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

ocempgui::widgets::BaseWidget::BaseWidget Class Reference

Inherits ocempgui::object::BaseObject.

List of all members.


Detailed Description

BaseWidget () -> BaseWidget

A basic widget class for user interface elements.

The BaseWidget is the most basic widget class, from which any other
widget class should be inherited. It provides the most basic
attributes and methods, every widget needs.

The widget is a visible (or non-vissible) element on the display,
which allows the user to interact with it (active or passive) in a
specific way. It has several methods and attributes to allow
developers to control this interaction and supports accessibility
through the ocempgui.access module.

The widget can be placed on the display by accessing the various
attributes of its 'rect' attribute directly. It exposes the following
pygame.Rect attributes:

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

Except the last three ones, 'size', 'width' and 'height' any of those
can be assigned similarily to the pygame.Rect:

widget.top = 10
widget.center = (10, 10)
...

Note: This will only work for toplevel widgets as widgets are placed
relative to their parent. Thus the 'top' attribute value of a
widget, which is packed into another one, refers to its parents
coordinates. So if it is placed four pixels to the left on its
parent, its 'top' value will be 4, while the parent might be placed
at e.g. 100, 100.
You can get the absolute coordinates, the widget is placed on the
display, by using the rect_to_client() method.

To get the actual dimensions of the widget, it provides the
read-only 'width', 'height' and 'size' attributes.

if (widget.width > 50) or (widget.height > 50):
    ...
if widget.size == (50, 50):
    ...

To force a specific minimum size to occupy by the widget, the
'minsize' attribute or the respective set_minimum_size() method can
be used. The occupied area of the widget will not be smaller than
the size, but can grow bigger.

widget.minsize = 100, 50
widget.set_minimum_size (10, 33)

The counterpart of 'minsize' is the 'maxsize' attribute, which
defines the maximum size, the widget can grow to. It will never
exceed that size.

widget.maxsize = 200, 200
wdget.set_maximum_size (100, 22)

The 'image' and 'rect' attributes are used and needed by the
pygame.sprite system. 'image' refers to the visible surface of the
widget, which will be blitted on the display. 'rect' is a copy of
the pygame.Rect object indicating the occupied area of the
widget. The rect denotes the relative position of the widget on its
parent (as explained above).

The 'index' attribute and set_index() method set the navigation
index position for the widget. It is highly recommended to set this
value in order to provide a better accessibility (e.g. for keyboard
navigation). The attribute can be used in ocempgui.access.IIndexable
implementations for example.

widget.index = 3
widget.set_index (0)

Widgets support a 'style' attribute and create_style() method, which
enable them to use different look than default one without the need
to override their draw() method. The 'style' attribute of a widget
usually defaults to a None value and can be set using the
create_style() method. This causes the widget internals to setup the
specific style for the widget and can be accessed through the
'style' attribute later on. A detailled documentation of the style
can be found in the Style class.

if not widget.style:
    widget.create_style () # Setup the style internals first.
widget.style['font']['size'] = 18
widget.create_style ()['font']['name'] = Arial

Widgets can be in different states, which cause the widgets to have
a certain behaviour and/or look. Dependant on the widget, the
actions it supports and actions, which have taken place, the state
of the widget can change. The actual state of the widget can be
looked up via the 'state' attribute and is one of the STATE_TYPES
constants.

if widget.state == STATE_INSENSITIVE:
    print 'The widget is currently insensitive and does not react.'

Any widget supports layered drawing through the 'depth' attribute.
The higher the depth is, the higher the layer on the z-axis will be,
on which the widget will be drawn. Widgets might use the flag to set
themselves on top or bottom of the display.

# The widget will be placed upon all widgets with a depth lower than 4.
widget.depth = 4
widget.set_depth (4)

Widgets should set the 'dirty' attribute to True, whenever an update
of the widget surface is necessary, which includes redrawing the
widget (resp. calling draw_bg() and draw()). In user code, 'dirty'
usually does not need to be modified manually, but for own widget
implementations it is necessary (e.g. if a Label text changed).
If the 'parent' attribute of the widget is set, the parent will be
notified automatically, that it has to update portions of its
surface.

# Force redrawing the widget on the next update cycle of the render
# group.
widget.dirty = True

Widgets support a focus mode, which denotes that the widget has the
current input and action focus. Setting the focus can be done via
the 'focus' attribute or the set_focus() method.

widget.focus = True
widget.set_focus (True)

'sensitive' is an attribute, which can block the widget's reaction
upon events temporarily. It also influences the look of the widget
by using other style values (see STATE_INSENSITIVE in the Style
class).

widget.sensitive = False
widget.set_sensitive (False)

