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
- Widget(rect = None)
a new widget, initially without any parent. If a rect is given, it
specifies the new widget's initial size and position relative to its
- 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.
- left, right, top, bottom, width, height, size,
- topleft, topright, bottomleft, bottomright,
midleft, midright, midtop, midbottom,
- center, centerx, centery
- Reading these attributes retrieves the corresponding values from the widget's rect.
Assigning to them changes the size and position of the widget.
Additionally, if the size of the widget is changed via these
attributes, the size and position of its subwidgets is updated
according to each subwidget's anchor attribute. (This does not happen if the rect is modified directly.)
- 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.
- True if this widget should receive the keyboard focus when the user presses the Tab key. Defaults to false.
- A string specifying how this widget is to change in size and position when its parent widget changes size. The letters 'l', 'r', 't' and 'b'
are used to anchor the widget to the left, right, top or bottom sides
of its parent. Anchoring it to both left and right, or both top and
bottom, causes the widget to stretch or shrink when its parent changes
in width or height.
true, the widget is visible and active. When false, the widget is
invisible and will not receive events. Defaults to true. The behaviour
of this property can be customized by overriding the get_visible method.
- A MenuBar
to be attached to and managed by this widget. Assigning to the menu_bar
property automatically adds the menu bar as a child widget. Also, if
the width of the menu bar has not already been set, it is set to be the
same width as this widget and to stretch horizontally with it.
a key down event with the platform's standard menu command modifier
(Command on Mac, Control on other platforms) is dispatched through this
widget, the menu bar is first given a chance to handle the event. If
the menu bar does not handle it, dispatching continues as normal.
the drawing behaviour of the widget when used in an OpenGL window. When
true, no 2D drawing is performed for the widget itself -- its
background colour and border properties are ignored, and its draw() and draw_over() methods are never called. If it has 3D subwidgets, 3D drawing is performed for them.
false, the widget and its subwidgets are rendered to a temporary
surface which is then drawn to the window using glDrawPixels() with
blending. No 3D drawing is performed for any of its subwidgets.
In either case, input events are handled in the usual way.
This property has no effect on widgets in a non-OpenGL window.
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.
- 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.
- An image to be displayed in the background. If specified, this overrides any bg_color.
true, and the background image is smaller than the widget in either
direction, the background image is scaled to fill the widget, otherwise
it is centered. Note: Due to
a limitation of the pygame rotozoom function, scaling is currently
uniform in both directions, with the scale factor being that required
to ensure that the whole widget is covered.
- 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.
- 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.
- Colour in which to draw the border specified by border_width.
- 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.
- event in widget
- Returns true if the mouse position of the given event is within the widget.
- Adds the given widget or sequence of widgets as a subwidget of this widget.
- Adds the given widget and positions it in the centre of this widget.
- 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 its return value is returned. Otherwise, nothing is done and 'pass' 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.
- Converts the given coordinate pair from PyGame screen coordinates to the widget's local coordinate system.
- Converts the given coordinate pair from the widget's local coordinate system to PyGame screen coordinates.
- present(centered = True)
- Presents the widget as a modal dialog. The widget is added as a
subwidget of the root widget, centered within it if centered is true. 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.
- 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.
- Returns the root widget (whether this widget is contained within it or not).
- Gives this widget the keyboard focus. The widget must be visible
(i.e. contained within the root widget) for this to have any effect.
- Returns true if the widget is on the focus path, i.e. this widget or one of its subwidgets currently has the keyboard focus.
- If this widget or one of its subwidgets has the keyboard focus, returns that widget. Otherwise it returns the widget that would have the keyboard focus if this widget were on the focus path.
- 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)
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.
- 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.
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
- Looks up the parent hierarchy to find the first widget that has an attribute with the given name, and returns its value. If not found, returns None.
the highest widget in the containment hierarchy currently receiving
input events. If a modal dialog is in progress, the modal dialog widget
is the top widget, otherwise it is the root widget.
- Adds the specified options to the widget's anchor property.
- Removes the specified options from the widget's anchor property.
- 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.
widget is filled with its background colour, if any, before this method
is called. The border and subwidgets, if any, are drawn after this
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.
- Called when a mouse button press event occurs in the widget.
- Called when a mouse movement event occurs with a mouse button held down following a mouse-down event in this widget.
- Called when a mouse button release event occurs following a mouse-down event in this widget.
- Called when a mouse movement event occurs in this widget with no mouse button down.
- 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
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.
- 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.
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 the PyGame set_cursor() function, or None to use the standard arrow cursor. (The resource.get_cursor() function returns a suitable tuple.)
when the widget is on the focus path, and a mouse-down event occurs in
any widget which is not on the focus path. The focus path is defined as
the widget having the keyboard focus, plus any widgets on the path from
there up the parent hierarchy to the root widget. This method can be
useful to ensure that changes to a data structure being edited are
committed before performing some other action.
- Called when the widget changes size as a result of assigning to its width, height or size attributes, with (dw, dh) being the amount of the change. The default is to call parent_resized on each of its subwidgets.
- Called when the widget's parent changes size as a result of assigning to its width, height or size attributes, with (dw, dh) being the amount of the change. The default is to resize and/or reposition the widget according to its anchor attribute.
- Called to determine the value of the visible property. By overriding this, you can make the visibility of the widget dependent on some external condition.