Logo Search packages:      
Sourcecode: ocempgui version File versions  Download package

ocempgui::widgets::Renderer::Renderer Class Reference

Inherits ocempgui::access::IIndexable.

List of all members.


Detailed Description

Renderer () -> Renderer

A render engine, which can deal with events and sprites.

The Renderer class incorporates an event management system based on
the EventManager class from the ocempgui.events module and can
render widgets based on the BaseWidget class. It contains several
attributes and methods to create and manipulate a pygame window as
well as interfaces to support a higher range of accessibility
features such as keyboard navigation by implementing the IIndexable
interfaces.

The Renderer class can be used as standalone render engine and event
loop for a pygame application or be integrated in an existing loop
easily (which is exaplained below).

The 'title' attribute and set_title() method will set the caption
title of the pygame window. This works independant of if the
Renderer works in a standalon or integrated mode.

renderer.title = 'My title'
renderer.set_title ('Another title')

The 'screen' attribute and set_screen() method allow you to set up
the background surface the Renderer shall use for blitting
operations. This can be especially useful, if only portions of the
complete visible screen contain elements, which should be handled by
the Renderer and/or if the Renderer is not used as standalone render
engine. If you instead want to use the Renderer as standalone, the
create_screen() method should be used to create the pygame window
with the desired size.

# Screen already exists:
renderer.screen = mainscreen
renderer.set_screen (own_screen_portion)

# Renderer will be used as standalone render engine with a pygame
# window of 800x600 size.
renderer.create_screen (800, 600)

When using only a part of the screen it is important to adjust the
Renderer's position, too, so that events, which require positional
arguments (such as mouse movements, etc), can be translated
correctly. This means, that when the Renderer's screen is blit a
certain offset (x, y), its topleft position should be set to (x, y)
as well:

mainsurface.blit (renderer.screen, (10, 10))
renderer.topleft = 10, 10

As the Renderer exposes the attributes of its bound 'rect' attribute
you can use the following attributes directly to modify its position:

    top, left, bottom, right,
    topleft, bottomleft, topright, bottomright,
    midtop, midleft, midbottom, midright,
    center, centerx, centery,
    size, width, height

This however will NOT move the bound screen of the Renderer around.

If the create_creen() method is used, resizing events will be
recognized and resize the display accordingly. The 'support_resize'
attribute and set_support_resize() method can influence this
behaviour. It will be necessary to create the screen with the
pygame.RESIZEABLE flag enabled in order to retrieve resizing events.
'support_resize' will be automatically enabled anyways, if
create_screen() is used.

# Create a resizeable window - no need to set support_resize.
renderer.create_screen (200, 200, pygame.RESIZEABLE)

# Enable resizing support, if the screen is assigned manually.
renderer.support_resize = True
renderer.set_support_resize (True)

It is possible to set the background color of the set screen by
adjusting the 'color' attribute or set_color() method. By default it
uses a clear white color with the RBG value (255, 255, 255). It is
possible to change that value by any time. It will be applied
instantly.

renderer.color = (255, 0, 0)
renderer.set_color (100, 220, 100)

The Renderer supports an update timer value (~ FPS setting), which
defaults to 40. That means, that the timer will cause the default
event system to poll events 40 times a second, which is a good value
for most cases. On demand it can be adjusted using the 'timer'
attribute or set_timer() method. Be careful with it. Higher values
will cause higher CPU load.

renderer.timer = 20
renderer.set_timer (100)

It also supports different polling modes for events. The first
polling mode relies on the timer value while the second uses an
event based polling system. This means, that the second mode will
completely ignore the timer value and instead wait for events to
occur on the event queue. While the first mode is suitable for most
FPS based applications and games, the latter one suits perfectly for
event based ones.

Note however, that the events to occur _MUST_ occur on the pygame
event queue, not on those of the different EventManagers!

The mode can be chosen by passing the Renderer.start() method an
optional boolean argument, that determins, which mode should be
used. True indicates the event based loop, False (the default)
indicates the timer based loop.

