Home       Trees       Index       Help   
Package ocempgui :: Package widgets :: Module BaseWidget :: Class BaseWidget
[show private | hide private]
[frames | no frames]

Type BaseWidget

 object --+        
          |        
INotifyable --+    
              |    
     BaseObject --+
                  |
     object --+   |
              |   |
         Sprite --+
                  |
                 BaseWidget

Known Subclasses:
Bin, Container, Diagram, Editable, ImageLabel, Label, ProgressBar, Range, TooltipWindow
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
Method Summary
  __init__(self)
  activate(self)
W.activate () -> None
  activate_mnemonic(self, mnemonic)
W.activate_mnemonic (...) -> bool
  check_sizes(self, width, height)
W.check_sizes (...) -> int, int
  create_style(self)
W.create_style () -> WidgetStyle
  debug_update(self)
For debugging usage only
  destroy(self)
W.destroy () -> None
  draw(self)
W.draw () -> None
  draw_bg(self)
W.draw_bg () -> Surface
  get_style(self)
W.get_style () -> WidgetStyle
  initclass(cls)
B.initclass () -> None (Class method)
  lock(self)
W.lock () -> None
  notify(self, event)
W.notify (...) -> None
  rect_to_client(self, rect)
W.rect_to_client (...) -> pygame.Rect
  set_depth(self, depth)
W.set_depth (...) -> None
  set_dirty(self, dirty, update)
W.set_dirty (...) -> None
  set_entered(self, entered)
W.set_entered (...) -> None
  set_event_area(self, area)
W.set_event_area (...) -> None
  set_event_manager(self, manager)
W.set_event_manager (...) -> None
  set_focus(self, focus)
W.set_focus (...) -> bool
  set_index(self, index)
W.set_index (...) -> None
  set_indexable(self, indexable)
W.set_indexable (...) -> None
  set_maximum_size(self, width, height)
W.set_maximum_size (...) -> None
  set_minimum_size(self, width, height)
W.set_minimum_size (...) -> None
  set_opacity(self, opacity)
W.set_opacity (...) -> None
  set_position(self, x, y)
W.set_position (...) -> None
  set_sensitive(self, sensitive)
W.set_sensitive (...) -> None
  set_size(self, width, height)
W.set_size (...) -> None
  set_state(self, state)
W.set_state (...) -> None
  set_style(self, style)
W.set_style (...) -> None
  set_tooltip(self, tooltip)
W.set_tooltip (...) -> None
  unlock(self)
W.unlock () -> None
  update(self, **kwargs)
W.update (...) -> None
    Inherited from BaseObject
  connect_signal(self, signal, callback, *data)
B.connect_signal (...) -> EventCallback
  disconnect_signal(self, event)
B.disconnect_signal (...) -> None
  emit(self, signal, data)
B.emit (...) -> bool
  run_signal_handlers(self, signal, *data)
B.run_signal_handlers (...) -> None
    Inherited from Sprite
  __repr__(self)
  add(self, *groups)
add(group or list of of groups, ...) add a sprite to container
  add_internal(self, group)
  alive(self)
alive() -> bool check to see if the sprite is in any groups
  groups(self)
groups() -> list of groups list used sprite containers
  kill(self)
kill() remove this sprite from all groups
  remove(self, *groups)
remove(group or list of groups, ...) remove a sprite from container
  remove_internal(self, group)
    Inherited from object
  __delattr__(...)
x.__delattr__('name') <==> del x.name
  __getattribute__(...)
x.__getattribute__('name') <==> x.name
  __hash__(x)
x.__hash__() <==> hash(x)
  __new__(T, S, ...)
T.__new__(S, ...) -> a new object with type S, a subtype of T
  __reduce__(...)
helper for pickle
  __reduce_ex__(...)
helper for pickle
  __setattr__(...)
x.__setattr__('name', value) <==> x.name = value
  __str__(x)
x.__str__() <==> str(x)

