Skip to content

Screen

screen

Screen

Bases: Widget

A widget for the root of the app.

focus_chain: list[Widget] property

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

is_current: bool property

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

update_timer: Timer property

Timer used to perform updates.

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(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(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_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_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_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.

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.

set_focus(widget, scroll_visible=True)

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 in to view.

True