renderer.start ()      # Use the timer based polling.
renderer.start (False) # Use the timer based polling.
renderer.start (True)  # Use the event based polling.

The Renderer supports temporary locking the update routines by using
the lock() and unlock() methods. Each lock() call however has to
be followed by a call to unlock(). You can check whether the Renderer
is currently locked by using its 'locked' attribute.

renderer.lock () # Note that an unlock() has to follow.
if renderer.locked:
    print 'The Renderer is currently locked'
renderer.unlock ()

To speed up the mouse interaction behaviour, you can adjust the
amount of mouse motion events to drop on each update the Renderer
performs. This usually increases the overall speed while decreasing
the exactness of mouse position related actions. You can adjust the
amount of mouse motion events to drop using the 'drops' attribute and
set_drops() method.

renderer.drops = 10 # Drop each 10th mouse motion event on updates.
renderer.set_drops (5)

Keyboard navigation
-------------------
The Renderer class implements keyboard navigation through the
ocempgui.access.IIndexable interface class. It uses the TAB key for
switching between attached objects of the currently active layer.
Objects can be attached and removed using the add_index() and
remove_index() method and will be automatically put into the
correct layer (Note: objects inheriting from the BaseWidget class
will do that automatically by default). Switching is done via
the switch_index() method, which will be activated automatically by
sending a KEYDOWN event with the TAB key as value.

Objects which should be added to the navigation indexing, need to
have a 'index' and 'sensitive' attribute and a set_focus() method,
which receives a bool value as argument and returns True on
successfully setting the focus or False otherwise. In case that
False will be returned the method will try to set the focus on the
next object.

The index is needed for the order the objects shall be navigated
through. Objects with a lower index will be focused earlier than
objects with a higher index. If multiple objects with the same index
are added, it cannot be guaranteed in which order they are
activated.

The active layer can be switched using the switch_layer() method,
which will be activated automatically by sending a KEYDOWN event
with the TAB key as value and CTRL as modifier. More information
about the layer system can be found in the 'Layer system' section
beneath.

The Renderer supports automatic cycling through the objects and
layers, which means, that if the end of the index list or layer list
is reached it will start from the beginning of the respective list.

Mnemonic support
----------------
The Renderer supports mnemonic keys (also known as hotkeys) for
object activation through the <ALT><Key> combination. If it receives
a KEYDOWN event, in which the ALT modifier is set, it will not
escalate the event to its children, but instead loop over its
indexing list in order to activate a matching child.

As stated in 'Keyboard Navigation' the objects need to have a
'sensitive' attribute. Additionally they must have an
activate_mnemonic() method, which receives a unicode as argument and
returns True on successful mnemonic activation or False
otherwise. If the widget's 'sensitive' attribute does not evaluate
to True, the Renderer will not try to invoke the activate_mnemonic()
method of the widget.

Layer system
------------
The Renderer contains full z-axis support by using different layers,
in which widgets will be kept and drawn. A higher layer index will
cause widgets to be drawn on top of others with a lower index.
The layer, in which a widget will be put, can be adjusted using the
'depth' attribute or set_depth() method of the BaseWidget class.

Each layer stored in the Renderer is a tuple consisting of three
values,

* an index list, which keeps a list of indexable objects for that
  layer (see the section 'Keyboard navigation' above for more),
* a widget list, which contains all the widgets and
* a specialized EventManager subclass, that will deal with the
  events sent to the specific layer.

The Renderer forwards received events to each layer starting
with the currently active layer and then in order from the highest
layer index (topmost layer) to the one with the lowest index
(=lowest depth).
The only exception from this behaviour is mouse input, which
alaways will be sent in order from the highest layer index to the
one with the lowest index.
if the sent event is handled by any object within that particular
layer and its 'handled' attribute is set to True, the event manager
and Renderer will stop passing the event around, so that neither
following widgets in that layer nor following layers will receive
the event.

