FormLayout

class pygamelib.gfx.ui.FormLayout(parent: Widget | None = None, wrap_rows: bool = False)

Bases: Layout

Added in version 1.4.0.

The FormLayout is a layout to organize the widgets like they would be on a form. This means a label associated to a widget (for example a label like “Name” associated to a LineInput widget).

__init__(parent: Widget | None = None, wrap_rows: bool = False) → None

Parameters:

• parent (Widget) – The parent widget of this layout.

• wrap_rows (bool) – By default, widgets are displayed on the same line as the label. If wrap_rows is True, the widget will be displayed bellow the label.

Example:

w = ui.Widget(60, 20, 60, 30)
w.layout = ui.FormLayout()
w.layout.spacing = 0
w.layout.add_row("First name", LineInput("John Doe"))

Methods

__init__([parent, wrap_rows])
add_row(label, widget)	Adds a row to the layout with the given label and widget.
add_widget(w)	Add a widget to the layout, this method is an alias to: form_layout.add_row(base.Text(""), w)
attach(observer)	Attach an observer to this instance.
count()	Returns the number of widgets in the form layout.
count_rows()	returns the number of rows in the form layout.
detach(observer)	Detach an observer from this instance.
handle_notification(subject[, attribute, value])	A virtual method that needs to be implemented by the observer.
insert_row(row, label, widget)	Inserts a row at the specified position in the layout with the given label and widget.
notify([modifier, attribute, value])	Notify all the observers that a change occurred.
remove_row([row])	Removes the specified row from the layout.
render_to_buffer(buffer, row, column, ...)	Render the object from the display buffer to the frame buffer.
set_label(row, label)	set the label to the row passed in parameter.
set_widget(row, widget)	set the widget to the row passed in parameter.
store_screen_position(row, column)	Store the screen position of the object.
take_row(row)	Take a row from the layout and return the label and the widget.
widgets()

Attributes

height	Get the layout's height (including spacing).
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	Get the layout's width.

add_row(label: str | Text, widget: Widget) → bool

Adds a row to the layout with the given label and widget.

Parameters:

• label (Text | str) – The label of the row to add.

• widget (Widget) – The widget to add.

Returns:

A boolean, True is the row was added, False otherwise.

Return type:

bool

add_widget(w: Widget) → bool

Add a widget to the layout, this method is an alias to: form_layout.add_row(base.Text(“”), w)

It will add a row with an empty label and the given widget.

Parameters:

w (Widget) – The widget to add.

Returns:

A boolean, True is the widget was added, False otherwise.

Return type:

bool

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

Returns the number of widgets in the form layout. Since there is exactly one widget per row, this method is equivalent to count_rows().

count_rows() → int

returns the number of rows in the form 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)

get_row(row: int) → Tuple[Text, Widget]

Return the required row as a tuple of a label and a widget. If the specified row does not exist either because row is not an int or the int is bigger or smaller than the number or rows, the last row is returned.

Parameters:

row (int) – The row number to get.

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

Get the layout’s height (including spacing).

Returns an int.

This is a read-only property.

insert_row(row: int, label: str | Text, widget: Widget) → bool

Inserts a row at the specified position in the layout with the given label and widget.

Parameters:

• row (int) – The index at which the row should be inserted.

• label (Text | str) – The label of the row to add.

• widget (Widget) – The widget to add.

Returns:

A boolean, True is the row was added, False otherwise.

Return type:

bool

notify(modifier: PglBaseObject | None = None, attribute: str | None = None, value: Any | None = 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).

remove_row(row: int | None = None) → bool

Removes the specified row from the layout. If no row is specified, removes the last row.

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

set_label(row: int, label: str | Text) → None

set the label to the row passed in parameter.

set_widget(row: int, widget: Widget) → None

set the widget to the row passed in parameter.

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)

take_row(row: int) → Tuple[Text, Widget]

Take a row from the layout and return the label and the widget. All layout’s remaining rows are correctly renumbered. If the specified row does not exist either because row is not an int or the int is bigger or smaller than the number or rows, the last row is returned.

widgets() → List[Widget]

Returns:

A list of widgets

Return type:

List[Widget]

Returns a list of widgets that are contained in the FormLayout.

property width: int

Get the layout’s width. The FormLayout uses spacing only for vertical spacing. Therefor, it is not included in the width of the layout.

Returns an int.

This is a read-only property.

property wrap_rows: bool

A property to control row wrapping. If sets to True, the labels will be rendered on one row and the widget on the next. Otherwise, the label and the widget will be rendered on the same row.