class widget.Widget

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.

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.

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.

Constructor

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

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.

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.

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.

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