textual.app

Here you will find the App class, which is the base class for Textual apps.

See app basics for how to build Textual apps.

AutopilotCallbackType module-attribute

AutopilotCallbackType = (
    "Callable[[Pilot[object]], Coroutine[Any, Any, None]]"
)

Signature for valid callbacks that can be used to control apps.

CommandCallback module-attribute

CommandCallback = (
    "Callable[[], Awaitable[Any]] | Callable[[], Any]"
)

Signature for callbacks used in get_system_commands

RenderResult module-attribute

RenderResult = 'RenderableType | Visual | SupportsVisual'

Result of Widget.render()

ScreenType module-attribute

ScreenType = TypeVar('ScreenType', bound=Screen)

Type var for a Screen, used in get_screen.

ActionError

Bases: Exception

Base class for exceptions relating to actions.

ActiveModeError

Bases: ModeError

Raised when attempting to remove the currently active mode.

App

App(
    driver_class=None,
    css_path=None,
    watch_css=False,
    ansi_color=False,
)

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. This will be used by some Textual tools.	None
css_path	CSSPathType | None	Path to CSS or None to use the CSS_PATH class variable. To load multiple CSS files, pass a list of strings or paths which will be loaded in order.	None
watch_css	bool	Reload CSS if the files changed. This is set automatically if you are using textual run with the dev switch.	False
ansi_color	bool	Allow ANSI colors if True, or convert ANSI colors to to RGB if False.	False

Raises:

Type	Description
CssPathError	When the supplied CSS path(s) are an unexpected type.

ALLOW_IN_MAXIMIZED_VIEW class-attribute

ALLOW_IN_MAXIMIZED_VIEW = 'Footer'

The default value of Screen.ALLOW_IN_MAXIMIZED_VIEW.

ALLOW_SELECT class-attribute

ALLOW_SELECT = True

A switch to toggle arbitrary text selection for the app.

Note that this doesn't apply to Input and TextArea which have builtin support for selection.

AUTO_FOCUS class-attribute

AUTO_FOCUS = '*'

A selector to determine what to focus automatically when a screen is activated.

The widget focused is the first that matches the given CSS selector. Setting to None or "" disables auto focus.

BINDINGS class-attribute

BINDINGS = [
    Binding(
        "ctrl+q",
        "quit",
        "Quit",
        tooltip="Quit the app and return to the command prompt.",
        show=False,
        priority=True,
    ),
    Binding("ctrl+c", "help_quit", show=False, system=True),
]

The default key bindings.

BINDING_GROUP_TITLE class-attribute instance-attribute

BINDING_GROUP_TITLE = None

Set to text to show in the key panel.

CLICK_CHAIN_TIME_THRESHOLD class-attribute

CLICK_CHAIN_TIME_THRESHOLD = 0.5

The maximum number of seconds between clicks to upgrade a single click to a double click, a double click to a triple click, etc.

CLOSE_TIMEOUT class-attribute instance-attribute

CLOSE_TIMEOUT = 5.0

Timeout waiting for widget's to close, or None for no timeout.

COMMANDS class-attribute

COMMANDS = {get_system_commands_provider}

Command providers used by the command palette.

Should be a set of command.Provider classes.

COMMAND_PALETTE_BINDING class-attribute

COMMAND_PALETTE_BINDING = 'ctrl+p'

The key that launches the command palette (if enabled by App.ENABLE_COMMAND_PALETTE).

COMMAND_PALETTE_DISPLAY class-attribute

COMMAND_PALETTE_DISPLAY = None

How the command palette key should be displayed in the footer (or None for default).

CSS class-attribute

CSS = ''

Inline CSS, useful for quick scripts. This is loaded after CSS_PATH, and therefore takes priority in the event of a specificity clash.

CSS_PATH class-attribute

CSS_PATH = None

File paths to load CSS from.

DEFAULT_MODE class-attribute

DEFAULT_MODE = '_default'

Name of the default mode.

ENABLE_COMMAND_PALETTE class-attribute

ENABLE_COMMAND_PALETTE = True

Should the command palette be enabled for the application?

ESCAPE_TO_MINIMIZE class-attribute

ESCAPE_TO_MINIMIZE = True

