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:
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.
Click
class
¶
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
DescendantBlur
class
¶
DescendantFocus
class
¶
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 toFalse
. - 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
Key
class
¶
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 |
aliases
instance-attribute
¶
The aliases for the key, including the key itself.
character
instance-attribute
¶
A printable character or None
if it is not printable.
is_printable
property
¶
Check if the key is printable (produces a unicode character).
Returns
Type | Description |
---|---|
bool
|
|
name_aliases
property
¶
The corresponding name for every alias in aliases
list.
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
MouseCapture
class
¶
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
¶
The position of the mouse when captured.
MouseDown
class
¶
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. |
offset
property
¶
screen_x
instance-attribute
¶
The absolute x coordinate.
screen_y
instance-attribute
¶
The absolute y coordinate.
get_content_offset
method
¶
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
¶
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
¶
MouseRelease
class
¶
MouseScrollDown
class
¶
MouseScrollUp
class
¶
MouseUp
class
¶
Paste
class
¶
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. |
Print
class
¶
Ready
class
¶
Bases: Event
Sent to the App
when the DOM is ready and the first frame has been displayed.
- Bubbles
- Verbose
Resize
class
¶
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. |