gui.base Api

Widget

class gui.base.Widget(parent, size, pos, anchor='topleft', index='end', style={}, **kwargs)

Bases: object

Base class of all GUI elements.

Parameters:

• parent (Layer) – Parent widget
• size (Size) – Size of the widget.
• pos (Position) – Position of the widget. (Note the anchor attribute, too.)
• anchor (String) – The point that should be used for positioning. Must be one of the pygame.Rect attributes (topleft, midtop, center, ...)
• index (int or “end”) – Index that will be used when adding the widget to the parent widget (via Layer.add()). The rearmost position is at index 0, the topmost position at "end" (default).
• visible (boolean) – Whether the widget should be visible or not. Defaults to True.
• validate_pos (boolean) – If True, the widget cannot tower above the parent. This will affect moving and resizing of the widget.
• min_size (Size) – Minimum size for the widget. Defaults to ("1px, "1px").
• max_size (Size) – Maximum size for the widget. Defaults to ("100%", "100%").
• style (Style or dict) – Widget specific style attributes. Fallback defaults to the main GUI style.
• style_class_name (String) – Prefix used by Style when searching for a style attribute. See documentation on Styling.

blit(screen)

Parameter:screen (pygame.Surface) – Surface to blit the widget on.

Overwrite this method and blit the widget, but call Widget.blit() there.

See Writing Custom Widgets.

blit_image(screen)

Return type:pygame.Rect Returns:Dirty rect

Get “image” from the style object and blit it centered.

collide_point(point)

Parameter:point (Tuple) – A point (x, y) on the pygame screen. Return type:boolean Returns:Whether the point touches the widget. By default, this simply uses self.rect.collidepoint.

Overwrite this method to get more accurate mouse events for non-rectangular widgets.

get_gui()

Return type:GUI Returns:the main GUI instance that contains this widget.

Get the topmost GUI widget.

get_suffix(style_name)

Parameter:style_name (String) – Name of a requested style attribute. Return type:String Returns:Style name suffix.

Return a string that will be added to style_name before searching for the style attribute. See docs on Styling.

get_widget(point)

Parameter:point (Tuple) – A point (x, y) on the pygame screen. Return type:Widget or False Returns:Topmost widget at this point.

Get the topmost widget at a certain point.

handle_events(events)

Parameter:events (list) – pygame events that may be used Return type:list Returns:pygame events that were not used

Overwrite this method to process raw pygame events.

hide()

Hide the widget if it is visible.

listen(event_name, callback)

Parameters:

• event_name (String) – Name of an event this widget raises
• callback (callable) – Method or function that should accept any keyword arguments (**kwargs).

Add an event listener. See the event documentation.

move(offset)

Parameter:offset (Tuple) – Offset between old and new position. This can have the same format like a normal position (eg. "40px", "20%", 80), but the values can be positive or negative.

Move the widget. This will not change the units of the current position.

resize(amount, anchor=None)

Parameter:anchor – anchor for the resize. Eg set it to "topright" if you want to move the bottomright corner.

Resize the widget. If amount is not possible, it will resize as far as possible.

set_abs_pos(pos)

Parameter:pos (Tuple) – Absolute pixel position of the topleft widget corner with the topleft corner of the screen as point of origin.

Set the widgets topleft position. This won’t change the position unit. If the position is not reachable, the nearest possible position will be used.

set_size(new_size, anchor=None)

Not yet implemented.

Todo

Implement Widget.set_size()

show()

Show the widget if it is hidden.

toggle()

Toggle visibility.

unlisten(event_name, callback)

Parameters:

• event_name (String) – Name of the event the handler is listening to.
• callback (callable) – The registered event handler.

Remove a previously registered event handler. For more see the event documentation.

update(events)

Parameter:events (list) – pygame events that may be used Return type:list Returns:pygame events that were not used

Process events and update the widget.

update_cache()

update cached values and styles.

update_widget()

Overwrite this method and update the widget. This method will be called once per frame.

focusable

If False, the widget will be unable to take the focus. Otherwise, focused will be set to True if the widget was clicked. Defaults to True.

pass_events

If True, the widget will pass all events. This means, events may be used more than once. Defaults to False.

pos

Position of the widget. When setting, it is a pair of x and y coords relative to the parent layers topleft corner. Either absolute pixel values (eg. "30px") or relative to the parent size (eg. "50%"). When getting, it will be the absolute position on the pygame screen.

For more see the position documentation.

rect

A rect containing this widget. This is a read-only property, build from size and pos. To change the position of the widget use its pos (and size and anchor) attributes. Changing the rect will not affect the widget position.

size

Size of the widget. When setting, it is a pair of width and height. Either absolute pixel values (eg "30px") or relative to the parent size (eg. "50%"). When getting, it will be the absolute width and hight.

For more see the size documentation.

style_class_name

Class name that will be used to get per-class styles (case insensitive). If it is None (which is the default), the class name will be used. This may be useful for inherited classes that should belong to the same style class group like their parent class. See Styling .. note:

Since this is a normal class attribute, this will be inherited
to all child classes. So only use when required.

Layer

class gui.base.Layer(parent, size=None, pos=(0, 0), **kwargs)

Bases: gui.base.Widget

A Layer is a Widget that can contain other widgets (and Layers, since Layer is a child class of Widget). You can use Layers either as a frame, ie. to gorup different widgets, or to build own superwidgets, ie. widgets that contain other widgets. Child widgets cannot overlap a Layer, they must be completely contained.

The arguments are the same like for Widget. Only that size will be set to the size of the parent widget and pos to (0, 0) by default.

add(widget, index='end', send_event=True)

Parameters:

• widget (Widget) – A Widget to add to the Layer.
• index (int or "end") – Index of the new Widget in the Widget list. The rearmost position is at index 0, the topmost position at "end" (default).
• send_event (boolean) – Whether a "widget_added" event should be send. Default is True.

Add a Widget at the given index to the Layer.

blit(screen)

Parameter:screen (pygame.Surface) – Surface on which to blit. Return type:list Returns:Rects that need to be updated (dirty rects).

Blit the Layer and all its child Widgets, from background to foreground.

change_index(widget, new_index='end')

Parameters:

• widget (Widget) – A child Widget of the Layer.
• new_index (int or "end") – The new index for the Widget.

Change the index of a child Widget.

get_index(widget)

Parameter:widget (Widget) – A child Widget of the Layer. Return type:int Returns:Index of the given Widget.

get_rect(widget)

Parameter:widget (Widget) – A child widget. Return type:pygame.Rect Returns:The Inner Rects for the widget.

Todo

document “borderwidth” standard syle attribute

get_widget(point)

Parameter:point (Tuple) – A point (x, y) on the pygame screen. Return type:Widget or False Returns:Topmost widget at this point.

Get the topmost widget at a certain point.

rel_chage_index(widget, amount)

Parameters:

• widget (Widget) – A child Widget of the Layer.
• amount (int) – Distance form the current index. Positive and negative values are possible. The new index will be current index + amount.

Change the index of a child Widget relatively to its current index.

remove(widget, send_event=True)

Parameters:

• widget (Widget) – A Widget to remove from the Layer.
• send_event (boolean) – Whether a "widget_removed" event should be send. Default is True.

Remove a Widget from the Layer.

update(events)

Parameter:events (list) – Pygame events since the last frame that were not yet used Returns:list of events that were not used and can be passed to the next widget

Update all children, from foreground to background, then the Layer itself.

update_cache()

update cached values and styles.

widget_down(widget)

Shortcut for rel_change_index(). Moves a child widget one position backward.

widget_up(widget)

Shortcut for rel_change_index(). Moves a child widget one position forward.

GUI

class gui.base.GUI(size, pos=(0, 0), style={})

Bases: gui.base.Layer

GUI is the topmost Layer and the only :class`Widget` that has no parent. Thus, you need a GUI before you can create other Widgets.

Parameters:

• size (Tuple) – Absolute size of the GUI.
• pos (Tuple) – Absolute position of the GUI on the pygame screen. Defaults to (0, 0).

get_gui()

Return type:GUI Returns:self

Hook for child Widgets to get the topmost GUI instance.

get_widget(point)

Parameter:point (Tuple) – A point (x, y) on the pygame screen. Return type:Widget Returns:Topmost widget at this point.

Get the topmost widget at a certain point. This will always return a widget.

handle_events(events)

Tpye events:list Parameter:events – Pygame events to process. Returns:List of pygame events that were not used.

Resize the GUI on pygame.VIDEORESIZE.

Todo

Make this optional. This ignores the current size and pos.

set_focus(widget)

Parameter:widget (Widget) – Widget that was clicked or otherwise selected.

Set the focus to a new Widget. If Widget is not focusable, the focus will be set to None.