Events

Builtin events sent by Textual.

Events may be marked as "Bubbles" and "Verbose". See the events guide for an explanation of bubbling. Verbose events are excluded from the textual console, unless you explicitly request them with the -v switch as follows:

textual console -v

Blur class

Bases: Event

Sent when a widget is blurred (un-focussed).

• Bubbles
• Verbose

Click class

Bases: MouseEvent

Sent when a widget is clicked.

• Bubbles
• Verbose

Compose class

Bases: Event

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

• Bubbles
• Verbose

DescendantBlur class

Bases: Event

Sent when a child widget is blurred.

• Bubbles
• Verbose

control property

control: Widget

The widget that was blurred (alias of widget).

widget instance-attribute

widget: Widget

The widget that was blurred.

DescendantFocus class

Bases: Event

Sent when a child widget is focussed.

• Bubbles
• Verbose

control property

control: Widget

The widget that was focused (alias of widget).

widget instance-attribute

widget: Widget

The widget that was focused.

Enter class

Bases: Event

Sent when the mouse is moved over a widget.

• Bubbles
• Verbose

Event class

Bases: Message

The base class for all events.

Focus class

Bases: Event

Sent when a widget is focussed.

• Bubbles
• Verbose

Hide class

Bases: Event

Sent when a widget has been hidden.

• Bubbles
• Verbose

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 class

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.

• Bubbles
• Verbose

InputEvent class

Bases: Event

Base class for input events.

Key class

def __init__(self, key, character):

Bases: InputEvent

Sent when the user hits a key on the keyboard.

• Bubbles
• Verbose

Parameters

Name	Type	Description	Default
key	str	The key that was pressed.	required
character	str | None	A printable character or None if it is not printable.	required

Attributes

Name	Type	Description
aliases	list[str]	The aliases for the key, including the key itself.

is_printable property

is_printable: bool

Check if the key is printable (produces a unicode character).

Returns

Type	Description
bool	True if the key is printable.

name property

name: str

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

name_aliases property

name_aliases: list[str]

The corresponding name for every alias in aliases list.

Leave class

Bases: Event

Sent when the mouse is moved away from a widget.

• Bubbles
• Verbose

Load class

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.

• Bubbles
• Verbose

Mount class

Bases: Event

Sent when a widget is mounted and may receive messages.

• Bubbles
• Verbose

MouseCapture class

def __init__(self, mouse_position):

Bases: Event

Sent when the mouse has been captured.

• Bubbles
• Verbose

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

Parameters

Name	Type	Description	Default
mouse_position	Offset	The position of the mouse when captured.	required

MouseDown class

Bases: MouseEvent

Sent when a mouse button is pressed.

• Bubbles
• Verbose

MouseEvent class

def __init__(
    self,
    x,
    y,
    delta_x,
    delta_y,
    button,
    shift,
    meta,
    ctrl,
    screen_x=None,
    screen_y=None,
    style=None,
):

Bases: InputEvent

Sent in response to a mouse event.

• Bubbles
• Verbose

Parameters

Name	Type	Description	Default
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 | None	The absolute x coordinate.	None
screen_y	int | None	The absolute y coordinate.	None
style	Style | None	The Rich Style under the mouse cursor.	None

delta property

delta: Offset

Mouse coordinate delta (change since last event).

Returns

Type	Description
Offset	Mouse coordinate.

offset property

offset: Offset

The mouse coordinate as an offset.

Returns

Type	Description
Offset	Mouse coordinate.

screen_offset property

screen_offset: Offset

Mouse coordinate relative to the screen.

Returns

Type	Description
Offset	Mouse coordinate.

style property writable

style: Style

The (Rich) Style under the cursor.

get_content_offset method

def get_content_offset(self, 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	An offset where the origin is at the top left of the content area.

get_content_offset_capture method

def get_content_offset_capture(self, widget):

Get offset from a widget's content area.

This method works even if the offset is outside the widget content region.

Parameters

Name	Type	Description	Default
widget	Widget	Widget receiving the event.	required

Returns

Type	Description
Offset	An offset where the origin is at the top left of the content area.

MouseMove class

Bases: MouseEvent

Sent when the mouse cursor moves.

• Bubbles
• Verbose

MouseRelease class

def __init__(self, mouse_position):

Bases: Event

Mouse has been released.

• Bubbles
• Verbose

Parameters

Name	Type	Description	Default
mouse_position	Offset	The position of the mouse when released.	required

MouseScrollDown class

Bases: MouseEvent

Sent when the mouse wheel is scrolled down.

• Bubbles
• Verbose

MouseScrollUp class

Bases: MouseEvent

Sent when the mouse wheel is scrolled up.

• Bubbles
• Verbose

MouseUp class

Bases: MouseEvent

Sent when a mouse button is released.

• Bubbles
• Verbose

Paste class

def __init__(self, text):

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.

• Bubbles
• Verbose

Parameters

Name	Type	Description	Default
text	str	The text that has been pasted.	required

Print class

def __init__(self, text, stderr=False):

Bases: Event

Sent to a widget that is capturing prints.

• Bubbles
• Verbose

Parameters

Name	Type	Description	Default
text	str	Text that was printed.	required
stderr	bool	True if the print was to stderr, or False for stdout.	False

Ready class

Bases: Event

Sent to the app when the DOM is ready.

• Bubbles
• Verbose

Resize class

def __init__(self, size, virtual_size, container_size=None):

Bases: Event

Sent when the app or widget has been resized.

• Bubbles
• Verbose

Parameters

Name	Type	Description	Default
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.	None

ScreenResume class

Bases: Event

Sent to screen that has been made active.

• Bubbles
• Verbose

ScreenSuspend class

Bases: Event

Sent to screen when it is no longer active.

• Bubbles
• Verbose

Show class

Bases: Event

Sent when a widget has become visible.

• Bubbles
• Verbose

Timer class

def __init__(self, timer, time, count=0, callback=None):

Bases: Event

Sent in response to a timer.

• Bubbles
• Verbose

Unmount class

Bases: Event

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

• Bubbles
• Verbose