Layout

class pygamelib.gfx.ui.Layout(parent: Widget | None = None)

Bases: PglBaseObject

New in version 1.4.0.

The Layout class is mostly a virtual class. It implements a few properties but all of the methods and properties marked with the virtual method tag need to be implemented in the inheriting object.

By convention, a layout will always use the maximum space available in a rendering buffer. That means that in render_to_buffer() it will try to use the entire buffer_width and buffer_height while respecting the layout’s constraints.

It is therefore the responsibility of the widget or layout that triggers the rendering loop to confine said layout inside its own rendering space. Most of the time it involves passing a different set of argument to render_to_buffer() (like the position or size of the buffer).

__init__(parent: Widget | None = None) → None

The Layout constructor takes the following parameters.

Parameters:: parent – The parent widget. If set, it will set the parent’s layout.

Methods

`__init__`([parent])	The Layout constructor takes the following parameters.
`add_widget`(w)	virtual method
`attach`(observer)	Attach an observer to this instance.
`count`()	virtual method
`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, ...)	virtual method
`store_screen_position`(row, column)	Store the screen position of the object.
`widgets`()	virtual method

Attributes

`height`	virtual attribute
`parent`	This property get/set the parent of the Layout (if any).
`screen_column`	A property to get/set the screen column.
`screen_row`	A property to get/set the screen row.
`spacing`	This property get/set the inter-widgets spacing of the Layout.
`width`	virtual attribute

add_widget(w: Widget) → bool

virtual method

This method is purely virtual and needs to be implemented in the inheriting class.

It must allow adding a Widget to the layout. Adding can mean different things depending on the type of layout. For example, a GridLayout need a row and a column to place the widget. However, these parameters are optional. All layouts should be able to add a Widget in the first available space.

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)

count() → int

virtual method

This method is purely virtual and needs to be implemented in the inheriting class.

It must count and returns as an integer the number of widgets in the layout.

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)

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

virtual attribute

This property is purely virtual and needs to be implemented in the inheriting class.

It must return the total height of the Layout.

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 of the Layout (if any).

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

virtual method

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.

This method is purely virtual and needs to be implemented in the inheriting class.

It must render the object from the display buffer to the frame buffer.

By convention, a layout will always use the maximum space available in a rendering buffer. That means that in render_to_buffer() it will try to use the entire buffer_width and buffer_height while respecting the layout’s constraints.

It is therefore the responsibility of the widget or layout that triggers the rendering loop to confine said layout inside its own rendering space. Most of the time it involves passing a different set of argument to render_to_buffer() (like the position or size of the 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 spacing: int

This property get/set the inter-widgets spacing of the Layout.

When the spacing is changed the pygamelib.gfx.ui.Layout.spacing:changed event is sent to the observers.

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)

widgets() → List[Widget]

virtual method

Returns:: A list of widgets
Return type:: List[Widget]

This method is purely virtual and needs to be implemented in the inheriting class.

It must returns a list of widgets that are contained in the layout.

property width: int

virtual attribute

This property is purely virtual and needs to be implemented in the inheriting class.

It must return the total width of the Layout.