Property Summary
  bottom
  bottomleft
  bottomright
  center
  centerx
  centery
  controls: Widgets associated with the widget.
  depth: The z-axis layer depth of the widget.
  dirty: Indicates, whether the widget need to be redrawn.
  entered: Indicates, whether the widget is entered.
  eventarea: The area, which gets the events.
  focus: The focus of the widget.
  h
  height
  image: The visible surface of the widget.
  index: The tab index position of the widget.
  indexable: The IIndexable, the widget is attached to.
  left
  locked: Indicates, whether the widget is locked.
  maxsize: The maximum size to occupy by the widget.
  midbottom
  midleft
  midright
  midtop
  minsize: The guaranteed size of the widget.
  opacity: The opacity of the widget.
  position: The position of the topleft corner.
  rect: The area occupied by the widget.
  right
  sensitive: The sensitivity of the widget.
  size
  state: The current state of the widget.
  style: The style of the widget.
  tooltip: The tool tip text to display for the widget.
  top
  topleft
  topright
  w
  width
  x
  y
    Inherited from BaseObject
  manager: The event manager to use by the object.

Instance Method Details

activate(self)

W.activate () -> None

Activates the widget.

Activates the widget, which means, that the default action of the widget will be invoked.

This method should be implemented by inherited widgets.

activate_mnemonic(self, mnemonic)

W.activate_mnemonic (...) -> bool

Activates the widget through the set mnemonic.

Activates the widget through the set mnemonic for it and returns True upon successful activation or False, if the widget was not activated.

The BaseWidget.activate_mnemonic () method always returns False by default, so that this method should be implemented by inherited widgets, if they need explicit mnemonic support.

check_sizes(self, width, height)

W.check_sizes (...) -> int, int

Checks the passed width and height for allowed values.

Checks, whether the passed width an height match the upper and lower size ranges of the widget and returns corrected values, if they exceed those. Else the same values are returned.

create_style(self)

W.create_style () -> WidgetStyle

Creates the instance-specific style for the widget.

Gets the style associated with the widget. If the widget had no style before, a new one will be created for it, based on the class name of the widget. The style will be copied internally and associated with the widget, so that modifications on it will be instance specific.

More information about how a style looks like and how to modify them can be found in the Style class documentation.

debug_update(self)

For debugging usage only

destroy(self)

W.destroy () -> None

Destroys the widget and removes it from its event system.

Causes the widget to destroy itself as well as its controls and removes all from the connected event manager and sprite groups using the sprite.kill() method.
Overrides:
ocempgui.object.BaseObject.BaseObject.destroy

draw(self)

W.draw () -> None

Draws the widget surface.

Creates the visible surface of the widget and updates its internals.

draw_bg(self)

W.draw_bg () -> Surface

Draws the widget background surface and returns it.

Creates the visible background surface of the widget and returns it to the caller.

This method has to be implemented by inherited widgets.

get_style(self)

W.get_style () -> WidgetStyle

DEPRECATED - use the create_style() method instead

lock(self)

W.lock () -> None

Acquires a lock on the Widget to suspend its updating methods.

notify(self, event)

W.notify (...) -> None

Notifies the widget about an event.

Note: Widgets, which are not visible (not shown) or are in a specific state (e.g. STATE_INSENSITIVE), usually do not receive any events. But dependant on the widget, this behaviour can be different, thus checking the visibility depends on the widget and implementation.
Overrides:
ocempgui.events.INotifyable.INotifyable.notify

rect_to_client(self, rect=None)

W.rect_to_client (...) -> pygame.Rect

Returns the absolute coordinates a rect is located at.

In contrast to the widget.rect attribute, which denotes the relative position and size of the widget on its parent, this method returns the absolute position and occupied size on the screen for a passed rect.

Usually this method will be called by children of the callee and the callee itself to detrmine their absolute positions on the screen.

set_depth(self, depth)

W.set_depth (...) -> None

Sets the z-axis layer depth for the widget.

Sets the z-axis layer depth for the widget. This will need a renderer, which makes use of layers such as the Renderer class. By default, the higher the depth value, the higher the drawing layer of the widget is. That means, that a widget with a depth of 1 is placed upon widgets with a depth of 0.

