Skip to content

Screen

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

ScreenResultCallbackType module-attribute

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

Type of a screen result callback function.

ScreenResultType module-attribute

ScreenResultType = TypeVar('ScreenResultType')

The result type of a screen.

ModalScreen class

def __init__(self, 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 class

def __init__(self, requester, callback, future=None):

Bases: Generic[ScreenResultType]

Holds the details of a callback.

Parameters
Parameter Default Description
requester
MessagePump
required

The object making a request for the callback.

callback
ScreenResultCallbackType[ScreenResultType] | None
required

The callback function.

future
asyncio.Future[ScreenResultType] | None
None

A Future to hold the result.

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 class

def __init__(self, name=None, id=None, classes=None):

Bases: Generic[ScreenResultType], Widget

The base class for screens.

Parameters
Parameter Default Description
name
str | None
None

The name of the screen.

id
str | None
None

The ID of the screen in the DOM.

classes
str | None
None

The CSS classes for the screen.

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.

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 boolean).

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 instance-attribute class-attribute

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

The focused widget or None for no focus.

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.

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.

stack_updates instance-attribute class-attribute

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

An integer that updates when the screen is resumed.

sub_title instance-attribute class-attribute

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

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

title instance-attribute class-attribute

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

Screen title to override the app title.

action_dismiss method

def action_dismiss(self, result=_NoResult):

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

Parameters
Parameter Default Description
result
ScreenResultType | Type[_NoResult]
_NoResult

The optional result to be passed to the result callback.

can_view method

def can_view(self, widget):

Check if a given widget is in the current view (scrollable area).

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

Parameters
Parameter Default Description
widget
Widget
required

A widget that is a descendant of self.

Returns
Type Description
bool

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

dismiss method

def dismiss(self, result=_NoResult):

Dismiss the screen, optionally with a result.

Note

Only the active screen may be dismissed. If you try to dismiss a screen that isn't active, this method will return False.

If result is provided and a callback was set when the screen was pushed, then the callback will be invoked with result.

Parameters
Parameter Default Description
result
ScreenResultType | Type[_NoResult]
_NoResult

The optional result to be passed to the result callback.

Returns
Type Description
bool

True if the Screen was dismissed, or False if the Screen wasn't dismissed due to not being active.

Raises
Type Description
ScreenStackError

If trying to dismiss a screen that is not at the top of the stack.

find_widget method

def find_widget(self, widget):

Get the screen region of a Widget.

Parameters
Parameter Default Description
widget
Widget
required

A Widget within the composition.

Returns
Type Description
MapGeometry

Region relative to screen.

Raises
Type Description
NoWidget

If the widget could not be found in this screen.

focus_next method

def focus_next(self, 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
Parameter Default Description
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 method

def focus_previous(self, 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
Parameter Default Description
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 method

def get_focusable_widget_at(self, 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
Parameter Default Description
x
int
required

X coordinate.

y
int
required

Y coordinate.

Returns
Type Description
Widget | None

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

get_offset method

def get_offset(self, widget):

Get the absolute offset of a given Widget.

Parameters
Parameter Default Description
widget
Widget
required

A widget

Returns
Type Description
Offset

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

get_style_at method

def get_style_at(self, x, y):

Get the style under a given coordinate.

Parameters
Parameter Default Description
x
int
required

X Coordinate.

y
int
required

Y Coordinate.

Returns
Type Description
Style

Rich Style object.

get_widget_at method

def get_widget_at(self, x, y):

Get the widget at a given coordinate.

Parameters
Parameter Default Description
x
int
required

X Coordinate.

y
int
required

Y Coordinate.

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 method

def get_widgets_at(self, x, y):

Get all widgets under a given coordinate.

Parameters
Parameter Default Description
x
int
required

X coordinate.

y
int
required

Y coordinate.

Returns
Type Description
Iterable[tuple[Widget, Region]]

Sequence of (WIDGET, REGION) tuples.

refresh_bindings method

def refresh_bindings(self):

Call to request a refresh of bindings.

set_focus method

def set_focus(self, widget, scroll_visible=True):

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

Parameters
Parameter Default Description
widget
Widget | None
required

Widget to focus, or None to un-focus.

scroll_visible
bool
True

Scroll widget in to view.

validate_sub_title method

def validate_sub_title(self, sub_title):

Ensure the sub-title is a string or None.

validate_title method

def validate_title(self, title):

Ensure the title is a string or None.