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.


Widget(rect = None)
Creates 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 parent.


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.


When 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.

Whey 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.

Controls 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.

When 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.

Theme Properties

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.
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.

If 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)
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.
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.

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.

Returns 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.

Abstract Methods

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.
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.
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 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.

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.
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 the PyGame set_cursor() function, or None to use the standard arrow cursor. (The resource.get_cursor() function returns a suitable tuple.)
Called 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.

resized(dw, dh)
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.

parent_resized(dw, dh)
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.