Skip to content

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 str | PurePath | list[str | PurePath] | 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.

action(action, default_namespace=None) async

Perform an action.

Parameters:

Name Type Description Default
action str

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:

Name Type Description
bool bool

True if the event has handled.

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_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=Ellipsis, 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.

Ellipsis
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

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

Replacement text for key, or None to use default. Defaults to None.

None

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, universal=False) async

Handle a key press.

Parameters:

Name Type Description Default
key str

A key

required
universal bool

Check universal keys if True, otherwise non-universal keys.

False

Returns:

Name Type Description
bool bool

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

compose()

Yield child widgets for a container.

debug() property

exit(result=None)

Exit the app, and return the supplied result.

Parameters:

Name Type Description Default
result ReturnType | None

Return value. Defaults to None.

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.

focused() property

Widget | None: the widget that is focused on the currently active screen.

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

Require the object be of the supplied type, or None for any type. Defaults to None.

None

Returns:

Type Description
ExpectType | Widget

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_css_variables()

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

Returns:

Type Description
dict[str, str]

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:

Name Type Description
Driver 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:

Name Type Description
str 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:

Name Type Description
Screen Screen

A screen instance.

get_widget_at(x, y)

Get the widget under the given coordinates.

Parameters:

Name Type Description Default
x int

X Coord.

required
y int

Y Coord.

required

Returns:

Type Description
tuple[Widget, Region]

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

Require the object be of the supplied type, or None for any type. Defaults to None.

None

Returns:

Type Description
ExpectType | Widget

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=None)

Install a screen.

Parameters:

Name Type Description Default
screen Screen

Screen to install.

required
name str | None

Unique name of screen or None to auto-generate. Defaults to None.

None

Raises:

Type Description
ScreenError

If the screen can't be installed.

Returns:

Name Type Description
AwaitMount AwaitMount

An awaitable that awaits the mounting of the screen and its children.

is_headless() property

is_mounted(widget)

Check if a widget is mounted.

Parameters:

Name Type Description Default
widget Widget

A widget.

required

Returns:

Name Type Description
bool 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:

Name Type Description
bool bool

True if the screen is currently installed,

log() property

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

Optional location to mount before.

None
after int | str | Widget

Optional location to mount after.

None

Returns:

Name Type Description
AwaitMount 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

Optional location to mount before.

None
after int | str | Widget

Optional location to mount after.

None

Returns:

Name Type Description
AwaitMount 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.

namespace_bindings() 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.

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:

Name Type Description
Screen 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.

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

return_value() property

ReturnType | None: The return type of the app.

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

An auto pilot coroutine.

None

Returns:

Type Description
ReturnType | None

ReturnType | None: App return value.

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

An auto pilot coroutine.

None

Returns:

Type Description
ReturnType | None

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='%Y%m%d %H%M%S %f')

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

Time format to use if filename is None. Defaults to "%Y-%m-%d %X %f".

'%Y%m%d %H%M%S %f'

Returns:

Name Type Description
str str

Filename of screenshot.

screen() property

Raises:

Type Description
ScreenStackError

If there are no screens on the stack.

screen_stack() property

list[Screen]: A copy of the screen stack.

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

Widget to focus.

required
scroll_visible bool

Scroll widget in to view.

True

size() property

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.

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

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.