GridSelector

class pygamelib.gfx.ui.GridSelector(choices: list = None, width: int = None, height: int = None, minimum_width: int = None, minimum_height: int = None, maximum_width: int = 5, maximum_height: int = 10, config: UiConfig | None = None)

Bases: Widget

The GridSelector is a widget that present a list of elements as a grid to the user.

It also provides the API to draw and manage the cursor and to retrieve the selected element.

Warning

In the first version of that widget, only the characters that have a length of 1 are supported. This excludes some UTF8 characters and most of the emojis.

__init__(choices: list = None, width: int = None, height: int = None, minimum_width: int = None, minimum_height: int = None, maximum_width: int = 5, maximum_height: int = 10, config: UiConfig | None = None) → None
Parameters:

  • choices (list) – A list of choices to present to the user. The elements of the list needs to be str or Sprixel.

  • minimum_width (int) – The minimum width of the GridSelector.

  • minimum_height (int) – The minimum height of the GridSelector.

  • maximum_width (int) – The maximum width of the GridSelector.

  • maximum_height (int) – The maximum height of the GridSelector.

  • config (UiConfig) – The configuration object.

Example:

choices = ["@","#","$","%","&","*","[","]"]
grid_selector = GridSelector(
    choices,
    maximum_width=30,
    maximum_height=10,
    config=conf
    )
screen.place(grid_selector, 10, 10)
screen.update()

Methods

__init__([choices,Β width,Β height,Β ...])

current_sprixel()

Returns the currently selected sprixel.

cursor_down()

Move the selection cursor one row down.

cursor_left()

Move the selection cursor one column to the left.

cursor_right()

Move the selection cursor one column to the right.

cursor_up()

Move the selection cursor one row up.

items_per_page()

Returns the number of items per page.

nb_pages()

Returns the number of pages.

page_down()

Change the current page to the one immediately down (current_page + 1).

page_up()

Change the current page to the one immediately up (current_page - 1).

render_to_buffer(buffer,Β row,Β column,Β ...)

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

Attributes

choices

Get and set the list of choices, it has to be a list of Sprixel or str.

current_choice

Get and set the currently selected item's index (the current choice), it needs to be an int.

current_page

Get and set the current page of the grid selector, it needs to be an int.
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.

property choices: int

Get and set the list of choices, it has to be a list of Sprixel or str.

property current_choice: int

Get and set the currently selected item’s index (the current choice), it needs to be an int. Use current_sprixel() to get the actual current item.

property current_page: int

Get and set the current page of the grid selector, it needs to be an int.

current_sprixel() → Sprixel

Returns the currently selected sprixel.

cursor_down() → None

Move the selection cursor one row down.

cursor_left() → None

Move the selection cursor one column to the left.

cursor_right() → None

Move the selection cursor one column to the right.

cursor_up() → None

Move the selection cursor one row up.

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.

items_per_page() → int

Returns the number of items per page.

property layout: Layout | None

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.

nb_pages() → int

Returns the number of pages.

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()
page_down() → None

Change the current page to the one immediately down (current_page + 1).

page_up() → None

Change the current page to the one immediately up (current_page - 1).

property parent: Widget | None

This property get/set the parent widget of the widget.

post_processing(attribute)

This virtual method allows for subclasses to perform their own operations when a specific attribute is changed

Parameters:

attribute – The attribute that has changed. This is a string containing

the name of the changed attribute :type attribute: str

render_to_buffer(buffer, 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.