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
¶
The result type of a screen.
ModalScreen
class
¶
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
¶
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 |
Screen
class
¶
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
|
AUTO_FOCUS
class-attribute
¶
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
¶
Command providers used by the command palette, associated with the screen.
Should be a set of command.Provider
classes.
CSS
class-attribute
¶
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
¶
File paths to load CSS from.
Note
This CSS applies to the whole app.
SUB_TITLE
class-attribute
¶
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
¶
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.
focus_chain
property
¶
A list of widgets that may receive focus, in focus order.
layers
property
¶
stack_updates
class-attribute
instance-attribute
¶
An integer that updates when the screen is resumed.
sub_title
class-attribute
instance-attribute
¶
Screen sub-title to override the app sub-title.
title
class-attribute
instance-attribute
¶
Screen title to override the app title.
action_dismiss
method
¶
A wrapper around dismiss
that can be called as an action.
Parameters
Name | Type | Description | Default |
---|---|---|---|
result |
ScreenResultType | Type[_NoResult]
|
The optional result to be passed to the result callback. |
_NoResult
|
can_view
method
¶
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
Name | Type | Description | Default |
---|---|---|---|
widget |
Widget
|
A widget that is a descendant of self. |
required |
Returns
Type | Description |
---|---|
bool
|
True if the entire widget is in view, False if it is partially visible or not in view. |
dismiss
method
¶
Dismiss the screen, optionally with a result.
If result
is provided and a callback was set when the screen was pushed, then
the callback will be invoked with result
.
Parameters
Name | Type | Description | Default |
---|---|---|---|
result |
ScreenResultType | Type[_NoResult]
|
The optional result to be passed to the result callback. |
_NoResult
|
Raises
Type | Description |
---|---|
ScreenStackError
|
If trying to dismiss a screen that is not at the top of the stack. |
find_widget
method
¶
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
method
¶
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 |
focus_previous
method
¶
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 |
get_offset
method
¶
get_style_at
method
¶
get_widget_at
method
¶
get_widgets_at
method
¶
set_focus
method
¶
validate_sub_title
method
¶
Ensure the sub-title is a string or None
.