Skip to content

Events

Compose

Bases: Event

Sent to a widget to request it to compose and mount children.

Event

Bases: Message

The base class for all events.

Hide

Bases: Event

Sent when a widget has been hidden.

A widget may be hidden by setting its visible flag to False, if it is no longer in a layout, or if it has been offset beyond the edges of the terminal.

Idle

Bases: Event

Sent when there are no more items in the message queue.

This is a pseudo-event in that it is created by the Textual system and doesn't go through the usual message queue.

InvokeCallbacks

Bases: Event

Sent after the Screen is updated

Key

Bases: InputEvent

Sent when the user hits a key on the keyboard.

Parameters:

Name Type Description Default
sender MessageTarget

The sender of the event (the App).

required
key str

A key name (textual.keys.Keys).

required
char str | None

A printable character or None if it is not printable.

required

Attributes:

Name Type Description
key_aliases list[str]

The aliases for the key, including the key itself

is_printable() property

Return True if the key is printable. Currently, we assume any key event that isn't defined in key bindings is printable.

Returns:

Name Type Description
bool bool

True if the key is printable.

key_name() property

Name of a key suitable for use as a Python identifier.

Load

Bases: Event

Sent when the App is running but before the terminal is in application mode.

Use this event to run any set up that doesn't require any visuals such as loading configuration and binding keys.

Mount

Bases: Event

Sent when a widget is mounted and may receive messages.

MouseCapture

Bases: Event

Sent when the mouse has been captured.

When a mouse has been captured, all further mouse events will be sent to the capturing widget.

Parameters:

Name Type Description Default
sender MessageTarget

The sender of the event, (in this case the app).

required
mouse_position Point

The position of the mouse when captured.

required

MouseEvent

Bases: InputEvent

Sent in response to a mouse event.

Parameters:

Name Type Description Default
sender MessageTarget

The sender of the event.

required
x int

The relative x coordinate.

required
y int

The relative y coordinate.

required
delta_x int

Change in x since the last message.

required
delta_y int

Change in y since the last message.

required
button int

Indexed of the pressed button.

required
shift bool

True if the shift key is pressed.

required
meta bool

True if the meta key is pressed.

required
ctrl bool

True if the ctrl key is pressed.

required
screen_x int

The absolute x coordinate.

None
screen_y int

The absolute y coordinate.

None
style Style

The Rich Style under the mouse cursor.

None

delta() property

Mouse coordinate delta (change since last event).

Returns:

Name Type Description
Offset Offset

Mouse coordinate.

get_content_offset(widget)

Get offset within a widget's content area, or None if offset is not in content (i.e. padding or border).

Parameters:

Name Type Description Default
widget Widget

Widget receiving the event.

required

Returns:

Type Description
Offset | None

Offset | None: An offset where the origin is at the top left of the content area.

offset() property

The mouse coordinate as an offset.

Returns:

Name Type Description
Offset Offset

Mouse coordinate.

screen_offset() property

Mouse coordinate relative to the screen.

Returns:

Name Type Description
Offset Offset

Mouse coordinate.

style() property writable

The (Rich) Style under the cursor.

MouseMove

Bases: MouseEvent

Sent when the mouse cursor moves.

MouseRelease

Bases: Event

Mouse has been released.

Parameters:

Name Type Description Default
sender MessageTarget

The sender of the event, (in this case the app).

required
mouse_position Point

The position of the mouse when released.

required

Paste

Bases: Event

Event containing text that was pasted into the Textual application. This event will only appear when running in a terminal emulator that supports bracketed paste mode. Textual will enable bracketed pastes when an app starts, and disable it when the app shuts down.

Parameters:

Name Type Description Default
sender MessageTarget

The sender of the event, (in this case the app).

required
text str

The text that has been pasted.

required

Resize

Bases: Event

Sent when the app or widget has been resized.

Parameters:

Name Type Description Default
sender MessageTarget

The sender of the event (the Screen).

required
size Size

The new size of the Widget.

required
virtual_size Size

The virtual size (scrollable size) of the Widget.

required
container_size Size | None

The size of the Widget's container widget. Defaults to None.

None

Show

Bases: Event

Sent when a widget has become visible.

Unmount

Bases: Mount

Sent when a widget is unmounted and may not longer receive messages.