textual.screen

This module contains the Screen class and related objects.

The Screen class is a special widget which represents the content in the terminal. See Screens for details.

ScreenResultCallbackType module-attribute

ScreenResultCallbackType = Union[
    Callable[[Optional[ScreenResultType]], None],
    Callable[[Optional[ScreenResultType]], Awaitable[None]],
]

Type of a screen result callback function.

ScreenResultType module-attribute

ScreenResultType = TypeVar('ScreenResultType')

The result type of a screen.

ModalScreen

ModalScreen(name=None, id=None, classes=None)

Bases: Screen[ScreenResultType]

A screen with bindings that take precedence over the App's key bindings.

The default styling of a modal screen will dim the screen underneath.

ResultCallback

ResultCallback(requester, callback, future=None)

Bases: Generic[ScreenResultType]

Holds the details of a callback.

Parameters:

Name	Type	Description	Default
requester	MessagePump	The object making a request for the callback.	required
callback	ScreenResultCallbackType[ScreenResultType] | None	The callback function.	required
future	asyncio.Future[ScreenResultType] | None	A Future to hold the result.	None

callback instance-attribute

callback: ScreenResultCallbackType | None = callback

The callback function.

future instance-attribute

future = future

A future for the result

requester instance-attribute

requester = requester

The object in the DOM that requested the callback.

Screen

Screen(name=None, id=None, classes=None)

Bases: Generic[ScreenResultType], Widget

The base class for screens.

Parameters:

Name	Type	Description	Default
name	str | None	The name of the screen.	None
id	str | None	The ID of the screen in the DOM.	None
classes	str | None	The CSS classes for the screen.	None

ALLOW_IN_MAXIMIZED_VIEW class-attribute

ALLOW_IN_MAXIMIZED_VIEW: str | None = None

A selector for the widgets (direct children of Screen) that are allowed in the maximized view (in addition to maximized widget). Or None to default to App.ALLOW_IN_MAXIMIZED_VIEW

AUTO_FOCUS class-attribute

AUTO_FOCUS: str | None = None

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

The widget focused is the first that matches the given CSS selector. Set to None to inherit the value from the screen's app. Set to "" to disable auto focus.

COMMANDS class-attribute

COMMANDS: set[
    type[Provider] | Callable[[], type[Provider]]
] = set()

Command providers used by the command palette, associated with the screen.

Should be a set of command.Provider classes.

CSS class-attribute

CSS: str = ''

Inline CSS, useful for quick scripts. Rules here take priority over CSS_PATH.

Note

This CSS applies to the whole app.

CSS_PATH class-attribute

CSS_PATH: CSSPathType | None = None

File paths to load CSS from.

Note

This CSS applies to the whole app.

ESCAPE_TO_MINIMIZE class-attribute

ESCAPE_TO_MINIMIZE: bool | None = None

Use escape key to minimize (potentially overriding bindings) or None to defer to App.ESCAPE_TO_MINIMIZE.

SUB_TITLE class-attribute

SUB_TITLE: str | None = None

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

This overrides the app sub-title. To update the sub-title while the screen is running, you can set the sub_title attribute.

TITLE class-attribute

TITLE: str | None = None

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

This overrides the app title. To update the title while the screen is running, you can set the title attribute.

active_bindings property

active_bindings: dict[str, ActiveBinding]

Get currently active bindings for this screen.

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

This property may be used to inspect current bindings.

Returns:

Type	Description
dict[str, ActiveBinding]	A map of keys to a tuple containing (NAMESPACE, BINDING, ENABLED).

allow_select property

allow_select: bool

Check if this widget permits text selection.

bindings_updated_signal instance-attribute

bindings_updated_signal: Signal[Screen] = Signal(
    self, "bindings_updated"
)

A signal published when the bindings have been updated

focus_chain property

focus_chain: list[Widget]

A list of widgets that may receive focus, in focus order.

focused class-attribute instance-attribute