Using the Renderer as standalone engine
---------------------------------------
Using the Renderer as standalone engine is very simple. You usually
have to type the following code to get it to work:

renderer = Renderer ()
renderer.create_screen (width, height, optional_flags)
renderer.title = 'Window caption title'
renderer.color = (100, 200, 100)
...
re.start ()

The first line will create a new Renderer object. The second creates
a new pygame window with the passed width and height. The third and
fourth line are not necessary, but useful and will set the window
caption of the pygame window and the background color to use for the
window.

After those few steps you can add objects to the Renderer via the
add_widget() method, use the inherited Group.add() method of the
pygame.sprite system or the add_object() method from the inherited
ocempgui.events.EventManager class.

When you are done with that, an invocation of the start() method
will run the event loop of the Renderer.

Integrating the Renderer in an existing environment
---------------------------------------------------
If an event loop and window already exists or an own event loop is
necessary, the Renderer can be integrated into it with only a few
lines of code. First you will need to set the screen, on which the
Renderer should blit its objects:

renderer = Renderer ()
renderer.screen = your_main_screen_or_surface

Note, that if the assigned scren is a surface, which will be blit at
a certain position x, y (e.g. mainscreen.blit (renderer.screen, (10, 10)),
the Renderer's screen offset values have to be adjusted, too:

Renderer.topleft = 10, 10 # Set both, x and y offset.
Renderer.x = 10           # Only x offset.
Renderer.y = 10           # Only y offset.

See above for the necessity of it.

Then you can send the events processed in your event loop to the
Renderer and its objects via the distribute_events() method:

def your_loop ():
    ...
    renderer.distribute_events (received_events)

Attributes:
title           - The title caption to display on the pygame window.
screen          - The surface to draw on.
timer           - Speed of the event and update loop. Default is 40 fps.
color           - The background color of the screen. Default is
                  (255, 255, 255).
managers        - The EventManager objects of the different layers.
active_layer    - The currently activated layer.
show_layer_info - Indicates, whether the layer information should be
                  shown on the screen when the layer is switched.
support_resize  - Indicates, whether resize events should be supported.
                  Default is False and automatically set to True,
                  if create_screen() is used.
locked          - Indicates, whether the Renderer is locked.
drops           - The mouse motion events to drop on each update.
rect            - The area occupied by the Renderer.
x, y, ...       - The Renderer allows to reposition itself through the
width, ...        various attributes offered by its rect attribute.
size       

Definition at line 139 of file Renderer.py.


Public Member Functions

def __init__
def add_index
def add_widget
def clear
def create_screen
def distribute_events
def get_managers
def initclass
def lock
def refresh
def remove_index
def remove_widget
def set_active_layer
def set_color
def set_drops
def set_screen
def set_show_layer_info
def set_support_resize
def set_timer
def set_title
def start
def switch_index
def switch_layer
def unlock
def update
def update_index
def update_layer

Public Attributes

 active_layer
 screen
 support_resize
 topleft

Static Public Attributes

tuple active_layer
tuple color
tuple drops
tuple initclass = classmethod(initclass)
tuple locked
tuple managers
tuple rect
tuple screen
tuple show_layer_info
tuple support_resize
tuple timer
tuple title

Private Member Functions

def _activate_mnemonic
def _add
def _check_doubleclick
def _create_bg
def _create_layer
def _destroy_layer
def _get_layers
def _get_rect
def _get_rect_attr
def _is_mod
def _loop
def _redraw_widgets
def _set_grab
def _set_rect_attr
def _show_layer_info
def _synced_loop

Private Attributes

 __flags
 __layerinfo
 __updateevent
 _activelayer
 _background
 _color
 _drops
 _grabber
 _indexwidget
 _layers
 _lock
 _mouseinfo
 _rect
 _screen
 _showlayerinfo
 _supportresize
 _timer
 _title

The documentation for this class was generated from the following file:

Generated by  Doxygen 1.6.0   Back to index