[go: up one dir, main page]
Skip to content

textual.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 

AppBlur()

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 

AppFocus()

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 

Blur()

Bases: Event

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

  • Bubbles
  • Verbose

Callback 

Callback(callback)

Bases: Event

Sent by Textual to invoke a callback (see call_next and call_later).

Click 

Click(
    widget,
    x,
    y,
    delta_x,
    delta_y,
    button,
    shift,
    meta,
    ctrl,
    screen_x=None,
    screen_y=None,
    style=None,
)

Bases: MouseEvent

Sent when a widget is clicked.

  • Bubbles
  • Verbose

Compose 

Compose()

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 dataclass 

CursorPosition(x, y)

Bases: Event

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

DeliveryComplete dataclass 

DeliveryComplete(key, path=None, name=None)

Bases: Event

Sent to App when a file has been delivered.

key instance-attribute 

key

The delivery key associated with the delivery.

This is the same key that was returned by App.deliver_text/App.deliver_binary.

name class-attribute instance-attribute 

name = None

Optional name returned to the app to identify the download.

path class-attribute instance-attribute 

path = None

The path where the file was saved, or None if the path is not available, for example if the file was delivered via web browser.

DeliveryFailed dataclass 

DeliveryFailed(key, exception, name=None)

Bases: Event

Sent to App when a file delivery fails.

exception instance-attribute 

exception

The exception that was raised during the delivery.

key instance-attribute 

key

The delivery key associated with the delivery.

name class-attribute instance-attribute 

name = None

Optional name returned to the app to identify the download.

DescendantBlur dataclass 

DescendantBlur(widget)

Bases: Event

Sent when a child widget is blurred.

  • Bubbles
  • Verbose

control property 

control

The widget that was blurred (alias of widget).

widget instance-attribute 

widget

The widget that was blurred.

DescendantFocus dataclass 

DescendantFocus(widget)

Bases: Event

Sent when a child widget is focussed.

  • Bubbles
  • Verbose

control property 

control

The widget that was focused (alias of widget).

widget instance-attribute 

widget

The widget that was focused.

Enter 

Enter(node)

Bases: Event

Sent when the mouse is moved over a widget.

Note that this event bubbles, so a widget may receive this event when the mouse moves over a child widget. Check the node attribute for the widget directly under the mouse.

  • Bubbles
  • Verbose

control property 

control

Alias for the node under the mouse.

node instance-attribute 

node = node

The node directly under the mouse.

Event 

Event()

Bases: Message

The base class for all events.

Focus 

Focus()

Bases: Event

Sent when a widget is focussed.

  • Bubbles
  • Verbose

Hide 

Hide()

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 

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.

  • Bubbles
  • Verbose

InputEvent 

InputEvent()

Bases: Event

Base class for input events.

Key 

Key(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

aliases instance-attribute 

aliases = _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

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

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

name_aliases property 

name_aliases

The corresponding name for every alias in aliases list.

Leave 

Leave(node)

Bases: Event

Sent when the mouse is moved away from a widget, or if a widget is programmatically disabled while hovered.

Note that this widget bubbles, so a widget may receive Leave events for any child widgets. Check the node parameter for the original widget that was previously under the mouse.

  • Bubbles
  • Verbose

control property 

control

Alias for the node that was previously under the mouse.

node instance-attribute 

node = node

The node that was previously directly under the mouse.

Load 

Load()

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 

Mount()

Bases: Event

Sent when a widget is mounted and may receive messages.

  • Bubbles
  • Verbose

MouseCapture 

MouseCapture(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

mouse_position instance-attribute 

mouse_position = mouse_position

The position of the mouse when captured.

MouseDown 

MouseDown(
    widget,
    x,
    y,
    delta_x,
    delta_y,
    button,
    shift,
    meta,
    ctrl,
    screen_x=None,
    screen_y=None,
    style=None,
)

Bases: MouseEvent

Sent when a mouse button is pressed.

  • Bubbles
  • Verbose

MouseEvent 

MouseEvent(
    widget,
    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

widget

Widget | None

The widget under the mouse.

 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 | 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

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

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

The mouse coordinate as an offset.

Returns:

Type Description
Offset

Mouse coordinate.

screen_offset property 

screen_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

The (Rich) Style under the cursor.

widget instance-attribute 

widget = widget

The widget under the mouse at the time of a click.

x instance-attribute 

x = x

The relative x coordinate.

y instance-attribute 

y = y

The relative y coordinate.

get_content_offset 

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

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

get_content_offset_capture 

get_content_offset_capture(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 

MouseMove(
    widget,
    x,
    y,
    delta_x,
    delta_y,
    button,
    shift,
    meta,
    ctrl,
    screen_x=None,
    screen_y=None,
    style=None,
)

Bases: MouseEvent

Sent when the mouse cursor moves.

  • Bubbles
  • Verbose

MouseRelease 

MouseRelease(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

mouse_position instance-attribute 

mouse_position = mouse_position

The position of the mouse when released.

MouseScrollDown 

MouseScrollDown(
    widget,
    x,
    y,
    delta_x,
    delta_y,
    button,
    shift,
    meta,
    ctrl,
    screen_x=None,
    screen_y=None,
    style=None,
)

Bases: MouseEvent

Sent when the mouse wheel is scrolled down.

  • Bubbles
  • Verbose

MouseScrollUp 

MouseScrollUp(
    widget,
    x,
    y,
    delta_x,
    delta_y,
    button,
    shift,
    meta,
    ctrl,
    screen_x=None,
    screen_y=None,
    style=None,
)

Bases: MouseEvent

Sent when the mouse wheel is scrolled up.

  • Bubbles
  • Verbose

MouseUp 

MouseUp(
    widget,
    x,
    y,
    delta_x,
    delta_y,
    button,
    shift,
    meta,
    ctrl,
    screen_x=None,
    screen_y=None,
    style=None,
)

Bases: MouseEvent

Sent when a mouse button is released.

  • Bubbles
  • Verbose

Paste 

Paste(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

text instance-attribute 

text = text

The text that was pasted.

Print 

Print(text, stderr=False)

Bases: Event

Sent to a widget that is capturing print.

  • 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
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 

Ready()

Bases: Event

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

  • Bubbles
  • Verbose

Resize 

Resize(
    size, virtual_size, container_size=None, pixel_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

container_size instance-attribute 

container_size = (
    size if container_size is None else container_size
)

The size of the Widget's container widget.

pixel_size instance-attribute 

pixel_size = pixel_size

Size of terminal window in pixels if known, or None if not known.

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.

from_dimensions classmethod 

from_dimensions(cells, pixels)

Construct from basic dimensions.

Parameters:

Name Type Description Default

cells

tuple[int, int]

tuple of (, ) in cells.

 required

pixels

tuple[int, int] | None

tuple of (, ) in pixels if known, or None if not known.

 required

ScreenResume 

ScreenResume()

Bases: Event

Sent to screen that has been made active.

  • Bubbles
  • Verbose

ScreenSuspend 

ScreenSuspend()

Bases: Event

Sent to screen when it is no longer active.

  • Bubbles
  • Verbose

Show 

Show()

Bases: Event

Sent when a widget is first displayed.

  • Bubbles
  • Verbose

Timer 

Timer(timer, time, count=0, callback=None)

Bases: Event

Sent in response to a timer.

  • Bubbles
  • Verbose

Unmount 

Unmount()

Bases: Event

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

  • Bubbles
  • Verbose