Use escape key to minimize widgets (potentially overriding bindings).

This is the default value, used if the active screen's ESCAPE_TO_MINIMIZE is not changed from None.

HORIZONTAL_BREAKPOINTS class-attribute instance-attribute

HORIZONTAL_BREAKPOINTS = []

List of horizontal breakpoints for responsive classes.

This allows for styles to be responsive to the dimensions of the terminal. For instance, you might want to show less information, or fewer columns on a narrow displays -- or more information when the terminal is sized wider than usual.

A breakpoint consists of a tuple containing the minimum width where the class should applied, and the name of the class to set.

Note that only one class name is set, and if you should avoid having more than one breakpoint set for the same size.

Example

# Up to 80 cells wide, the app has the class "-normal"
# 80 - 119 cells wide, the app has the class "-wide"
# 120 cells or wider, the app has the class "-very-wide"
HORIZONTAL_BREAKPOINTS = [(0, "-normal"), (80, "-wide"), (120, "-very-wide")]

INLINE_PADDING class-attribute

INLINE_PADDING = 1

Number of blank lines above an inline app.

MODES class-attribute

MODES = {}

Modes associated with the app and their base screens.

The base screen is the screen at the bottom of the mode stack. You can think of it as the default screen for that stack. The base screens can be names of screens listed in SCREENS, Screen instances, or callables that return screens.

Example

class HelpScreen(Screen[None]):
    ...

class MainAppScreen(Screen[None]):
    ...

class MyApp(App[None]):
    MODES = {
        "default": "main",
        "help": HelpScreen,
    }

    SCREENS = {
        "main": MainAppScreen,
    }

    ...

NOTIFICATION_TIMEOUT class-attribute

NOTIFICATION_TIMEOUT = 5

Default number of seconds to show notifications before removing them.

SCREENS class-attribute

SCREENS = {}

Screens associated with the app for the lifetime of the app.

SUB_TITLE class-attribute instance-attribute

SUB_TITLE = None

A class variable to set the default sub-title for the application.

To update the sub-title while the app is running, you can set the sub_title attribute. See also the Screen.SUB_TITLE attribute.

SUSPENDED_SCREEN_CLASS class-attribute

SUSPENDED_SCREEN_CLASS = ''

Class to apply to suspended screens, or empty string for no class.

TITLE class-attribute instance-attribute

TITLE = None

A class variable to set the default title for the application.

To update the title while the app is running, you can set the title attribute. See also the Screen.TITLE attribute.

TOOLTIP_DELAY class-attribute instance-attribute

TOOLTIP_DELAY = 0.5

The time in seconds after which a tooltip gets displayed.

VERTICAL_BREAKPOINTS class-attribute instance-attribute

VERTICAL_BREAKPOINTS = []

List of vertical breakpoints for responsive classes.

Contents are the same as HORIZONTAL_BREAKPOINTS, but the integer is compared to the height, rather than the width.

active_bindings property

active_bindings

Get currently active bindings.

If no widget is focused, then app-level bindings are returned. If a widget is focused, then any bindings present in the active screen and app are merged and returned.

This property may be used to inspect current bindings.

Returns:

Type	Description
dict[str, ActiveBinding]	A dict that maps keys on to binding information.

animation_level instance-attribute

animation_level = TEXTUAL_ANIMATIONS

Determines what type of animations the app will display.

See textual.constants.TEXTUAL_ANIMATIONS.

animator property

animator

The animator object.

ansi_color class-attribute instance-attribute

ansi_color = Reactive(False)

Allow ANSI colors in UI?

ansi_theme property

ansi_theme

The ANSI TerminalTheme currently being used.

Defines how colors defined as ANSI (e.g. magenta) inside Rich renderables are mapped to hex codes.

ansi_theme_dark class-attribute instance-attribute

ansi_theme_dark = Reactive(MONOKAI, init=False)

Maps ANSI colors to hex colors using a Rich TerminalTheme object while using a dark theme.

ansi_theme_light class-attribute instance-attribute

ansi_theme_light = Reactive(ALABASTER, init=False)

Maps ANSI colors to hex colors using a Rich TerminalTheme object while using a light theme.

app_focus class-attribute instance-attribute

