Cursor
- class pygamelib.gfx.ui.Cursor(relative_row: int | None = 0, relative_column: int | None = 0, blink_time: float | None = 0.4, sprixel: Sprixel | None = None, parent: Widget | None = None)
Bases:
PglBaseObject
New in version 1.4.0.
The Cursor class represent a typing cursor on screen.
Warning
The Cursor need to be rendered last! For example, in a LineInput widget, the cursor is rendered when the rest of the LineInput is already rendered . The reason being that the Cursor need to know what is already on screen in case it overlap something.
- __init__(relative_row: int | None = 0, relative_column: int | None = 0, blink_time: float | None = 0.4, sprixel: Sprixel | None = None, parent: Widget | None = None) None
- Parameters:
relative_row (int) – The relative row position inside the parent widget.
relative_column (int) – The relative column position inside the parent widget.
blink_time (float) – The time interval between blinks. Default is 0.4 seconde. If you want to keep the cursor solid (i.e: not blinking) set this parameter to 0.
sprixel (
Sprixel
) – The cursor’s sprixel (or representation) as a Sprixel.parent (
Widget
) – The parent object, ie: the one in which the cursor reside. It’s optional because you can share a cursor with multiple widgets.
Example:
# Create a cyan cursor rapidly blinking. custom_cursor = Cursor( blink_time=0.1, sprixel=Sprixel( "|", bg_color=config.input_bg_color, fg_color=Color(0, 255, 255) ), ) line_input = LineInput( "Test of the LineInput widget", config=UiConfig.instance(), minimum_width=6, maximum_width=200, cursor=custom_cursor, )
Methods
__init__
([relative_row, relative_column, ...])- param relative_row:
The relative row position inside the parent widget.
attach
(observer)Attach an observer to this instance.
detach
(observer)Detach an observer from this instance.
handle_notification
(subject[, attribute, value])A virtual method that needs to be implemented by the observer.
Prevent the cursor's relative position to be changed.
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.
Authorize the cursor's relative position to be changed.
Attributes
Get and set the sprixel of the cursor, it has to be
core.Sprixel
.Get and set the parent widget of the cursor, it has to be a
Widget
or None.A property to get/set the screen column.
A property to get/set the screen row.
Get and set the relative_column of the cursor, it has to be an int.
Get and set the relative_row of the cursor, it has 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)
- 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.
- lock_position()
Prevent the cursor’s relative position to be changed. It is useful for objects that manipulate the cursor depending on their content.
Example:
my_cursor = Cursor() my_lineedit = LineEdit(cursor=my_cursor) my_cursor.lock_position() my_lineedit.delete() my_cursor.unlock_position()
- 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
Get and set the parent widget of the cursor, it has to be a
Widget
or None.
- property relative_column: int
Get and set the relative_column of the cursor, it has to be an int. This value cannot be negative (as it makes no sense in our coordinate referential).
- property relative_row: int
Get and set the relative_row of the cursor, it has to be an int. This value cannot be negative (as it makes no sense in our coordinate referential).
- 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
- 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)
- unlock_position() None
Authorize the cursor’s relative position to be changed. It is useful for objects that manipulate the cursor depending on their content.
Example:
my_cursor = Cursor() my_lineedit = LineEdit(cursor=my_cursor) my_cursor.lock_position() my_lineedit.delete() my_cursor.unlock_position()