focused: Reactive[Widget | None] = Reactive(None)

The focused widget or None for no focus. To set focus, do not update this value directly. Use set_focus instead.

is_active property

is_active: bool

Is the screen active (i.e. visible and top of the stack)?

is_current property

is_current: bool

Is the screen current (i.e. visible to user)?

is_modal property

is_modal: bool

Is the screen modal?

layers property

layers: tuple[str, ...]

Layers from parent.

Returns:

Type	Description
tuple[str, ...]	Tuple of layer names.

maximized class-attribute instance-attribute

maximized: Reactive[Widget | None] = Reactive(
    None, layout=True
)

The currently maximized widget, or None for no maximized widget.

screen_layout_refresh_signal instance-attribute

screen_layout_refresh_signal: Signal[Screen] = Signal(
    self, "layout-refresh"
)

The signal that is published when the screen's layout is refreshed.

selections class-attribute instance-attribute

selections: var[dict[Widget, Selection]] = var(dict)

Map of widgets and selected ranges.

stack_updates class-attribute instance-attribute

stack_updates: Reactive[int] = Reactive(0, repaint=False)

An integer that updates when the screen is resumed.

sub_title class-attribute instance-attribute

sub_title: Reactive[str | None] = self.SUB_TITLE

Screen sub-title to override the app sub-title.

text_selection_started_signal instance-attribute

text_selection_started_signal: Signal[Screen] = Signal(
    self, "selection_started"
)

A signal published when text selection has started.

title class-attribute instance-attribute

title: Reactive[str | None] = self.TITLE

Screen title to override the app title.

action_blur

action_blur()

Action to remove focus (if set).

action_copy_text

action_copy_text()

Copy selected text to clipboard.

action_dismiss async

action_dismiss(result=None)

A wrapper around dismiss that can be called as an action.

Parameters:

Name	Type	Description	Default
result	ScreenResultType | None	The optional result to be passed to the result callback.	None

action_maximize

action_maximize()

Action to maximize the currently focused widget.

action_minimize

action_minimize()

Action to minimize the currently maximized widget.

can_view_entire

can_view_entire(widget)

Check if a given widget is fully within the current screen.

Note: This doesn't necessarily equate to a widget being visible. There are other reasons why a widget may not be visible.

Parameters:

Name	Type	Description	Default
widget	Widget	A widget.	required

Returns:

Type	Description
bool	True if the entire widget is in view, False if it is partially visible or not in view.

can_view_partial

can_view_partial(widget)

Check if a given widget is at least partially within the current view.

Parameters:

Name	Type	Description	Default
widget	Widget	A widget.	required

Returns:

Type	Description
bool	True if the any part of the widget is in view, False if it is completely outside of the screen.

clear_selection

clear_selection()

Clear any selected text.

dismiss

dismiss(result=None)

Dismiss the screen, optionally with a result.

Any callback provided in push_screen will be invoked with the supplied result.

Only the active screen may be dismissed. This method will produce a warning in the logs if called on an inactive screen (but otherwise have no effect).

Warning

Textual will raise a ScreenError if you await the return value from a message handler on the Screen being dismissed. If you want to dismiss the current screen, you can call self.dismiss() without awaiting.

Parameters:

Name	Type	Description	Default
result	ScreenResultType | None	The optional result to be passed to the result callback.	None

find_widget

find_widget(widget)

Get the screen region of a Widget.

Parameters:

Name	Type	Description	Default
widget	Widget	A Widget within the composition.	required

Returns:

Type	Description
MapGeometry	Region relative to screen.

Raises:

Type	Description
NoWidget	If the widget could not be found in this screen.

focus_next

focus_next(selector='*')

Focus the next widget, optionally filtered by a CSS selector.

If no widget is currently focused, this will focus the first focusable widget. If no focusable widget matches the given CSS selector, focus is set to None.

Parameters:

Name	Type	Description	Default
selector	str | type[QueryType]	CSS selector to filter what nodes can be focused.	'*'

