class widget.Widget(object)

The Widget class is the base class for all widgets. A widget occupies a rectangular area of the PyGame screen to which all drawing in it is clipped, and it may receive mouse and keyboard events. A widget may also contain subwidgets.

NOTE: Due to a limitation of PyGame subsurfaces, a widget's rectangle must be entirely contained within that of its parent widget. An exception will occur if this is violated.

Constructor

Widget(rect = None)
Creates a new widget, initially without any parent. If a rect is given, it becomes the new widget's rectangle.

WARNING: If you pass a Rect object for the rect parameter, it is not copied. Since pygame Rects are mutable, this is something to be careful about.

Attributes

rect
A PyGame rectangle defining the portion of the parent widget's coordinate system occupied by the widget. Modifying this rectangle changes the widget's size and position.

parent
Read-only. The widget having this widget as a subwidget, or None if the widget is not contained in another widget. A widget must ultimately be contained in the root widget in order to be drawn and to receive events.
visible
When true, the widget is visible and active. When false, the widget is invisible and will not receive events. Defaults to true.

Theme Properties

fg_color
Foreground colour for the contents of the widget. How this property is used depends on the widget. Some widgets have additional colour properties for specific parts of the widget.
bg_color
Background colour of the widget. If specified, the widget's rect is filled with this colour before drawing its contents. If no background colour is specified or it is set to None, the widget has no background and is drawn transparently over its parent. For most widgets, it defaults to None.
font
Font to use for drawing text in the widget. How this property is used depends on the widget. Some widgets have additional font properties for specific parts of the widget.
border_width
Width of a border to be drawn inside the outer edge of the widget. If this is unspecified or set to zero, no border is drawn.
border_color
Colour in which to draw the border specified by border_width.
margin
The amount of space to leave between the edge of the widget and its contents. Note that this distance includes the border_width, e.g. if border_width == 1 and margin == 3, then there is 2 pixels of space between the inside of the border and the contents.

Most of the predefined Albow widgets honour the margin property, but this is not automatic for your own widget subclasses. You may find the get_margin_rect() method helpful in implementing support for the margin property in your widget classes.

Methods

add(subwidget)
Adds the given widget as a subwidget of this widget.

remove(subwidget)
If the given widget is a subwidget of this widget, it is removed and its parent attribute is set to None.

set_parent(self, parent)
Changes the parent of this widget to the given widget. This is an alternative to using the add and remove methods of the parent widget. Setting the parent to None removes the widget from any parent.

call_handler(self, name, *args)
If the widget has a method with the given name, it is called with the given args, and True is returned. Otherwise, nothing is done and False is returned.

call_parent_handler(self, name, *args)
Invokes call_handler on the parent of this widget, if any. This can be used to pass an event on to a parent widget if you don't want to handle it.

global_to_local(coords)
Converts the given coordinate pair from PyGame screen coordinates to the widget's local coordinate system.

local_to_global(coords)
Converts the given coordinate pair from the widget's local coordinate system to PyGame screen coordinates.

present()
Presents the widget as a modal dialog. The widget is added as a subwidget of the root widget and centered within it, and a nested event loop is entered in which any events for widgets other than this widget and its subwidgets are ignored. Control is retained until this widget's dismiss method is called. The argument to dismiss is returned from the present call.

dismiss(result)
When the widget is being presented modally using present(), causes the modal event loop to exit and the present() call to return with the given result.

get_root()
Returns the root widget (whether this widget is contained within it or not).

focus()
Gives this widget the keyboard focus. The widget must be visible (i.e. contained within the root widget) for this to have any effect.

has_focus()
Returns true if the widget currently has the keyboard focus.
get_margin_rect()
Returns a Rect in local coordinates representing the content area of the widget, as determined by its margin property.
set_size_for_text(width, nlines = 1)
Sets the widget's Rect to a suitable size for displaying text of the specified width and number of lines in its current font, as determined by the font property. The width can be either a number of pixels or a piece of sample text.
invalidate()
Marks the widget as needing to be redrawn. You will need to call this from the begin_frame() method of your Shell or Screen if you have the redraw_every_frame attribute of the root widget set to False.

NOTE: Currently, calling this method on any widget will cause all widgets to be redrawn on next return to the event loop. Future versions may be more selective.

Abstract Methods

draw(surface)
Called whenever the widget's contents need to be drawn. The surface is a subsurface the same size as the widget's rect with the drawing origin at its top left corner.

The widget is filled with its background colour, if any, before this method is called. The border and subwidgets, if any, are drawn after this method returns.
draw_over(surface)
Called after drawing all the subwidgets of this widget. This method can be used to draw content that is to appear on top of any subwidgets.
mouse_down(event)
Called when a mouse button press event occurs in the widget.

mouse_drag(event)
Called when a mouse movement event occurs with a mouse button held down following a mouse-down event in this widget.

mouse_up(event)
Called when a mouse button release event occurs following a mouse-down event in this widget.

mouse_move(event)
Called when a mouse movement event occurs in this widget with no mouse button down.

key_down(event)
Called when a key press event occurs and this widget has the keyboard focus, or a subwidget has the focus but did not handle the event.

NOTE: If you override this method and don't want to handle a key_down event, be sure to call the inherited key_down() method to pass the event to the parent widget.

key_up(event)
Called when a key release event occurs and this widget has the keyboard focus.

NOTE: If you override this method and don't want to handle a key_up event, be sure to call the inherited key_up() method to pass the event to the parent widget.
get_cursor(event)
Called to determine the appropriate cursor to display over the widget. The event is an event object containing the mouse coordinates to be used in determining the cursor. Should return a cursor in the form of a tuple of arguments to set_cursor(), or None to use the standard arrow cursor. (The get_cursor() resource function returns a suitable tuple.)
---