GridLayout

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

Bases: Layout

New in version 1.4.0.

The GridLayout is a layout to organize the widgets in a grid (shocking right?). All widgets are managed in a grid, one per cell. Layouts can be nested of course to adapt to your need.

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

Parameters:: parent (Widget) – The parent object, ie: the one in which the GridLayout reside.

Example:

parent_widget = Widget(45, 30, config=config)
# Add a GridLayout to a widget
parent_widget.layout = GridLayout()
# You could also do:
parent_widget.layout = GridLayout(parent_widget)
# But it is not necessary because the Widget.layout property is going to do
# it for you.

Methods

`__init__`([parent])	param parent: The parent object, ie: the one in which the GridLayout reside.
`add_widget`(widget[, row, column])	Add a widget to the GridLayout.
`attach`(observer)	Attach an observer to this instance.
`count`()	Returns the amount (the count) of widgets in the GridLayout.
`count_columns`()	Returns the number of columns in the GridLayout.
`count_rows`()	Returns the number of rows in the GridLayout.
`detach`(observer)	Detach an observer from this instance.
`handle_notification`(subject[, attribute, value])	This is an implementation of the notification handling system that is necessary for this class to handle correctly widget's resizing.
`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.
`widgets`()	Returns the list of widgets that are managed by the GridLayout as a set.

Attributes

`column_minimum_width`	Get and set the column's minimum width of the layout.
`height`	Get the layout's height (including spacing).
`horizontal_spacing`	Get and set the horizontal spacing between the widgets in the layout.
`parent`	This property get/set the parent of the Layout (if any).
`row_minimum_height`	Get and set the row's minimum width of the layout.
`screen_column`	A property to get/set the screen column.
`screen_row`	A property to get/set the screen row.
`spacing`	Get and set the spacing between the widgets in the layout.
`vertical_spacing`	Get and set the vertical spacing between the widgets in the layout.
`width`	Get the layout's width (including spacing).

add_widget(widget: Widget, row: int = None, column: int = None) → bool

Add a widget to the GridLayout. If the widget is correctly added to the layout this method returns True, otherwise it returns False.

Parameters:

widget (class:Widget) – The widget to add to the layout.
row (int) – The row in the layout at which the widget should be added.
column (int) – The column in the layout at which the widget should be added.

Example:

parent_widget = Widget(45, 30, config=config)
# Add a GridLayout to a widget
parent_widget.layout = GridLayout()
# Then add children widgets to the parent's layout
# Step 1: create a widget (here just a generic widget)
child_widget1 = Widget(config=UiConfig.instance())
# Step 2: add it to the layout.
parent_widget.layout.add_widget(child_widget1, 2, 3)
# That's it!

If either of the row or column (or both) are None, the method will find the first unused cell to put the widget in.

Important

If there’s no space within the existing grid, a new line will be added. For now, the expansion policy cannot be chosen and it is vertically. In the future an expand policy could be added.

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 column_minimum_width: int: Get and set the column’s minimum width of the layout. This will apply to all columns. It has to be an int.

count() → int: Returns the amount (the count) of widgets in the GridLayout.

count_columns() → int: Returns the number of columns in the GridLayout.

count_rows() → int: Returns the number of rows in the GridLayout.

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

This is an implementation of the notification handling system that is necessary for this class to handle correctly widget’s resizing. If you subclass GridLayout and you need to overload that method, please keep in mind that you need to let GridLayout.handle_notification() do its job if you want to benefit from its capabilities.

In other words, do not forget to call super().handle_notification(subject, attribute, value)!

property height: int

Get the layout’s height (including spacing).

Returns an int.

This is a read-only property.

property horizontal_spacing: int: Get and set the horizontal spacing between the widgets in the layout. It has to be an int.

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

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 row_minimum_height: int: Get and set the row’s minimum width of the layout. This will apply to all row. It has to be an int.

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: Get and set the spacing between the widgets in the layout. This property sets both the horizontal and vertical spacing. It has to be an int.

Warning

if you try to retrieve the spacing and the horizontal and vertical spacing are not identical this property returns -1.

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 vertical_spacing: int: Get and set the vertical spacing between the widgets in the layout. It has to be an int.

widgets() → Set[Widget]: Returns the list of widgets that are managed by the GridLayout as a set. This set is not guaranteed to be ordered!

property width: int

Get the layout’s width (including spacing).

Returns an int.

This is a read-only property.