LineInput

class pygamelib.gfx.ui.LineInput(default: str = '', filter: InputValidator = InputValidator.PRINTABLE_FILTER, width: int = 0, height: int = 0, minimum_width: int = 0, minimum_height: int = 1, maximum_width: int = 20, maximum_height: int = 1, config: UiConfig | None = None, history: History | None = None, cursor: Cursor | None = None)

Bases: Widget

New in version 1.4.0.

The LineInput widget allows the user to enter and edit a single line of text.

This widget can be configured to accept either anything printable or only digits.

Contrary to its dialog version that widget does not have any key binding. It provides all the tools to manipulate it but it is the user’s (developer) responsibility to bind keys to specific actions.

__init__(default: str = '', filter: InputValidator = InputValidator.PRINTABLE_FILTER, width: int = 0, height: int = 0, minimum_width: int = 0, minimum_height: int = 1, maximum_width: int = 20, maximum_height: int = 1, config: UiConfig | None = None, history: History | None = None, cursor: Cursor | None = None) → None

Parameters:

default (str) – The default value in the input field.
filter (InputValidator) – Sets the type of accepted input. It comes from the constants module.
width (int) – The width of the LineInput.
height (int) – The height of the LineInput.
minimum_width (int) – The minimum width of the LineInput.
minimum_height (int) – The minimum height of the LineInput.
maximum_width (int) – The maximum width of the LineInput.
maximum_height (int) – The maximum height of the LineInput.
config (UiConfig) – The configuration object.
history (History) – The history object. If none is provided, the LineInput will use the global instance of History.

Example:

line_input = LineInput(
    "Test of the LineInput widget",
    config=UiConfig.instance(),
    minimum_width=6,
    maximum_width=200,
)
screen.place(line_input, 10, 10)

# Somewhere else in your code you can access the content with LineInput.text
pet_name = line_input.text

Methods

`__init__`([default, filter, width, height, ...])	param default: The default value in the input field.
`attach`(observer)	Attach an observer to this instance.
`backspace`()	Erase the character immediately before the `Cursor`.
`clear`()	Clear everything from the LineInput.
`cursor`	A read-only property that gives access to the cursor.
`delete`()	Delete the character immediately under the `Cursor`.
`detach`(observer)	Detach an observer from this instance.
`end`()	Set the `Cursor`'s relative column to the length of the content (i.e: put the cursor at the end of the LineEdit).
`handle_notification`(subject[, attribute, value])	A virtual method that needs to be implemented by the observer.
`home`()	Set the `Cursor`'s relative column to 0 (i.e: put the cursor at the beginning of the LineEdit).
`insert_characters`([character, position])	Insert one or more characters at a given position.
`length`()	Return the length of the content of the LineInput widget.
`move_cursor`(direction)	Move the `Cursor` in the specified direction.
`notify`([modifier, attribute, value])	Notify all the observers that a change occurred.
`redo`()	If a `History` is available, redo previously undone changes.
`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.
`undo`()	If a `History` is available, undo the last changes.

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.
`cursor`	A read-only property that gives access to the cursor.
`filter`	Get and set the filter of the line input, it has to be an `InputValidator`.
`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.
`text`	Get and set the text of the line input, it has to be a str.
`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)

backspace() → None

Erase the character immediately before the Cursor.

The modification is reported to the history (i.e: can be undone)

Example:

# If the LineInput contains "Hello"
line_input.backspace()
# Will modify it to "Hell" if the cursor is at the end of the line.

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.

clear() → None: Clear everything from the LineInput. If a History is available, it will also clear the history.

property cursor: Cursor: A read-only property that gives access to the cursor.

delete() → None: Delete the character immediately under the Cursor.

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)

end() → None: Set the Cursor’s relative column to the length of the content (i.e: put the cursor at the end of the LineEdit).

property filter: InputValidator: Get and set the filter of the line input, it has to be an InputValidator.

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.

home() → None: Set the Cursor’s relative column to 0 (i.e: put the cursor at the beginning of the LineEdit).

insert_characters(character: str = None, position: int | None = None) → None

Insert one or more characters at a given position.

If no position is given, the characters are inserted at the cursor’s position.

Parameters:

character (str) – The character to insert.
position (int) – The position at which a character must be inserted.

Example:

# Insert a character at position 3 of the LineInput widget (if it exists,
# otherwise insert at the end)
line_input.insert_character("a", 3)

# Insert a character at the cursor's position
line_input.insert_character("a")

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.

length() → int: Return the length of the content of the LineInput widget.

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.

move_cursor(direction: Direction) → None

Move the Cursor in the specified direction.

Parameters:: direction (Direction) – The direction to move the cursor to.

Example:

line_edit.move_cursor(constants.Direction.LEFT)

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.

redo() → None: If a History is available, redo previously undone changes.

render_to_buffer(buffer, row, column, buffer_height, buffer_width) → 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 text: str

Get and set the text of the line input, it has to be a str. When setting this property tries to set the LineInput.width to the size of the content if the content’s length is greater than the width.

Obviously the width is constrained by the maximum_width property.

undo() → None: If a History is available, undo the last changes.

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.