Each widget supports transparency, which also includes all children
which are drawn on it. By setting the 'opacity' attribute you can
adjust the degree of transparency of the widget. The allowed values
are ranged between 0 for fully transparent and 255 for fully opaque.

widget.opacity = 100
widget.set_opacity (25)

Widgets allow parent-child relationships via the 'parent' attribute.
Parental relationships are useful for container classes, which can
contain widgets and need to be informed, when the widget is
destroyed, for example. Take a look the Bin and Container classes
for details about possible implementations.
Do NOT modify the 'parent' attribute value, if you do not know, what
might happen.

Widgets support locking themselves self temporarily using the lock()
method. This is extremely useful to avoid multiple update/draw
calls, when certain operations take place on it. To unlock the
widget, the unlock() method should be called, which causes it to
update itself instantly.

widget.lock ()            # Acquire lock.
widget.focus = False      # Normally update() would be called here.
widget.sensitive = False  # Normally update() would be called here.
widget.unlock ()          # Release lock and call update().

When using the lock() method in your own code, you have to ensure,
that you unlock() the widget as soon as you do not need the lock
anymore. The state of the lock on a widget can be queried using the
'locked' attribute:

if widget.locked:
    print 'The widget is currently locked'

Widgets can consist of other widgets. To guarantee that all of them
will be added to the same event management system, set the same
state, etc., the 'controls' attribute exists. It is a collection to
and from which widgets can be attached or detached. Several methods
make use of this attribute by iterating over the attached widgets
and invoking their methods to put them into the same state, etc. as
the main widget.

widget.controls.append (sub_widget)
for sub in widget.controls:
    ...

Default action (invoked by activate()):
None, will raise an NotImplementedError

Mnemonic action (invoked by activate_mnemonic()):
None

Signals:
SIG_FOCUSED   - Invoked, when the widget received the focus
                (widget.focus=True).
SIG_ENTER     - Invoked, when the input device enters the widget.
SIG_LEAVE     - Invoked, when the input device leaves the wigdet.
SIG_DESTROYED - Invoked, when the widget is destroyed.

Attributes:
minsize   - Guaranteed size of the widget.
maxsize   - Counterpart to size and denotes the maximum size the widget.
            is allowed to occupy. Defaults to None usually.
image     - The visible surface of the widget.
index     - Navigation index of the widget.
style     - The style to use for drawing the widget.
state     - The current state of the widget.
depth     - The z-axis layer depth of the widget.
dirty     - Indicates, that the widget needs to be updated.
focus     - Indicates, that the widget has the current input focus.
sensitive - Indicates, if the user can interact with the widget.
parent    - Slot for the creation of parent-child relationships.
controls  - Collection of attached controls for complex widgets.
tooltip   - The tool tip text to display for the widget.
opacity   - The degree of transparency to apply (0-255, 0 for fully
            transparent, 255 for fully opaque).
indexable - The ocempgui.access.IIndexable implementation to use for
            the 'index' attribute support.
entered   - Indicates, that an input device is currently over the widget
            (e.g. the mouse cursor).
locked    - Indicates, whether the widget is locked.
rect      - The area occupied by the widget.
x, y, ... - The widget allows to reposition itself through the various
width, ...  attributes offered by its rect attribute.
size       

Definition at line 38 of file BaseWidget.py.


Public Member Functions

def __init__
def activate
def activate_mnemonic
def check_sizes
def create_style
def destroy
def draw
def draw_bg
def get_style
def initclass
def lock
def notify
def rect_to_client
def set_depth
def set_dirty
def set_entered
def set_event_area
def set_event_manager
def set_focus
def set_index
def set_indexable
def set_maximum_size
def set_minimum_size
def set_opacity
def set_position
def set_sensitive
def set_size
def set_state
def set_style
def set_tooltip
def unlock
def update

Public Attributes

 dirty
 entered
 focus
 parent
 state

Static Public Attributes

tuple controls
tuple depth
tuple dirty
tuple entered
tuple eventarea
tuple focus
tuple image
tuple index
tuple indexable
tuple initclass = classmethod(initclass)
tuple locked
tuple maxsize
tuple minsize
tuple opacity
tuple position
tuple rect
tuple sensitive
tuple state
tuple style
tuple tooltip

Private Member Functions

def _get_rect
def _get_rect_attr
def _set_rect_attr

Private Attributes

 _bg
 _controls
 _depth
 _dirty
 _entered
 _focus
 _image
 _index
 _indexable
 _lock
 _maxheight
 _maxwidth
 _minheight
 _minwidth
 _oldrect
 _opacity
 _rect
 _sensitive
 _state
 _style
 _tooltip

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

Generated by  Doxygen 1.6.0   Back to index