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 to auto-detect. Defaults to None.	None
css_path	CSSPathType | None	Path to CSS or None for no CSS file. Defaults to None. To load multiple CSS files, pass a list of strings or paths which will be loaded in order.	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 value if not set.	...
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

Handle a key press.

Parameters:

Name	Type	Description	Default
key	str	A key.	required
priority	bool	If True check from App down, otherwise from focused up.	False

Returns:

Type	Description
bool	True if the key was handled by a binding, otherwise False

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 a child of a give type.

Parameters:

Name	Type	Description	Default
expect_type	type[ExpectType]	The type of the expected child.	required

Raises:

Type	Description
NoMatches	If no valid child is found.

Returns:

Type	Description
ExpectType	A widget.

get_css_variables()

Get a mapping of variables used to pre-populate CSS.

Returns:

Type	Description
dict[str, str]	A mapping of variable name to value.

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 an installed screen.

Parameters:

Name	Type	Description	Default
screen	Screen | str	Either a Screen object or screen name (the name argument when installed).	required

Raises:

Type	Description
KeyError	If the named screen doesn't exist.

Returns:

Type	Description
Screen	A screen instance.

get_widget_at(x, y)

Get the widget under the given coordinates.

Parameters:

Name	Type	Description	Default
x	int	X coordinate.	required
y	int	Y coordinate.	required

Returns:

Type	Description
tuple[Widget, Region]	The widget and the widget's screen region.

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)

Check if a widget is mounted.

Parameters:

Name	Type	Description	Default
widget	Widget	A widget.	required

Returns:

Type	Description
bool	True of the widget is mounted.

is_screen_installed(screen)

Check if a given screen has been installed.

Parameters:

Name	Type	Description	Default
screen	Screen | str	Either a Screen object or screen name (the name argument when installed).	required

Returns:

Type	Description
bool	True if the screen is currently installed,

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 int is the index of the child to mount before, a str is a query_one query to find the widget to mount before.	None
after	int | str | Widget | None	Optional location to mount after. An int is the index of the child to mount after, a str is a query_one query to find the widget to mount after.	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 int is the index of the child to mount before, a str is a query_one query to find the widget to mount before.	None
after	int | str | Widget | None	Optional location to mount after. An int is the index of the child to mount after, a str is a query_one query to find the widget to mount after.	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)

Push a new screen on the screen stack, making it the current screen.

Parameters:

Name	Type	Description	Default
screen	Screen | str	A Screen instance or the name of an installed screen.	required

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 (WIDTH, HEIGHT), or None to auto-detect. Defaults to None.	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 (WIDTH, HEIGHT), or None to auto-detect. Defaults to None.	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

An asynchronous context manager for testing app.

Parameters:

Name	Type	Description	Default
headless	bool	Run in headless mode (no output or input). Defaults to True.	True
size	tuple[int, int] | None	Force terminal size to (WIDTH, HEIGHT), or None to auto-detect. Defaults to None.	(80, 24)

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)

Focus (or unfocus) a widget. A focused widget will receive key events first.

Parameters:

Name	Type	Description	Default
widget	Widget | None	Widget to focus.	required
scroll_visible	bool	Scroll widget in to view.	True

switch_screen(screen)

Switch to another screen by replacing the top of the screen stack with a new screen.

Parameters:

Name	Type	Description	Default
screen	Screen | str	Either a Screen object or screen name (the name argument when installed).	required

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.

CssPathError

Bases: Exception

Raised when supplied CSS path(s) are invalid.

ScreenStackError

Bases: ScreenError

Raised when attempting to pop the last screen from the stack.