App
app
¶
App
¶
Bases: Generic[ReturnType]
, DOMNode
The base class for Textual Applications.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
driver_class |
Type[Driver] | None
|
Driver class or |
None
|
css_path |
CSSPathType | None
|
Path to CSS or |
None
|
watch_css |
bool
|
Watch CSS for changes. Defaults to False. |
False
|
Raises:
Type | Description |
---|---|
CssPathError
|
When the supplied CSS path(s) are an unexpected type. |
CSS
class-attribute
¶
Inline CSS, useful for quick scripts. This is loaded after CSS_PATH, and therefore takes priority in the event of a specificity clash.
SUB_TITLE: str | None
class-attribute
¶
str | None: The default sub-title for the application.
If set to a string, this sets the default sub-title for the application. See
also the sub_title
attribute.
TITLE: str | None
class-attribute
¶
str | None: The default title for the application.
If set to a string, this sets the default title for the application. See
also the title
attribute.
children: Sequence[Widget]
property
¶
A view on to the children which contains just the screen.
debug: bool
property
¶
Is debug mode enabled?
focused: Widget | None
property
¶
Widget | None: the widget that is focused on the currently active screen.
is_headless: bool
property
¶
Is the driver running in 'headless' mode?
log: Logger
property
¶
namespace_bindings: dict[str, tuple[DOMNode, Binding]]
property
¶
Get current bindings. If no widget is focused, then the app-level bindings are returned. If a widget is focused, then any bindings present in the active screen and app are merged and returned.
return_value: ReturnType | None
property
¶
ReturnType | None: The return type of the app.
screen: Screen
property
¶
Raises:
Type | Description |
---|---|
ScreenStackError
|
If there are no screens on the stack. |
screen_stack: list[Screen]
property
¶
list[Screen]: A copy of the screen stack.
scroll_sensitivity_x: float
instance-attribute
¶
Number of columns to scroll in the X direction with wheel or trackpad.
scroll_sensitivity_y: float
instance-attribute
¶
Number of lines to scroll in the Y direction with wheel or trackpad.
size: Size
property
¶
sub_title
instance-attribute
¶
The sub-title for the application.
The initial value in a running application will be that set in SUB_TITLE
(if one is set). Assign new values to this instance attribute to change
the sub-title.
title
instance-attribute
¶
The title for the application.
The initial value in a running application will be that set in TITLE
(if one is set). Assign new values to this instance attribute to change
the title.
action_bell()
async
¶
Play the terminal 'bell'.
action_focus(widget_id)
async
¶
Focus the given widget.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
widget_id |
str
|
ID of widget to focus. |
required |
action_focus_next()
¶
Focus the next widget.
action_focus_previous()
¶
Focus the previous widget.
action_pop_screen()
async
¶
Removes the topmost screen and makes the new topmost screen active.
action_push_screen(screen)
async
¶
Pushes a screen on to the screen stack and makes it active.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
screen |
str
|
Name of the screen. |
required |
action_quit()
async
¶
Quit the app as soon as possible.
action_screenshot(filename=None, path='./')
¶
Save an SVG "screenshot". This action will save an SVG file containing the current contents of the screen.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
filename |
str | None
|
Filename of screenshot, or None to auto-generate. Defaults to None. |
None
|
path |
str
|
Path to directory. Defaults to current working directory. |
'./'
|
action_switch_screen(screen)
async
¶
Switches to another screen.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
screen |
str
|
Name of the screen. |
required |
action_toggle_dark()
¶
Action to toggle dark mode.
animate(attribute, value, *, final_value=..., duration=None, speed=None, delay=0.0, easing=DEFAULT_EASING, on_complete=None)
¶
Animate an attribute.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
attribute |
str
|
Name of the attribute to animate. |
required |
value |
float | Animatable
|
The value to animate to. |
required |
final_value |
object
|
The final value of the animation. Defaults to |
...
|
duration |
float | None
|
The duration of the animate. Defaults to None. |
None
|
speed |
float | None
|
The speed of the animation. Defaults to None. |
None
|
delay |
float
|
A delay (in seconds) before the animation starts. Defaults to 0.0. |
0.0
|
easing |
EasingFunction | str
|
An easing method. Defaults to "in_out_cubic". |
DEFAULT_EASING
|
on_complete |
CallbackType | None
|
A callable to invoke when the animation is finished. Defaults to None. |
None
|
batch_update()
¶
A context manager to suspend all repaints until the end of the batch.
bell()
¶
Play the console 'bell'.
bind(keys, action, *, description='', show=True, key_display=None)
¶
Bind a key to an action.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
keys |
str
|
A comma separated list of keys, i.e. |
required |
action |
str
|
Action to bind to. |
required |
description |
str
|
Short description of action. Defaults to "". |
''
|
show |
bool
|
Show key in UI. Defaults to True. |
True
|
key_display |
str | None
|
Replacement text for key, or None to use default. Defaults to None. |
None
|
call_from_thread(callback, *args, **kwargs)
¶
Run a callback from another thread.
Like asyncio apps in general, Textual apps are not thread-safe. If you call methods or set attributes on Textual objects from a thread, you may get unpredictable results.
This method will ensure that your code runs within the correct context.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
callback |
Callable[..., CallThreadReturnType | Awaitable[CallThreadReturnType]]
|
A callable to run. |
required |
*args |
Arguments to the callback. |
()
|
|
**kwargs |
Keyword arguments for the callback. |
{}
|
Raises:
Type | Description |
---|---|
RuntimeError
|
If the app isn't running or if this method is called from the same thread where the app is running. |
capture_mouse(widget)
¶
Send all mouse events to the given widget, disable mouse capture.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
widget |
Widget | None
|
If a widget, capture mouse event, or None to end mouse capture. |
required |
check_bindings(key, priority=False)
async
¶
compose()
¶
Yield child widgets for a container.
exit(result=None, message=None)
¶
Exit the app, and return the supplied result.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
result |
ReturnType | None
|
Return value. Defaults to None. |
None
|
message |
RenderableType | None
|
Optional message to display on exit. |
None
|
export_screenshot(*, title=None)
¶
Export an SVG screenshot of the current screen.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
title |
str | None
|
The title of the exported screenshot or None to use app title. Defaults to None. |
None
|
fatal_error()
¶
Exits the app after an unhandled exception.
get_child_by_id(id, expect_type=None)
¶
Shorthand for self.screen.get_child(id: str) Returns the first child (immediate descendent) of this DOMNode with the given ID.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
id |
str
|
The ID of the node to search for. |
required |
expect_type |
type[ExpectType] | None
|
Require the object be of the supplied type, or None for any type. Defaults to None. |
None
|
Returns:
Type | Description |
---|---|
ExpectType | Widget
|
The first child of this node with the specified ID. |
Raises:
Type | Description |
---|---|
NoMatches
|
if no children could be found for this ID |
WrongType
|
if the wrong type was found. |
get_child_by_type(expect_type)
¶
get_css_variables()
¶
get_driver_class()
¶
Get a driver class for this platform.
Called by the constructor.
Returns:
Type | Description |
---|---|
Type[Driver]
|
A Driver class which manages input and display. |
get_key_display(key)
¶
For a given key, return how it should be displayed in an app (e.g. in the Footer widget). By key, we refer to the string used in the "key" argument for a Binding instance. By overriding this method, you can ensure that keys are displayed consistently throughout your app, without needing to add a key_display to every binding.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
key |
str
|
The binding key string. |
required |
Returns:
Type | Description |
---|---|
str
|
The display string for the input key. |
get_screen(screen)
¶
get_widget_at(x, y)
¶
get_widget_by_id(id, expect_type=None)
¶
Shorthand for self.screen.get_widget_by_id(id) Return the first descendant widget with the given ID.
Performs a breadth-first search rooted at the current screen.
It will not return the Screen if that matches the ID.
To get the screen, use self.screen
.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
id |
str
|
The ID to search for in the subtree |
required |
expect_type |
type[ExpectType] | None
|
Require the object be of the supplied type, or None for any type. Defaults to None. |
None
|
Returns:
Type | Description |
---|---|
ExpectType | Widget
|
The first descendant encountered with this ID. |
Raises:
Type | Description |
---|---|
NoMatches
|
if no children could be found for this ID |
WrongType
|
if the wrong type was found. |
install_screen(screen, name)
¶
Install a screen.
Installing a screen prevents Textual from destroying it when it is no longer on the screen stack. Note that you don't need to install a screen to use it. See push_screen or switch_screen to make a new screen current.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
screen |
Screen
|
Screen to install. |
required |
name |
str
|
Unique name to identify the screen. |
required |
Raises:
Type | Description |
---|---|
ScreenError
|
If the screen can't be installed. |
Returns:
Type | Description |
---|---|
None
|
An awaitable that awaits the mounting of the screen and its children. |
is_mounted(widget)
¶
is_screen_installed(screen)
¶
mount(*widgets, before=None, after=None)
¶
Mount the given widgets relative to the app's screen.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
*widgets |
Widget
|
The widget(s) to mount. |
()
|
before |
int | str | Widget | None
|
Optional location to mount before. An |
None
|
after |
int | str | Widget | None
|
Optional location to mount after. An |
None
|
Returns:
Type | Description |
---|---|
AwaitMount
|
An awaitable object that waits for widgets to be mounted. |
Raises:
Type | Description |
---|---|
MountError
|
If there is a problem with the mount request. |
Note
Only one of before
or after
can be provided. If both are
provided a MountError
will be raised.
mount_all(widgets, *, before=None, after=None)
¶
Mount widgets from an iterable.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
widgets |
Iterable[Widget]
|
An iterable of widgets. |
required |
before |
int | str | Widget | None
|
Optional location to mount before. An |
None
|
after |
int | str | Widget | None
|
Optional location to mount after. An |
None
|
Returns:
Type | Description |
---|---|
AwaitMount
|
An awaitable object that waits for widgets to be mounted. |
Raises:
Type | Description |
---|---|
MountError
|
If there is a problem with the mount request. |
Note
Only one of before
or after
can be provided. If both are
provided a MountError
will be raised.
panic(*renderables)
¶
Exits the app then displays a message.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
*renderables |
RenderableType
|
Rich renderables to display on exit. |
()
|
pop_screen()
¶
Pop the current screen from the stack, and switch to the previous screen.
Returns:
Type | Description |
---|---|
Screen
|
The screen that was replaced. |
post_display_hook()
¶
Called immediately after a display is done. Used in tests.
push_screen(screen)
¶
refresh_css(animate=True)
¶
Refresh CSS.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
animate |
bool
|
Also execute CSS animations. Defaults to True. |
True
|
run(*, headless=False, size=None, auto_pilot=None)
¶
Run the app.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
headless |
bool
|
Run in headless mode (no output). Defaults to False. |
False
|
size |
tuple[int, int] | None
|
Force terminal size to |
None
|
auto_pilot |
AutopilotCallbackType | None
|
An auto pilot coroutine. |
None
|
Returns:
Type | Description |
---|---|
ReturnType | None
|
App return value. |
run_action(action, default_namespace=None)
async
¶
Perform an action.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
action |
str | ActionParseResult
|
Action encoded in a string. |
required |
default_namespace |
object | None
|
Namespace to use if not provided in the action, or None to use app. Defaults to None. |
None
|
Returns:
Type | Description |
---|---|
bool
|
True if the event has handled. |
run_async(*, headless=False, size=None, auto_pilot=None)
async
¶
Run the app asynchronously.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
headless |
bool
|
Run in headless mode (no output). Defaults to False. |
False
|
size |
tuple[int, int] | None
|
Force terminal size to |
None
|
auto_pilot |
AutopilotCallbackType | None
|
An auto pilot coroutine. |
None
|
Returns:
Type | Description |
---|---|
ReturnType | None
|
App return value. |
run_test(*, headless=True, size=(80, 24))
async
¶
save_screenshot(filename=None, path='./', time_format=None)
¶
Save an SVG screenshot of the current screen.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
filename |
str | None
|
Filename of SVG screenshot, or None to auto-generate a filename with the date and time. Defaults to None. |
None
|
path |
str
|
Path to directory for output. Defaults to current working directory. |
'./'
|
time_format |
str | None
|
Date and time format to use if filename is None. Defaults to a format like ISO 8601 with some reserved characters replaced with underscores. |
None
|
Returns:
Type | Description |
---|---|
str
|
Filename of screenshot. |
set_focus(widget, scroll_visible=True)
¶
switch_screen(screen)
¶
uninstall_screen(screen)
¶
Uninstall a screen.
If the screen was not previously installed then this method is a null-op. Uninstalling a screen allows Textual to delete it when it is popped or switched. Note that uninstalling a screen is only required if you have previously installed it with install_screen. Textual will also uninstall screens automatically on exit.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
screen |
Screen | str
|
The screen to uninstall or the name of a installed screen. |
required |
Returns:
Type | Description |
---|---|
str | None
|
The name of the screen that was uninstalled, or None if no screen was uninstalled. |
update_styles(node=None)
¶
Request update of styles.
Should be called whenever CSS classes / pseudo classes change.
watch_dark(dark)
¶
Watches the dark bool.
ScreenStackError
¶
Bases: ScreenError
Raised when attempting to pop the last screen from the stack.