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.
• highlight (boolean) – If True, style names will be prefixed with active_ on mouse over or dragging. Defaults to False.

blit(screen)

Parameter:screen (pygame.Surface) – Surface to blit the widget onto. Return type:list Returns:A list that contains either a Rect if the Widget was changed or None. Can be passed to pygame.display.update.

Blit the widget onto a surface. Normally this will be called by the parent Widget only.

blit_widget(styles)

Parameter:styles (dict) – Style attributes used to blit the widget. Return type:list Returns:List of dirty rects

reblit self.image. You should use attributes from styles only.

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_styles()

Return type:dict Returns:all styles and attributes used to blit the widget and that may change

return value will be passed to update_widget().

By default, this returns a dict with all styles with stylenames in used_syles

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.

Todo

test for performance issures

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.

localize_rect(rect, rel=None)

Parameters:

• rect (pygame.Rect) – Rect to localize.
• rel (pygame.Rect or None) – Rect to use as origin. Defaults to self.parent.get_rect()

Return type:

pygame.Rect

Returns:

Localized rect.

Turns a global rect into a local one (ie. relative rel).

mark_dirty()

Mark Widget as dirty.

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_widget()

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

used_styles

This should be a complete list of names of style attributes that you will use. If this is too generic, overwrite Widget.get_styles()

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.

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_widgets(point)

Parameter:point (Tuple) – A point (x, y) on the pygame screen. Return type:list Returns:Widgets at point, topmost at the end

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.

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={}, pass_events=True)

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.

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 or None) – Widget that was clicked or otherwise selected.

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