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