app_focus = Reactive(True, compute=False)

Indicates if the app has focus.

When run in the terminal, the app always has focus. When run in the web, the app will get focus when the terminal widget has focus.

app_resume_signal instance-attribute

app_resume_signal = Signal(self, 'app-resume')

The signal that is published when the app is resumed after a suspend.

When the app is resumed after a App.suspend call this signal will be published; subscribe to this signal to perform work after the app has resumed.

app_suspend_signal instance-attribute

app_suspend_signal = Signal(self, 'app-suspend')

The signal that is published when the app is suspended.

When App.suspend is called this signal will be published; subscribe to this signal to perform work before the suspension takes place.

available_themes property

available_themes

All available themes (all built-in themes plus any that have been registered).

A dictionary mapping theme names to Theme instances.

children property

children

A view onto the app's immediate children.

This attribute exists on all widgets. In the case of the App, it will only ever contain a single child, which will be the currently active screen.

Returns:

Type	Description
Sequence['Widget']	A sequence of widgets.

clipboard property

clipboard

The value of the local clipboard.

Note, that this only contains text copied in the app, and not text copied from elsewhere in the OS.

console_options property

console_options

Get options for the Rich console.

Returns:

Type	Description
ConsoleOptions	Console options (same object returned from console.options).

current_mode property

current_mode

The name of the currently active mode.

cursor_position instance-attribute

cursor_position = Offset(0, 0)

The position of the terminal cursor in screen-space.

This can be set by widgets and is useful for controlling the positioning of OS IME and emoji popup menus.

debug property

debug

Is debug mode enabled?

default_screen property

default_screen

The default screen instance.

escape_to_minimize property

escape_to_minimize

Use the escape key to minimize?

When a widget is maximized, this boolean determines if the escape key will minimize the widget (potentially overriding any bindings).

The default logic is to use the screen's ESCAPE_TO_MINIMIZE classvar if it is set to True or False. If the classvar on the screen is not set (and left as None), then the app's ESCAPE_TO_MINIMIZE is used.

focused property

focused

The widget that is focused on the currently active screen, or None.

Focused widgets receive keyboard input.

Returns:

Type	Description
Widget | None	The currently focused widget, or None if nothing is focused.

hover_over instance-attribute

hover_over = None

The first widget with a hover style under the mouse.

is_attached property

is_attached

Is this node linked to the app through the DOM?

is_dom_root property

is_dom_root

Is this a root node (i.e. the App)?

is_headless property

is_headless

Is the app running in 'headless' mode?

Headless mode is used when running tests with run_test.

is_inline property

is_inline

Is the app running in 'inline' mode?

is_web property

is_web

Is the app running in 'web' mode via a browser?

log property

log

The textual logger.

Example

self.log("Hello, World!")
self.log(self.tree)

Returns:

Type	Description
Logger	A Textual logger.

mouse_over instance-attribute

mouse_over = None

The widget directly under the mouse.

return_code property

return_code

The return code with which the app exited.

Non-zero codes indicate errors. A value of 1 means the app exited with a fatal error. If the app hasn't exited yet, this will be None.

Example

The return code can be used to exit the process via sys.exit.

my_app.run()
sys.exit(my_app.return_code)

return_value property

return_value

The return value of the app, or None if it has not yet been set.

The return value is set when calling exit.

screen property

screen

The current active screen.

Returns:

Type	Description
Screen[object]	The currently active (visible) screen.

Raises:

Type	Description
ScreenStackError	If there are no screens on the stack.

screen_stack property

screen_stack

A snapshot of the current screen stack.

Returns:

Type	Description
list[Screen[Any]]	A snapshot of the current state of the screen stack.

scroll_sensitivity_x instance-attribute

scroll_sensitivity_x = 4.0

Number of columns to scroll in the X direction with wheel or trackpad.

scroll_sensitivity_y instance-attribute

scroll_sensitivity_y = 2.0

Number of lines to scroll in the Y direction with wheel or trackpad.

size property

size

The size of the terminal.

Returns:

Type	Description
Size	Size of the terminal.

sub_title class-attribute instance-attribute

sub_title = SUB_TITLE if SUB_TITLE is not None else ''

