Skip to content

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

AppBlur class

Bases: Event

Sent when the app loses focus.

  • Bubbles
  • Verbose
Note

Only available when running within a terminal that supports FocusOut, or when running via textual-web.

AppFocus class

Bases: Event

Sent when the app has focus.

  • Bubbles
  • Verbose
Note

Only available when running within a terminal that supports FocusIn, or when running via textual-web.

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.

This event is used internally by Textual. You won't typically need to explicitly handle it,

  • Bubbles
  • Verbose

CursorPosition class

Bases: Event

Internal event used to retrieve the terminal's cursor position.

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

Sent when any of the following conditions apply:

  • The widget is removed from the DOM.
  • The widget is no longer displayed because it has been scrolled or clipped from the terminal or its container.
  • The widget has its display attribute set to False.
  • The widget's display style is set to "none".

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
Parameter Default Description
key
str
required

The key that was pressed.

character
str | None
required

A printable character or None if it is not printable.

aliases instance-attribute

aliases: list[str] = _get_key_aliases(key)

The aliases for the key, including the key itself.

character instance-attribute

character = (
    key
    if len(key) == 1
    else None if character is None else character
)

A printable character or None if it is not printable.

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.

key instance-attribute

key = key

The key that was pressed.

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 setup 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
Parameter Default Description
mouse_position
Offset
required

The position of the mouse when captured.

mouse_position instance-attribute

mouse_position = mouse_position

The position of the mouse when captured.

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
Parameter Default Description
x
int
required

The relative x coordinate.

y
int
required

The relative y coordinate.

delta_x
int
required

Change in x since the last message.

delta_y
int
required

Change in y since the last message.

button
int
required

Indexed of the pressed button.

shift
bool
required

True if the shift key is pressed.

meta
bool
required

True if the meta key is pressed.

ctrl
bool
required

True if the ctrl key is pressed.

screen_x
int | None
None

The absolute x coordinate.

screen_y
int | None
None

The absolute y coordinate.

style
Style | None
None

The Rich Style under the mouse cursor.

button instance-attribute

button = button

Indexed of the pressed button.

ctrl instance-attribute

ctrl = ctrl

True if the ctrl key is pressed.

delta property

delta: Offset

Mouse coordinate delta (change since last event).

delta_x instance-attribute

delta_x = delta_x

Change in x since the last message.

delta_y instance-attribute

delta_y = delta_y

Change in y since the last message.

meta instance-attribute

meta = meta

True if the meta key is pressed.

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.

screen_x instance-attribute

screen_x = x if screen_x is None else screen_x

The absolute x coordinate.

screen_y instance-attribute

screen_y = y if screen_y is None else screen_y

The absolute y coordinate.

shift instance-attribute

shift = shift

True if the shift key is pressed.

style property writable

style: Style

The (Rich) Style under the cursor.

x instance-attribute

x = x

The relative x coordinate.

y instance-attribute

y = y

The relative y coordinate.

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
Parameter Default Description
widget
Widget
required

Widget receiving the event.

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
Parameter Default Description
widget
Widget
required

Widget receiving the event.

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
Parameter Default Description
mouse_position
Offset
required

The position of the mouse when released.

mouse_position instance-attribute

mouse_position = mouse_position

The position of the mouse when released.

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
Parameter Default Description
text
str
required

The text that has been pasted.

text instance-attribute

text = text

The text that was pasted.

Print class

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

Bases: Event

Sent to a widget that is capturing print.

  • Bubbles
  • Verbose
Parameters
Parameter Default Description
text
str
required

Text that was printed.

stderr
bool
False

True if the print was to stderr, or False for stdout.

Note

Python's print output can be captured with App.begin_capture_print.

stderr instance-attribute

stderr = stderr

True if the print was to stderr, or False for stdout.

text instance-attribute

text = text

The text that was printed.

Ready class

Bases: Event

Sent to the App when the DOM is ready and the first frame has been displayed.

  • 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
Parameter Default Description
size
Size
required

The new size of the Widget.

virtual_size
Size
required

The virtual size (scrollable size) of the Widget.

container_size
Size | None
None

The size of the Widget's container widget.

container_size instance-attribute

container_size = (
    size if container_size is None else container_size
)

The size of the Widget's container widget.

size instance-attribute

size = size

The new size of the Widget.

virtual_size instance-attribute

virtual_size = virtual_size

The virtual size (scrollable size) of the Widget.

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 is first displayed.

  • 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 no longer receive messages.

  • Bubbles
  • Verbose