Widget

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

tab_stop

True if this widget should receive the keyboard focus when the user presses the Tab key. Defaults to false.

anchor

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.

Properties

Theme Properties

Operations

Methods

add(widget) add(widgets): Adds the given widget or sequence of widgets as a subwidget of this widget.
add_centered(widget): Adds the given widget and positions it in the centre of this widget.
remove(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.
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(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.
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 is on the focus path, i.e. this widget or one of its subwidgets currently has the keyboard focus.
get_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.

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.
inherited(name): 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.
get_top_widget(): 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.
add_anchor(options): Adds the specified options to the widget's anchor property.
remove_anchor(options): Removes the specified options from the widget's anchor property.

Abstract Methods

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