Raises a TypeError, if the passed argument is not an integer.

set_dirty(self, dirty, update=True)

W.set_dirty (...) -> None

Marks the widget as dirty.

Marks the widget as dirty, so that it will be updated and redrawn.

set_entered(self, entered)

W.set_entered (...) -> None

Sets the widget into an entered mode.

set_event_area(self, area)

W.set_event_area (...) -> None

DEPRECATED - this is no longer used.

set_event_manager(self, manager)

W.set_event_manager (...) -> None

Sets the event manager of the widget and its controls.

Adds the widget to an event manager and causes its controls to be added to the same, too.
Overrides:
ocempgui.object.BaseObject.BaseObject.set_event_manager

set_focus(self, focus=True)

W.set_focus (...) -> bool

Sets the input and action focus of the widget.

Sets the input and action focus of the widget and returns True upon success or False, if the focus could not be set.

set_index(self, index)

W.set_index (...) -> None

Sets the tab index of the widget.

Sets the index position of the widget to the given value. It can be used by ocempgui.access.IIndexable implementations to allow easy navigation access and activation for the widgets.

Raises a TypeError, if the passed argument is not a positive integer.

set_indexable(self, indexable)

W.set_indexable (...) -> None

Sets the IIndexable for the widget.

The widget will invoke the add_index() method for itself on the IIndexable.

set_maximum_size(self, width, height)

W.set_maximum_size (...) -> None

Sets the maximum size the widget is allowed to occupy.

This is the counterpart to the set_minimum_size() method.

set_minimum_size(self, width, height)

W.set_minimum_size (...) -> None

Sets the minimum size to occupy for the widget.

Minimum size means that the widget can exceed the size by any time, but its width and height will never be smaller than these values.

Raises a TypeError, if the passed arguments are not integers. Raises a ValueError, if the passed arguments are not positive.

set_opacity(self, opacity)

W.set_opacity (...) -> None

Sets the opacity of the widget.

set_position(self, x, y)

W.set_position (...) -> None

DEPRECATED - use the 'topleft' attribute instead

set_sensitive(self, sensitive=True)

W.set_sensitive (...) -> None

Sets the sensitivity of the widget.

In a sensitive state (the default), widgets can react upon user interaction while they will not do so in an insensitive state.

To support the visibility of this, the widget style should support the STATE_INSENSITIVE flag, while inheriting widgets should check for the sensitivity to enable or disable the event mechanisms.

set_size(self, width, height)

W.set_size (...) -> None

DEPREACATED - use set_minimum_size () instead.

set_state(self, state)

W.set_state (...) -> None

Sets the state of the widget.

Sets the state of the widget. The state of the widget is mainly used for the visible or non-visible appearance of the widget, so that the user can determine the state of the widget easier. Usually this method should not be invoked by user code.

Raises a ValueError, if the passed argument is not a value of the STATE_TYPES tuple.

set_style(self, style)

W.set_style (...) -> None

Sets the style of the widget.

Sets the style of the widget to the passed style dictionary. This method currently does not perform any checks, whether the passed dictionary matches the criteria of the Style class.

Raises a TypeError, if the passed argument is not a WidgetStyle object.

set_tooltip(self, tooltip)

W.set_tooltip (...) -> None

Sets the tooltip information for the widget.

Raises a TypeError, if the passed argument is not a string or unicode.

unlock(self)

W.unlock () -> None

Releases a previously set lock on the Widget and updates it instantly.

update(self, **kwargs)

W.update (...) -> None

Updates the widget.

Updates the widget and causes its parent to update itself on demand.
Overrides:
pygame.sprite.Sprite.update

Class Method Details

initclass(cls)

B.initclass () -> None

Class method to expose the attributes of the own self.rect attribute.

The method usually is called in the __init__.py script of the module.

Property Details

bottom

Get Method:
get_attr(...)
Set Method:
set_attr(...)

