Widget

class pygamelib.gfx.ui.Widget(width: int = 0, height: int = 0, minimum_width: int = 0, minimum_height: int = 0, maximum_width: int = 20, maximum_height: int = 10, layout: Layout | None = None, bg_color: Color | None = None, config: UiConfig | None = None)

Bases: PglBaseObject

New in version 1.4.0.

The Widget object is the base for all UI elements (or should be). By itself it does not do anything functionally useful. What it does however, is taking care of the geometry logic.

It enforces the geometry constraints and takes care of sending resize events messages.

__init__(width: int = 0, height: int = 0, minimum_width: int = 0, minimum_height: int = 0, maximum_width: int = 20, maximum_height: int = 10, layout: Layout | None = None, bg_color: Color | None = None, config: UiConfig | None = None) → None

Parameters:

width (int) – The width of the widget.
height (int) – The height of the widget.
minimum_width (int) – The minimum_width of the widget.
minimum_height (int) – The minimum_height of the widget.
maximum_width (int) – The maximum_width of the widget.
maximum_height (int) – The maximum_height of the widget.
layout (Layout) – The layout of the widget.
bg_color (Color) – The default background color of the widget. This property overrides the widget_bg_color from the UiConfig class (in case you want to create a specific widget with a different background color than the default one).
config (UiConfig) – The configuration object.

Example:

my_widget = Widget(6, 3, minimum_width=6, minimum_height=3)
my_widget.bg_color = Color(255, 255, 255)
screen.place(my_widget, 5, 2)

Methods

`__init__`([width, height, minimum_width, ...])	param width: The width of the widget.
`attach`(observer)	Attach an observer to this instance.
`detach`(observer)	Detach an observer from this instance.
`handle_notification`(subject[, attribute, value])	A virtual method that needs to be implemented by the observer.
`notify`([modifier, attribute, value])	Notify all the observers that a change occurred.
`render_to_buffer`(buffer, row, column, ...)	Render the object from the display buffer to the frame buffer.
`store_screen_position`(row, column)	Store the screen position of the object.

Attributes

`bg_color`	This property get/set the background color of the widget.
`children`	This read only property property returns the list of children widgets.
`focus`	This property get/set the focus property.
`height`	This property get/set the height of the widget.
`layout`	This property get/set the layout of the widget.
`maximum_height`	This property get/set the maximum height of the widget.
`maximum_width`	This property get/set the maximum width of the widget.
`minimum_height`	This property get/set the minimum height of the widget.
`minimum_width`	This property get/set the minimum width of the widget.
`parent`	This property get/set the parent widget of the widget.
`screen_column`	A property to get/set the screen column.
`screen_row`	A property to get/set the screen row.
`size_constraint`	This property get/set the size constraints of the widget.
`width`	This property get/set the width of the widget.
`x`	This property get/set the x position of the widget on screen.
`y`	This property get/set the y position of the widget on screen.

attach(observer)

Attach an observer to this instance. It means that until it is detached, it will be notified every time that a notification is issued (usually on changes).

An object cannot add itself to the list of observers (to avoid infinite recursions).

Parameters:: observer (PglBaseObject) – An observer to attach to this object.
Returns:: True or False depending on the success of the operation.
Return type:: bool

Example:

myboard = Board()
screen = Game.instance().screen
# screen will be notified of all changes in myboard
myboard.attach(screen)

property bg_color: Color

This property get/set the background color of the widget.

When the color is changed the pygamelib.gfx.ui.Widget.bg_color:changed event is sent to the observers.

property children: Set[Widget]: This read only property property returns the list of children widgets.

detach(observer)

Detach an observer from this instance. If observer is not in the list this returns False.

Parameters:: observer (PglBaseObject) – An observer to detach from this object.
Returns:: True or False depending on the success of the operation.
Return type:: bool

Example:

# screen will no longer be notified of the changes in myboard.
myboard.detach(screen)

property focus: bool

This property get/set the focus property. It is a boolean.

At the moment it is mostly an informational property, to tell the programmer and potentially the Widget user (i.e: the class inheriting from Widget) about its own state.

handle_notification(subject, attribute=None, value=None)

A virtual method that needs to be implemented by the observer. By default it does nothing but each observer needs to implement it if something needs to be done when notified.

This method always receive the notifying object as first parameter. The 2 other parameters are optional and can be None.

You can use the attribute and value as you see fit. You are free to consider attribute as an event and value as the event’s value.

Parameters:

subject (PglBaseObject) – The object that has changed.
attribute (str) – The attribute that has changed, it is usually a “FQDN style” string. This can be None.
value (Any) – The new value of the attribute. This can be None.

property height: int

This property get/set the height of the widget. This property respects the boundaries set by the maximum_height and minimum_height properties.

When the height is changed the pygamelib.gfx.ui.Widget.resizeEvent:height event is sent to the observers.

property layout: Layout

This property get/set the layout of the widget. You can then add sub widgets to the layout.

This must be a Layout or a class that inherits from it.

When the layout is changed the pygamelib.gfx.ui.Widget.layout:changed event is sent to the observers.

property maximum_height: int: This property get/set the maximum height of the widget. This property is used when changing the size constraints and the height property.

property maximum_width: int: This property get/set the maximum width of the widget. This property is used when changing the size constraints and the width property.

property minimum_height: int: This property get/set the minimum height of the widget. This property is used when changing the size constraints and the height property.

property minimum_width: int: This property get/set the minimum width of the widget. This property is used when changing the size constraints and the width property.

notify(modifier=None, attribute: str = None, value: Any = None) → None

Notify all the observers that a change occurred.

Parameters:

modifier (PglBaseObject) – An optional parameter that identify the modifier object to exclude it from the notified objects.
attribute (str) – An optional parameter that identify the attribute that has changed.
value (Any) – An optional parameter that identify the new value of the attribute.

Example:

# This example is silly, you would usually notify other objects from inside
# an object that changes a value that's important for the observers.
color = Color(255,200,125)
color.attach(some_text_object)
color.notify()

property parent: Widget | None: This property get/set the parent widget of the widget.

render_to_buffer(buffer: numpy.array, row: int, column: int, buffer_height: int, buffer_width: int) → None

Render the object from the display buffer to the frame buffer.

This method is automatically called by pygamelib.engine.Screen.render().

Parameters:

buffer (numpy.array) – A screen buffer to render the item into.
row (int) – The row to render in.
column (int) – The column to render in.
height (int) – The total height of the display buffer.
width (int) – The total width of the display buffer.

property screen_column: int

A property to get/set the screen column.

Parameters:: value (int) – the screen column
Return type:: int

property screen_row: int

A property to get/set the screen row.

Parameters:: value (int) – the screen row
Return type:: int

property size_constraint: SizeConstraint: This property get/set the size constraints of the widget. Changing the size constraints immediately resize the widget.

store_screen_position(row: int, column: int) → bool

Store the screen position of the object.

This method is automatically called by Screen.place().

Parameters:

row (int) – The row (or y) coordinate.
column (int) – The column (or x) coordinate.

Example:

an_object.store_screen_coordinate(3,8)

property width: int

This property get/set the width of the widget. This property respects the boundaries set by the maximum_width and minimum_width properties.

When the width is changed the pygamelib.gfx.ui.Widget.resizeEvent:width event is sent to the observers.

property x: int: This property get/set the x position of the widget on screen. Since a Widget is a PglBaseObject this is an alias for the screen_column property.

property y: int: This property get/set the y position of the widget on screen. Since a Widget is a PglBaseObject this is an alias for the screen_row property.