Returns:

Type	Description
Widget | None	Newly focused widget, or None for no focus. If the return is not None, then it is guaranteed that the widget returned matches the CSS selectors given in the argument.

focus_previous

focus_previous(selector='*')

Focus the previous widget, optionally filtered by a CSS selector.

If no widget is currently focused, this will focus the first focusable widget. If no focusable widget matches the given CSS selector, focus is set to None.

Parameters:

Name	Type	Description	Default
selector	str | type[QueryType]	CSS selector to filter what nodes can be focused.	'*'

Returns:

Type	Description
Widget | None	Newly focused widget, or None for no focus. If the return is not None, then it is guaranteed that the widget returned matches the CSS selectors given in the argument.

get_focusable_widget_at

get_focusable_widget_at(x, y)

Get the focusable widget under a given coordinate.

If the widget directly under the given coordinate is not focusable, then this method will check if any of the ancestors are focusable. If no ancestors are focusable, then None will be returned.

Parameters:

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

Returns:

Type	Description
Widget | None	A Widget, or None if there is no focusable widget underneath the coordinate.

get_offset

get_offset(widget)

Get the absolute offset of a given Widget.

Parameters:

Name	Type	Description	Default
widget	Widget	A widget	required

Returns:

Type	Description
Offset	The widget's offset relative to the top left of the terminal.

get_selected_text

get_selected_text()

Get text under selection.

Returns:

Type	Description
str | None	Selected text, or None if no text was selected.

get_style_at

get_style_at(x, y)

Get the style under a given coordinate.

Parameters:

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

Returns:

Type	Description
Style	Rich Style object.

get_widget_and_offset_at

get_widget_and_offset_at(x, y)

Get the widget under a given coordinate, and an offset within the original content.

Parameters:

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

Returns:

Type	Description
tuple[Widget | None, Offset | None]	Tuple of Widget and Offset, both of which may be None.

get_widget_at

get_widget_at(x, y)

Get the widget at a given coordinate.

Parameters:

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

Returns:

Type	Description
tuple[Widget, Region]	Widget and screen region.

Raises:

Type	Description
NoWidget	If there is no widget under the screen coordinate.

get_widgets_at

get_widgets_at(x, y)

Get all widgets under a given coordinate.

Parameters:

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

Returns:

Type	Description
Iterable[tuple[Widget, Region]]	Sequence of (WIDGET, REGION) tuples.

maximize

maximize(widget, container=True)

Maximize a widget, so it fills the screen.

Parameters:

Name	Type	Description	Default
widget	Widget	Widget to maximize.	required
container	bool	If one of the widgets ancestors is a maximizeable widget, maximize that instead.	True

Returns:

Type	Description
bool	True if the widget was maximized, otherwise False.

minimize

minimize()

Restore any maximized widget to normal state.

pop_until_active

pop_until_active()

Pop any screens on top of this one, until this screen is active.

Raises:

Type	Description
ScreenError	If this screen is not in the current mode.

refresh_bindings

refresh_bindings()

Call to request a refresh of bindings.

set_focus

set_focus(
    widget, scroll_visible=True, from_app_focus=False
)

Focus (or un-focus) a widget. A focused widget will receive key events first.

Parameters:

Name	Type	Description	Default
widget	Widget | None	Widget to focus, or None to un-focus.	required
scroll_visible	bool	Scroll widget into view.	True
from_app_focus	bool	True if this focus is due to the app itself having regained focus. False if the focus is being set because a widget within the app regained focus.	False

validate_sub_title

validate_sub_title(sub_title)

Ensure the sub-title is a string or None.

validate_title

validate_title(title)

Ensure the title is a string or None.

SystemModalScreen

Bases: ModalScreen[ScreenResultType]

A variant of ModalScreen for internal use.

This version of ModalScreen allows us to build system-level screens; the type being used to indicate that the screen should be isolated from the main application.

Note

This screen is set to not inherit CSS.