bottomleft

Get Method:
get_attr(...)
Set Method:
set_attr(...)

bottomright

Get Method:
get_attr(...)
Set Method:
set_attr(...)

center

Get Method:
get_attr(...)
Set Method:
set_attr(...)

centerx

Get Method:
get_attr(...)
Set Method:
set_attr(...)

centery

Get Method:
get_attr(...)
Set Method:
set_attr(...)

controls

Widgets associated with the widget.
Get Method:
unknown-696294620(...)

depth

The z-axis layer depth of the widget.
Get Method:
unknown-696294676(...)
Set Method:
unknown-696294732(...)

dirty

Indicates, whether the widget need to be redrawn.
Get Method:
unknown-696294508(...)
Set Method:
unknown-696294564(...)

entered

Indicates, whether the widget is entered.
Get Method:
unknown-696295068(...)
Set Method:
unknown-696295124(...)

eventarea

The area, which gets the events.
Get Method:
unknown-696293500(...)
Set Method:
unknown-696293556(...)

focus

The focus of the widget.
Get Method:
unknown-696294284(...)
Set Method:
unknown-696294340(...)

h

Get Method:
get_attr(...)
Set Method:
set_attr(...)

height

Get Method:
get_attr(...)
Set Method:
set_attr(...)

image

The visible surface of the widget.
Get Method:
unknown-696293836(...)

index

The tab index position of the widget.
Get Method:
unknown-696293948(...)
Set Method:
unknown-696294004(...)

indexable

The IIndexable, the widget is attached to.
Get Method:
unknown-696294956(...)
Set Method:
unknown-696295012(...)

left

Get Method:
get_attr(...)
Set Method:
set_attr(...)

locked

Indicates, whether the widget is locked.
Get Method:
unknown-696294900(...)

maxsize

The maximum size to occupy by the widget.
Get Method:
unknown-696293724(...)
Set Method:
unknown-696293780(...)

midbottom

Get Method:
get_attr(...)
Set Method:
set_attr(...)

midleft

Get Method:
get_attr(...)
Set Method:
set_attr(...)

midright

Get Method:
get_attr(...)
Set Method:
set_attr(...)

midtop

Get Method:
get_attr(...)
Set Method:
set_attr(...)

minsize

The guaranteed size of the widget.
Get Method:
unknown-696293612(...)
Set Method:
unknown-696293668(...)

opacity

The opacity of the widget.
Get Method:
unknown-696295180(...)
Set Method:
unknown-696295236(...)

position

The position of the topleft corner.
Get Method:
unknown-696293388(...)
Set Method:
unknown-696293444(...)

rect

The area occupied by the widget.
Get Method:
unknown-696293892(...)

right

Get Method:
get_attr(...)
Set Method:
set_attr(...)

sensitive

The sensitivity of the widget.
Get Method:
unknown-696294396(...)
Set Method:
unknown-696294452(...)

size

Get Method:
get_attr(...)
Set Method:
set_attr(...)

state

The current state of the widget.
Get Method:
unknown-696294172(...)
Set Method:
unknown-696294228(...)

style

The style of the widget.
Get Method:
unknown-696294060(...)
Set Method:
unknown-696294116(...)

tooltip

The tool tip text to display for the widget.
Get Method:
unknown-696294788(...)
Set Method:
unknown-696294844(...)

top

Get Method:
get_attr(...)
Set Method:
set_attr(...)

topleft

Get Method:
get_attr(...)
Set Method:
set_attr(...)

topright

Get Method:
get_attr(...)
Set Method:
set_attr(...)

w

Get Method:
get_attr(...)
Set Method:
set_attr(...)

width

Get Method:
get_attr(...)
Set Method:
set_attr(...)

x

Get Method:
get_attr(...)
Set Method:
set_attr(...)

y

Get Method:
get_attr(...)
Set Method:
set_attr(...)

   Home       Trees       Index       Help   
Generated by Epydoc 2.1 on Thu Jan 10 10:18:44 2008 http://epydoc.sf.net