The sub-title for the application.

The initial value for sub_title will be set to the SUB_TITLE class variable if it exists, or an empty string if it doesn't.

Sub-titles are typically used to show the high-level state of the app, such as the current mode, or path to the file being worked on.

Assign a new value to this attribute to change the sub-title. The new value is always converted to string.

supports_smooth_scrolling instance-attribute

supports_smooth_scrolling = False

Does the terminal support smooth scrolling?

theme class-attribute instance-attribute

theme = Reactive(DEFAULT_THEME)

The name of the currently active theme.

theme_changed_signal instance-attribute

theme_changed_signal = Signal(self, 'theme-changed')

Signal that is published when the App's theme is changed.

Subscribers will receive the new theme object as an argument to the callback.

theme_variables instance-attribute

theme_variables = {}

Variables generated from the current theme.

title class-attribute instance-attribute

title = TITLE if TITLE is not None else f'{__name__}'

The title for the application.

The initial value for title will be set to the TITLE class variable if it exists, or the name of the app if it doesn't.

Assign a new value to this attribute to change the title. The new value is always converted to string.

use_command_palette instance-attribute

use_command_palette = ENABLE_COMMAND_PALETTE

A flag to say if the application should use the command palette.

If set to False any call to action_command_palette will be ignored.

viewport_size property

viewport_size

Get the viewport size (size of the screen).

workers property

workers

The worker manager.

Returns:

Type	Description
WorkerManager	An object to manage workers.

action_add_class async

action_add_class(selector, class_name)

An action to add a CSS class to the selected widget.

Parameters:

Name	Type	Description	Default
selector	str	Selects the widget to add the class to.	required
class_name	str	The class to add to the selected widget.	required

action_back async

action_back()

An action to go back to the previous screen (pop the current screen).

Note

If there is no screen to go back to, this is a non-operation (in other words it's safe to call even if there are no other screens on the stack.)

action_bell async

action_bell()

An action to play the terminal 'bell'.

action_change_theme

action_change_theme()

An action to change the current theme.

action_command_palette

action_command_palette()

Show the Textual command palette.

action_focus async

action_focus(widget_id)

An action to focus the given widget.

Parameters:

Name	Type	Description	Default
widget_id	str	ID of widget to focus.	required

action_focus_next

action_focus_next()

An action to focus the next widget.

action_focus_previous

action_focus_previous()

An action to focus the previous widget.

action_help_quit

action_help_quit()

Bound to ctrl+C to alert the user that it no longer quits.

action_hide_help_panel

action_hide_help_panel()

Hide the keys panel (if present).

action_notify

action_notify(message, title='', severity='information')

Show a notification.

action_pop_screen async

action_pop_screen()

An action to remove the topmost screen and makes the new topmost screen active.

action_push_screen async

action_push_screen(screen)

An action to push a new screen on to the stack and make it active.

Parameters:

Name	Type	Description	Default
screen	str	Name of the screen.	required

action_quit async

action_quit()

An action to quit the app as soon as possible.

action_remove_class async

action_remove_class(selector, class_name)

An action to remove a CSS class from the selected widget.

Parameters:

Name	Type	Description	Default
selector	str	Selects the widget to remove the class from.	required
class_name	str	The class to remove from the selected widget.	required

action_screenshot

action_screenshot(filename=None, path=None)

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.	None
path	str | None	Path to directory. Defaults to the user's Downloads directory.	None

action_show_help_panel

action_show_help_panel()

Show the keys panel.

action_simulate_key async

action_simulate_key(key)

An action to simulate a key press.

This will invoke the same actions as if the user had pressed the key.

Parameters:

Name	Type	Description	Default
key	str	The key to process.	required

action_suspend_process

action_suspend_process()

Suspend the process into the background.

Note

On Unix and Unix-like systems a SIGTSTP is sent to the application's process. Currently on Windows and when running under Textual Web this is a non-operation.

action_switch_mode async

action_switch_mode(mode)

An action that switches to the given mode.

action_switch_screen async

action_switch_screen(screen)

An action to switch screens.

Parameters:

Name	Type	Description	Default
screen	str	Name of the screen.	required

action_toggle_class async

action_toggle_class(selector, class_name)

An