hamil_clever_sim.components.sparkline_controllable.Sparkline

class Sparkline(data=None, *, summary_function=None, name=None, id=None, classes=None, disabled=False)

Bases: Widget

Methods

action_page_down	rtype: None
action_page_up	rtype: None
action_scroll_down	rtype: None
action_scroll_end	rtype: None
action_scroll_home	rtype: None
action_scroll_left	rtype: None
action_scroll_right	rtype: None
action_scroll_up	rtype: None
add_class	Add class names to this Node.
animate	Animate an attribute.
begin_capture_print	Capture text from print statements (or writes to stdout / stderr).
blur	Blur (un-focus) the widget.
broker_event	rtype: bool
call_after_refresh	Schedule a callback to run after all messages are processed and the screen has been refreshed.
call_later	Schedule a callback to run after all messages are processed in this object.
call_next	Schedule a callback to run immediately after processing the current message.
can_view	Check if a given widget is in the current view (scrollable area).
capture_mouse	Capture (or release) the mouse.
check_idle	Prompt the message pump to call idle if the queue is empty.
check_message_enabled	Check if a given message is enabled (allowed to be sent).
compose	Called by Textual to create child widgets.
compose_add_child	Add a node to children.
disable_messages	Disable message types from being processed.
dispatch_key	Dispatch a key event to method.
enable_messages	Enable processing of messages types.
end_capture_print	End print capture (set with [capture_print][textual.widget.Widget.capture_print]).
focus	Give focus to this widget.
get_child_by_id	Return the first child (immediate descendent) of this node with the given ID.
get_child_by_type	Get a child of a give type.
get_component_rich_style	Get a Rich style for a component.
get_component_styles	Get a "component" styles object (must be defined in COMPONENT_CLASSES classvar).
get_content_height	Called by Textual to get the height of the content area.
get_content_width	Called by textual to get the width of the content area.
get_pseudo_class_state	Get an object describing whether each pseudo class is present on this object or not.
get_pseudo_classes	Pseudo classes for a widget.
get_style_at	Get the Rich style in a widget at a given relative offset.
get_widget_by_id	Return the first descendant widget with the given ID.
handle_key	rtype: bool
has_class	Check if the Node has all the given class names.
has_pseudo_class	Check for pseudo classes (such as hover, focus etc)
mount	Mount widgets below this widget (making this widget a container).
mount_all	Mount widgets from an iterable.
move_child	Move a child widget within its parent's list of children.
notify	Create a notification.
notify_style_update	rtype: None
on_callback	rtype: None
on_event	Called to process an event.
on_timer	rtype: None
post_message	Post a message to this widget.
post_render	Applies style attributes to the default renderable.
prevent	A context manager to temporarily prevent the given message types from being posted.
query	Get a DOM query matching a selector.
query_one	Get a single Widget matching the given selector or selector type.
refresh	Initiate a refresh of the widget.
release_mouse	Release the mouse.
remove	Remove the Widget from the DOM (effectively deleting it).
remove_children	Remove all children of this Widget from the DOM.
remove_class	Remove class names from this Node.
render	rtype: Union[ConsoleRenderable, RichCast, str]
render_line	Render a line of content.
render_lines	Render the widget in to lines.
render_str	Convert str in to a Text object.
reset_styles	Reset styles back to their initial state.
run_action	Perform a given action, with this widget as the default namespace.
run_worker	Run work in a worker.
scroll_down	Scroll one line down.
scroll_end	Scroll to the end of the container.
scroll_home	Scroll to home position.
scroll_left	Scroll one cell left.
scroll_page_down	Scroll one page down.
scroll_page_left	Scroll one page left.
scroll_page_right	Scroll one page right.
scroll_page_up	Scroll one page up.
scroll_relative	Scroll relative to current position.
scroll_right	Scroll one cell right.
scroll_to	Scroll to a given (absolute) coordinate, optionally animating.
scroll_to_center	Scroll this widget to the center of self.
scroll_to_region	Scrolls a given region in to view, if required.
scroll_to_widget	Scroll scrolling to bring a widget in to view.
scroll_up	Scroll one line up.
scroll_visible	Scroll the container to make this widget visible.
set_class	Add or remove class(es) based on a condition.
set_classes	Replace all classes.
set_interval	Call a function at periodic intervals.
set_loading	Set or reset the loading state of this widget.
set_styles	Set custom styles on this object.
set_timer	Make a function call after a delay.
stop_animation	Stop an animation on an attribute.
toggle_class	Toggle class names on this Node.
validate_scroll_target_x	rtype: float
validate_scroll_target_y	rtype: float
validate_scroll_x	rtype: float
validate_scroll_y	rtype: float
walk_children	Walk the subtree rooted at this node, and return every descendant encountered in a list.
watch	Watches for modifications to reactive attributes on another object.
watch_disabled	Update the styles of the widget and its children when disabled is toggled.
watch_has_focus	Update from CSS if has focus state changes.
watch_hover_style	rtype: None
watch_marked_index
watch_mouse_over	Update from CSS if mouse over state changes.
watch_scroll_x	rtype: None
watch_scroll_y	rtype: None

Attributes

BINDINGS
BORDER_SUBTITLE	Initial value for border_subtitle attribute.
BORDER_TITLE	Initial value for border_title attribute.
COMPONENT_CLASSES
DEFAULT_CLASSES
DEFAULT_CSS
ExpectType
SCOPED_CSS	Should default css be limited to the widget type?
WalkType
allow_horizontal_scroll	Check if horizontal scroll is permitted.
allow_vertical_scroll	Check if vertical scroll is permitted.
ancestors	A list of ancestor nodes found by tracing a path all the way back to App.
ancestors_with_self	A list of ancestor nodes found by tracing a path all the way back to App.
app	Get the current app.
auto_refresh	Number of seconds between automatic refresh, or None for no automatic refresh.
background_colors	The background color and the color of the parent's background.
border_subtitle	A title to show in the bottom border (if there is one).
border_title	A title to show in the top border (if there is one).
can_focus	Widget may receive focus.
can_focus_children	Widget's children may receive focus.
children	A view on to the children.
colors	The widget's background and foreground colors, and the parent's background and foreground colors.
container_size	The size of the container (parent widget).
container_viewport	The viewport region (parent window).
content_offset	An offset from the Widget origin where the content begins.
content_region	Gets an absolute region containing the content (minus padding and border).
content_size	The size of the content area.
css_identifier	A CSS selector that identifies this DOM node.
css_identifier_styled	A syntax highlighted CSS identifier.
css_path_nodes	A list of nodes from the App to this node, forming a "path".
css_tree	A Rich tree to display the DOM, annotated with the node's CSS.
data	Create a reactive attribute.
display	Should the DOM node be displayed?
displayed_children	The child nodes which will be displayed.
dock_gutter	Space allocated to docks in the parent.
focusable	Can this widget currently be focused?
gutter	Spacing for padding / border / scrollbars.
has_parent	Does this object have a parent?
horizontal_scrollbar	The horizontal scrollbar.
id	The ID of this node, or None if the node has no ID.
is_attached	Is the node attached to the app via the DOM?
is_container	Is this widget a container (contains other widgets)?
is_horizontal_scroll_end	Is the horizontal scroll position at the maximum?
is_horizontal_scrollbar_grabbed	Is the user dragging the vertical scrollbar?
is_modal	Is the node a modal?
is_parent_active	Is the parent active?
is_running	Is the message pump running (potentially processing messages)?
is_scrollable	Can this widget be scrolled?
is_vertical_scroll_end	Is the vertical scroll position at the maximum?
is_vertical_scrollbar_grabbed	Is the user dragging the vertical scrollbar?
layer	Get the name of this widgets layer.
layers	Layers of from parent.
link_hover_style	Style of links underneath the mouse cursor.
link_style	Style of links.
log	Get a logger for this object.
max_scroll_x	The maximum value of scroll_x.
max_scroll_y	The maximum value of scroll_y.
name	The name of the node.
offset	Widget offset from origin.
opacity	Total opacity of widget.
outer_size	The size of the widget (including padding and border).
parent	The parent node.
pseudo_classes	A (frozen) set of all pseudo classes.
region	The region occupied by this widget, relative to the Screen.
rich_style	Get a Rich Style object for this DOMNode.
screen	The screen containing this node.
scroll_offset	Get the current scroll offset.
scrollable_content_region	Gets an absolute region containing the scrollable content (minus padding, border, and scrollbars).
scrollbar_corner	The scrollbar corner.
scrollbar_gutter	Spacing required to fit scrollbar(s).
scrollbar_size_horizontal	Get the height used by the horizontal scrollbar.
scrollbar_size_vertical	Get the width used by the vertical scrollbar.
scrollbars_enabled	A tuple of booleans that indicate if scrollbars are enabled.
scrollbars_space	The number of cells occupied by scrollbars for width and height
siblings	Get the widget's siblings (self is removed from the return list).
size	The size of the content area.
summary_function	Create a reactive attribute.
task
text_style	Get the text style object.
tooltip	Tooltip for the widget, or None for no tooltip.
tree	A Rich tree to display the DOM.
vertical_scrollbar	The vertical scrollbar (create if necessary).
virtual_region	The widget region relative to it's container (which may not be visible, depending on scroll offset).
virtual_region_with_margin	The widget region relative to its container (including margin), which may not be visible, depending on the scroll offset.
visible	Is this widget visible in the DOM?
visible_siblings	A list of siblings which will be shown.
window_region	The region within the scrollable area that is currently visible.
workers	The app's worker manager.
expand	Rich renderable may expand beyond optimal size.
shrink	Rich renderable may shrink below optimal size.
auto_links	Widget will highlight links automatically.
disabled	Is the widget disabled? Disabled widgets can not be interacted with, and are typically styled to look dimmer.
hover_style	The current hover style (style under the mouse cursor).
highlight_link_id	The currently highlighted link id.
loading	If set to True this widget will temporarily be replaced with a loading indicator.
virtual_size	The virtual (scrollable) [size][textual.geometry.Size] of the widget.
has_focus	Does this widget have focus? Read only.
mouse_over	Is the mouse over this widget? Read only.
scroll_x	The scroll position on the X axis.
scroll_y	The scroll position on the Y axis.
show_vertical_scrollbar	Show a horizontal scrollbar?
show_horizontal_scrollbar	Show a horizontal scrollbar?
classes	CSS class names for this node.

add_class(*class_names)

Add class names to this Node.

Return type:

Self

Args:

*class_names: CSS class names to add.

Returns:

Self.

property allow_horizontal_scroll: bool

Check if horizontal scroll is permitted.

May be overridden if you want different logic regarding allowing scrolling.

property allow_vertical_scroll: bool

Check if vertical scroll is permitted.

May be overridden if you want different logic regarding allowing scrolling.

property ancestors: list[DOMNode]

A list of ancestor nodes found by tracing a path all the way back to App.

Returns:

A list of nodes.

property ancestors_with_self: list[DOMNode]

A list of ancestor nodes found by tracing a path all the way back to App.

Note:

This is inclusive of self.

Returns:

A list of nodes.

animate(attribute, value, *, final_value=Ellipsis, duration=None, speed=None, delay=0.0, easing='in_out_cubic', on_complete=None)

Animate an attribute.

Return type:

None

Args:

attribute: Name of the attribute to animate. value: The value to animate to. final_value: The final value of the animation. Defaults to value if not set. duration: The duration of the animate. speed: The speed of the animation. delay: A delay (in seconds) before the animation starts. easing: An easing method. on_complete: A callable to invoke when the animation is finished.

property app: App[object]

Get the current app.

Returns:

The current app.

Raises:

NoActiveAppError: if no active app could be found for the current asyncio context

auto_links: Reactive[bool]

Widget will highlight links automatically.

property auto_refresh: float | None

Number of seconds between automatic refresh, or None for no automatic refresh.

property background_colors: tuple[Color, Color]

The background color and the color of the parent’s background.

Returns:

(<background color>, <color>)

begin_capture_print(stdout=True, stderr=True)

Capture text from print statements (or writes to stdout / stderr).

If printing is captured, the widget will be sent an [events.Print][textual.events.Print] message.

Call [end_capture_print][textual.widget.Widget.end_capture_print] to disable print capture.

Return type:

None

Args:

stdout: Capture stdout. stderr: Capture stderr.

blur()

Blur (un-focus) the widget.

Focus will be moved to the next available widget in the focus chain..

Return type:

Self

Returns:

The Widget instance.

call_after_refresh(callback, *args, **kwargs)

Schedule a callback to run after all messages are processed and the screen has been refreshed. Positional and keyword arguments are passed to the callable.

Return type:

bool

Args:

callback: A callable.

Returns:

True if the callback was scheduled, or False if the callback could not be

scheduled (may occur if the message pump was closed or closing).

call_later(callback, *args, **kwargs)

Schedule a callback to run after all messages are processed in this object. Positional and keywords arguments are passed to the callable.

Return type:

bool

Args:

callback: Callable to call next. *args: Positional arguments to pass to the callable. **kwargs: Keyword arguments to pass to the callable.

Returns:

True if the callback was scheduled, or False if the callback could not be

scheduled (may occur if the message pump was closed or closing).

call_next(callback, *args, **kwargs)

Schedule a callback to run immediately after processing the current message.

Return type:

None

Args:

callback: Callable to run after current event. *args: Positional arguments to pass to the callable. **kwargs: Keyword arguments to pass to the callable.

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

Return type:

bool

Args:

widget: A widget that is a descendant of self.

Returns:

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

capture_mouse(capture=True)

Capture (or release) the mouse.

When captured, mouse events will go to this widget even when the pointer is not directly over the widget.

Return type:

None

Args:

capture: True to capture or False to release.

check_idle()

Prompt the message pump to call idle if the queue is empty.

Return type:

None

check_message_enabled(message)

Check if a given message is enabled (allowed to be sent).

Return type:

bool

Args:

message: A message object

Returns:

True if the message will be sent, or False if it is disabled.

property children: Sequence[Widget]

A view on to the children.

Returns:

The node’s children.

classes

CSS class names for this node.

property colors: tuple[Color, Color, Color, Color]

The widget’s background and foreground colors, and the parent’s background and foreground colors.

Returns:

(<parent background>, <parent color>, <background>, <color>)

compose()

Called by Textual to create child widgets.

Extend this to build a UI.

Return type:

Iterable[Widget]

Example:

```python def compose(self) -> ComposeResult:

yield Header() yield Container(

Tree(), Viewer()

) yield Footer()

```

compose_add_child(widget)

Add a node to children.

This is used by the compose process when it adds children. There is no need to use it directly, but you may want to override it in a subclass if you want children to be attached to a different node.

Return type:

None

Args:

widget: A Widget to add.

property container_size: Size

The size of the container (parent widget).

Returns:

Container size.

property container_viewport: Region

The viewport region (parent window).

Returns:

The region that contains this widget.

property content_offset: Offset

An offset from the Widget origin where the content begins.

Returns:

Offset from widget’s origin.

property content_region: Region

Gets an absolute region containing the content (minus padding and border).

Returns:

Screen region that contains a widget’s content.

property content_size: Size

The size of the content area.

Returns:

Content area size.

property css_identifier: str

A CSS selector that identifies this DOM node.

property css_identifier_styled: Text

A syntax highlighted CSS identifier.

Returns:

A Rich Text object.

property css_path_nodes: list[DOMNode]

A list of nodes from the App to this node, forming a “path”.

Returns:

A list of nodes, where the first item is the App, and the last is this node.

property css_tree: Tree

A Rich tree to display the DOM, annotated with the node’s CSS.

Log this to visualize your app in the textual console.

Example:

`python self.log(self.css_tree) `

Returns:

A Tree renderable.

disable_messages(*messages)

Disable message types from being processed.

Return type:

None

disabled: Reactive[bool]

Is the widget disabled? Disabled widgets can not be interacted with, and are typically styled to look dimmer.

async dispatch_key(event)

Dispatch a key event to method.

This method will call the method named ‘key_<event.key>’ if it exists. Some keys have aliases. The first alias found will be invoked if it exists. If multiple handlers exist that match the key, an exception is raised.

Return type:

bool

Args:

event: A key event.

Returns:

True if key was handled, otherwise False.

Raises:

DuplicateKeyHandlers: When there’s more than 1 handler that could handle this key.

property display: bool

Should the DOM node be displayed?

May be set to a boolean to show or hide the node, or to any valid value for the display rule.

Example:

`python my_widget.display = False  # Hide my_widget `

property displayed_children: list[Widget]

The child nodes which will be displayed.

Returns:

A list of nodes.

property dock_gutter: Spacing

Space allocated to docks in the parent.

Returns:

Space to be subtracted from scrollable area.

enable_messages(*messages)

Enable processing of messages types.

Return type:

None

end_capture_print()

End print capture (set with [capture_print][textual.widget.Widget.capture_print]).

Return type:

None

expand: Reactive[bool]

Rich renderable may expand beyond optimal size.

focus(scroll_visible=True)

Give focus to this widget.

Return type:

Self

Args:

scroll_visible: Scroll parent to make this widget visible.

Returns:

The Widget instance.

property focusable: bool

Can this widget currently be focused?

get_child_by_id(id, expect_type=None)

Return the first child (immediate descendent) of this node with the given ID.

Return type:

ExpectType | Widget

Args:

id: The ID of the child. expect_type: Require the object be of the supplied type, or None for any type.

Returns:

The first child of this node with the ID.

Raises:

NoMatches: if no children could be found for this ID WrongType: if the wrong type was found.

get_child_by_type(expect_type)

Get a child of a give type.

Return type:

ExpectType

Args:

expect_type: The type of the expected child.

Raises:

NoMatches: If no valid child is found.

Returns:

A widget.

get_component_rich_style(name, *, partial=False)

Get a Rich style for a component.

Return type:

Style

Args:

name: Name of component. partial: Return a partial style (not combined with parent).

Returns:

A Rich style object.

get_component_styles(name)

Get a “component” styles object (must be defined in COMPONENT_CLASSES classvar).

Return type:

RenderStyles

Args:

name: Name of the component.

Raises:

KeyError: If the component class doesn’t exist.

Returns:

A Styles object.

get_content_height(container, viewport, width)

Called by Textual to get the height of the content area. May be overridden in a subclass.

Return type:

int

Args:

container: Size of the container (immediate parent) widget. viewport: Size of the viewport. width: Width of renderable.

Returns:

The height of the content.

get_content_width(container, viewport)

Called by textual to get the width of the content area. May be overridden in a subclass.

Return type:

int

Args:

container: Size of the container (immediate parent) widget. viewport: Size of the viewport.

Returns:

The optimal width of the content.

get_pseudo_class_state()

Get an object describing whether each pseudo class is present on this object or not.

Return type:

PseudoClasses

Returns:

A PseudoClasses object describing the pseudo classes that are present.

get_pseudo_classes()

Pseudo classes for a widget.

Return type:

Iterable[str]

Returns:

Names of the pseudo classes.

get_style_at(x, y)

Get the Rich style in a widget at a given relative offset.

Return type:

Style

Args:

x: X coordinate relative to the widget. y: Y coordinate relative to the widget.

Returns:

A rich Style object.

get_widget_by_id(id, expect_type=None)

Return the first descendant widget with the given ID.

Performs a depth-first search rooted at this widget.

Return type:

ExpectType | Widget

Args:

id: The ID to search for in the subtree. expect_type: Require the object be of the supplied type, or None for any type.

Returns:

The first descendant encountered with this ID.

Raises:

NoMatches: if no children could be found for this ID. WrongType: if the wrong type was found.

property gutter: Spacing

Spacing for padding / border / scrollbars.

Returns:

Additional spacing around content area.

has_class(*class_names)

Check if the Node has all the given class names.

Return type:

bool

Args:

*class_names: CSS class names to check.

Returns:

True if the node has all the given class names, otherwise False.

has_focus: Reactive[bool]

Does this widget have focus? Read only.

property has_parent: bool

Does this object have a parent?

has_pseudo_class(*class_names)

Check for pseudo classes (such as hover, focus etc)

Return type:

bool

Args:

*class_names: The pseudo classes to check for.

Returns:

True if the DOM node has those pseudo classes, False if not.

highlight_link_id: Reactive[str]

The currently highlighted link id. Read only.

property horizontal_scrollbar: ScrollBar

The horizontal scrollbar.

Note:

This will create a scrollbar if one doesn’t exist.

Returns:

ScrollBar Widget.

hover_style: Reactive[Style]

The current hover style (style under the mouse cursor). Read only.

property id: str | None

The ID of this node, or None if the node has no ID.

property is_attached: bool

Is the node attached to the app via the DOM?

property is_container: bool

Is this widget a container (contains other widgets)?

property is_horizontal_scroll_end: bool

Is the horizontal scroll position at the maximum?

property is_horizontal_scrollbar_grabbed: bool

Is the user dragging the vertical scrollbar?

property is_modal: bool

Is the node a modal?

property is_parent_active: bool

Is the parent active?

property is_running: bool

Is the message pump running (potentially processing messages)?

property is_scrollable: bool

Can this widget be scrolled?

property is_vertical_scroll_end: bool

Is the vertical scroll position at the maximum?

property is_vertical_scrollbar_grabbed: bool

Is the user dragging the vertical scrollbar?

property layer: str

Get the name of this widgets layer.

Returns:

Name of layer.

property layers: tuple[str, ...]

Layers of from parent.

Returns:

Tuple of layer names.

property link_hover_style: Style

Style of links underneath the mouse cursor.

Returns:

Rich Style.

property link_style: Style

Style of links.

Returns:

Rich style.

loading: Reactive[bool]

If set to True this widget will temporarily be replaced with a loading indicator.

property log: Logger

Get a logger for this object.

Returns:

A logger.

property max_scroll_x: int

The maximum value of scroll_x.

property max_scroll_y: int

The maximum value of scroll_y.

mount(*widgets, before=None, after=None)

Mount widgets below this widget (making this widget a container).

Return type:

AwaitMount

Args:

*widgets: The widget(s) to mount. before: Optional location to mount before. An int is the index

of the child to mount before, a str is a query_one query to find the widget to mount before.

after: Optional location to mount after. An int is the index

of the child to mount after, a str is a query_one query to find the widget to mount after.

Returns:

An awaitable object that waits for widgets to be mounted.

Raises:

MountError: If there is a problem with the mount request.

Note:

Only one of before or after can be provided. If both are provided a MountError will be raised.

mount_all(widgets, *, before=None, after=None)

Mount widgets from an iterable.

Return type:

AwaitMount

Args:

widgets: An iterable of widgets. before: Optional location to mount before. An int is the index

of the child to mount before, a str is a query_one query to find the widget to mount before.

after: Optional location to mount after. An int is the index

of the child to mount after, a str is a query_one query to find the widget to mount after.

Returns:

An awaitable object that waits for widgets to be mounted.

Raises:

MountError: If there is a problem with the mount request.

Note:

Only one of before or after can be provided. If both are provided a MountError will be raised.

mouse_over: Reactive[bool]

Is the mouse over this widget? Read only.

move_child(child, before=None, after=None)

Move a child widget within its parent’s list of children.

Return type:

None

Args:

child: The child widget to move. before: Child widget or location index to move before. after: Child widget or location index to move after.

Raises:

WidgetError: If there is a problem with the child or target.

Note:

Only one of before or after can be provided. If neither or both are provided a WidgetError will be raised.

property name: str | None

The name of the node.

notify(message, *, title='', severity='information', timeout=3)

Create a notification.

!!! tip :rtype: None

This method is thread-safe.

Args:

message: The message for the notification. title: The title for the notification. severity: The severity of the notification. timeout: The timeout for the notification.

See [App.notify][textual.app.App.notify] for the full documentation for this method.

property offset: Offset

Widget offset from origin.

Returns:

Relative offset.

async on_event(event)

Called to process an event.

Return type:

None

Args:

event: An Event object.

property opacity: float

Total opacity of widget.

property outer_size: Size

The size of the widget (including padding and border).

Returns:

Outer size.

property parent: DOMNode | None

The parent node.

All nodes have parent once added to the DOM, with the exception of the App which is the root node.

post_message(message)

Post a message to this widget.

Return type:

bool

Args:

message: Message to post.

Returns:

True if the message was posted, False if this widget was closed / closing.

post_render(renderable)

Applies style attributes to the default renderable.

Return type:

ConsoleRenderable

Returns:

A new renderable.

prevent(*message_types)

A context manager to temporarily prevent the given message types from being posted.

Return type:

Generator[None, None, None]

Example:

```python input = self.query_one(Input) with self.prevent(Input.Changed):

input.value = “foo”

```

property pseudo_classes: frozenset[str]

A (frozen) set of all pseudo classes.

query(selector=None)

Get a DOM query matching a selector.

Return type:

Union[DOMQuery[Widget], DOMQuery[TypeVar(QueryType, bound= Widget)]]

Args:

selector: A CSS selector or None for all nodes.

Returns:

A query object.

query_one(selector, expect_type=None)

Get a single Widget matching the given selector or selector type.

Return type:

Union[TypeVar(QueryType, bound= Widget), Widget]

Args:

selector: A selector. expect_type: Require the object be of the supplied type, or None for any type.

Raises:

WrongType: If the wrong type was found. NoMatches: If no node matches the query. TooManyMatches: If there is more than one matching node in the query.

Returns:

A widget matching the selector.

refresh(*regions, repaint=True, layout=False)

Initiate a refresh of the widget.

This method sets an internal flag to perform a refresh, which will be done on the next idle event. Only one refresh will be done even if this method is called multiple times.

By default this method will cause the content of the widget to refresh, but not change its size. You can also set layout=True to perform a layout.

!!! warning :rtype: Self

It is rarely necessary to call this method explicitly. Updating styles or reactive attributes will do this automatically.

Args:

*regions: Additional screen regions to mark as dirty. repaint: Repaint the widget (will call render() again). layout: Also layout widgets in the view.

Returns:

The Widget instance.

property region: Region

The region occupied by this widget, relative to the Screen.

Raises:

NoScreen: If there is no screen. errors.NoWidget: If the widget is not on the screen.

Returns:

Region within screen occupied by widget.

release_mouse()

Release the mouse.

Mouse events will only be sent when the mouse is over the widget.

Return type:

None

remove()

Remove the Widget from the DOM (effectively deleting it).

Return type:

AwaitRemove

Returns:

An awaitable object that waits for the widget to be removed.

remove_children()

Remove all children of this Widget from the DOM.

Return type:

AwaitRemove

Returns:

An awaitable object that waits for the children to be removed.

remove_class(*class_names)

Remove class names from this Node.

Return type:

Self

Args:

*class_names: CSS class names to remove.

Returns:

Self.

render_line(y)

Render a line of content.

Return type:

Strip

Args:

y: Y Coordinate of line.

Returns:

A rendered line.

render_lines(crop)

Render the widget in to lines.

Return type:

list[Strip]

Args:

crop: Region within visible area to render.

Returns:

A list of list of segments.

render_str(text_content)

Convert str in to a Text object.

If you pass in an existing Text object it will be returned unaltered.

Return type:

Text

Args:

text_content: Text or str.

Returns:

A text object.

reset_styles()

Reset styles back to their initial state.

Return type:

None

property rich_style: Style

Get a Rich Style object for this DOMNode.

Returns:

A Rich style.

async run_action(action)

Perform a given action, with this widget as the default namespace.

Return type:

None

Args:

action: Action encoded as a string.

run_worker(work, name='', group='default', description='', exit_on_error=True, start=True, exclusive=False, thread=False)

Run work in a worker.

A worker runs a function, coroutine, or awaitable, in the background as an async task or as a thread.

Return type:

Worker[TypeVar(ResultType)]

Args:

work: A function, async function, or an awaitable object to run in a worker. name: A short string to identify the worker (in logs and debugging). group: A short string to identify a group of workers. description: A longer string to store longer information on the worker. exit_on_error: Exit the app if the worker raises an error. Set to False to suppress exceptions. start: Start the worker immediately. exclusive: Cancel all workers in the same group. thread: Mark the worker as a thread worker.

Returns:

New Worker instance.

property screen: Screen[object]

The screen containing this node.

Returns:

A screen object.

Raises:

NoScreen: If this node isn’t mounted (and has no screen).

scroll_down(*, animate=True, speed=None, duration=None, easing=None, force=False, on_complete=None)

Scroll one line down.

Return type:

None

Args:

animate: Animate scroll. speed: Speed of scroll if animate is True; or None to use duration. duration: Duration of animation, if animate is True and speed is None. easing: An easing method for the scrolling animation. force: Force scrolling even when prohibited by overflow styling. on_complete: A callable to invoke when the animation is finished.

scroll_end(*, animate=True, speed=None, duration=None, easing=None, force=False, on_complete=None)

Scroll to the end of the container.

Return type:

None

Args:

animate: Animate scroll. speed: Speed of scroll if animate is True; or None to use duration. duration: Duration of animation, if animate is True and speed is None. easing: An easing method for the scrolling animation. force: Force scrolling even when prohibited by overflow styling. on_complete: A callable to invoke when the animation is finished.

scroll_home(*, animate=True, speed=None, duration=None, easing=None, force=False, on_complete=None)

Scroll to home position.

Return type:

None

Args:

animate: Animate scroll. speed: Speed of scroll if animate is True; or None to use duration. duration: Duration of animation, if animate is True and speed is None. easing: An easing method for the scrolling animation. force: Force scrolling even when prohibited by overflow styling. on_complete: A callable to invoke when the animation is finished.

scroll_left(*, animate=True, speed=None, duration=None, easing=None, force=False, on_complete=None)

Scroll one cell left.

Return type:

None

Args:

animate: Animate scroll. speed: Speed of scroll if animate is True; or None to use duration. duration: Duration of animation, if animate is True and speed is None. easing: An easing method for the scrolling animation. force: Force scrolling even when prohibited by overflow styling. on_complete: A callable to invoke when the animation is finished.

property scroll_offset: Offset

Get the current scroll offset.

Returns:

Offset a container has been scrolled by.

scroll_page_down(*, animate=True, speed=None, duration=None, easing=None, force=False, on_complete=None)

Scroll one page down.

Return type:

None

Args:

animate: Animate scroll. speed: Speed of scroll if animate is True; or None to use duration. duration: Duration of animation, if animate is True and speed is None. easing: An easing method for the scrolling animation. force: Force scrolling even when prohibited by overflow styling. on_complete: A callable to invoke when the animation is finished.

scroll_page_left(*, animate=True, speed=None, duration=None, easing=None, force=False, on_complete=None)

Scroll one page left.

Return type:

None

Args:

animate: Animate scroll. speed: Speed of scroll if animate is True; or None to use duration. duration: Duration of animation, if animate is True and speed is None. easing: An easing method for the scrolling animation. force: Force scrolling even when prohibited by overflow styling. on_complete: A callable to invoke when the animation is finished.

scroll_page_right(*, animate=True, speed=None, duration=None, easing=None, force=False, on_complete=None)

Scroll one page right.

Return type:

None

Args:

animate: Animate scroll. speed: Speed of scroll if animate is True; or None to use duration. duration: Duration of animation, if animate is True and speed is None. easing: An easing method for the scrolling animation. force: Force scrolling even when prohibited by overflow styling. on_complete: A callable to invoke when the animation is finished.

scroll_page_up(*, animate=True, speed=None, duration=None, easing=None, force=False, on_complete=None)

Scroll one page up.

Return type:

None

Args:

animate: Animate scroll. speed: Speed of scroll if animate is True; or None to use duration. duration: Duration of animation, if animate is True and speed is None. easing: An easing method for the scrolling animation. force: Force scrolling even when prohibited by overflow styling. on_complete: A callable to invoke when the animation is finished.

scroll_relative(x=None, y=None, *, animate=True, speed=None, duration=None, easing=None, force=False, on_complete=None)

Scroll relative to current position.

Return type:

None

Args:

x: X distance (columns) to scroll, or None for no change. y: Y distance (rows) to scroll, or None for no change. animate: Animate to new scroll position. speed: Speed of scroll if animate is True. Or None to use duration. duration: Duration of animation, if animate is True and speed is None. easing: An easing method for the scrolling animation. force: Force scrolling even when prohibited by overflow styling. on_complete: A callable to invoke when the animation is finished.

scroll_right(*, animate=True, speed=None, duration=None, easing=None, force=False, on_complete=None)

Scroll one cell right.

Return type:

None

Args:

animate: Animate scroll. speed: Speed of scroll if animate is True; or None to use duration. duration: Duration of animation, if animate is True and speed is None. easing: An easing method for the scrolling animation. force: Force scrolling even when prohibited by overflow styling. on_complete: A callable to invoke when the animation is finished.

scroll_to(x=None, y=None, *, animate=True, speed=None, duration=None, easing=None, force=False, on_complete=None)

Scroll to a given (absolute) coordinate, optionally animating.

Return type:

None

Args:

x: X coordinate (column) to scroll to, or None for no change. y: Y coordinate (row) to scroll to, or None for no change. animate: Animate to new scroll position. speed: Speed of scroll if animate is True; or None to use duration. duration: Duration of animation, if animate is True and speed is None. easing: An easing method for the scrolling animation. force: Force scrolling even when prohibited by overflow styling. on_complete: A callable to invoke when the animation is finished.

Note:

The call to scroll is made after the next refresh.

scroll_to_center(widget, animate=True, *, speed=None, duration=None, easing=None, force=False, origin_visible=True, on_complete=None)

Scroll this widget to the center of self.

The center of the widget will be scrolled to the center of the container.

Return type:

None

Args:

widget: The widget to scroll to the center of self. animate: Whether to animate the scroll. speed: Speed of scroll if animate is True; or None to use duration. duration: Duration of animation, if animate is True and speed is None. easing: An easing method for the scrolling animation. force: Force scrolling even when prohibited by overflow styling. origin_visible: Ensure that the top left corner of the widget remains visible after the scroll. on_complete: A callable to invoke when the animation is finished.

scroll_to_region(region, *, spacing=None, animate=True, speed=None, duration=None, easing=None, center=False, top=False, origin_visible=True, force=False, on_complete=None)

Scrolls a given region in to view, if required.

This method will scroll the least distance required to move region fully within the scrollable area.

Return type:

Offset

Args:

region: A region that should be visible. spacing: Optional spacing around the region. animate: True to animate, or False to jump. speed: Speed of scroll if animate is True; or None to use duration. duration: Duration of animation, if animate is True and speed is None. easing: An easing method for the scrolling animation. top: Scroll region to top of container. origin_visible: Ensure that the top left of the widget is within the window. force: Force scrolling even when prohibited by overflow styling. on_complete: A callable to invoke when the animation is finished.

Returns:

The distance that was scrolled.

scroll_to_widget(widget, *, animate=True, speed=None, duration=None, easing=None, center=False, top=False, origin_visible=True, force=False, on_complete=None)

Scroll scrolling to bring a widget in to view.

Return type:

bool

Args:

widget: A descendant widget. animate: True to animate, or False to jump. speed: Speed of scroll if animate is True; or None to use duration. duration: Duration of animation, if animate is True and speed is None. easing: An easing method for the scrolling animation. top: Scroll widget to top of container. origin_visible: Ensure that the top left of the widget is within the window. force: Force scrolling even when prohibited by overflow styling. on_complete: A callable to invoke when the animation is finished.

Returns:

True if any scrolling has occurred in any descendant, otherwise False.

scroll_up(*, animate=True, speed=None, duration=None, easing=None, force=False, on_complete=None)

Scroll one line up.

Return type:

None

Args:

animate: Animate scroll. speed: Speed of scroll if animate is True; or None to use duration. duration: Duration of animation, if animate is True and speed is None. easing: An easing method for the scrolling animation. force: Force scrolling even when prohibited by overflow styling. on_complete: A callable to invoke when the animation is finished.

scroll_visible(animate=True, *, speed=None, duration=None, top=False, easing=None, force=False, on_complete=None)

Scroll the container to make this widget visible.

Return type:

None

Args:

animate: Animate scroll. speed: Speed of scroll if animate is True; or None to use duration. duration: Duration of animation, if animate is True and speed is None. top: Scroll to top of container. easing: An easing method for the scrolling animation. force: Force scrolling even when prohibited by overflow styling. on_complete: A callable to invoke when the animation is finished.

scroll_x: Reactive[float]

The scroll position on the X axis.

scroll_y: Reactive[float]

The scroll position on the Y axis.

property scrollable_content_region: Region

Gets an absolute region containing the scrollable content (minus padding, border, and scrollbars).

Returns:

Screen region that contains a widget’s content.

property scrollbar_corner: ScrollBarCorner

The scrollbar corner.

Note:

This will create a scrollbar corner if one doesn’t exist.

Returns:

ScrollBarCorner Widget.

property scrollbar_gutter: Spacing

Spacing required to fit scrollbar(s).

Returns:

Scrollbar gutter spacing.

property scrollbar_size_horizontal: int

Get the height used by the horizontal scrollbar.

Returns:

Number of rows in the horizontal scrollbar.

property scrollbar_size_vertical: int

Get the width used by the vertical scrollbar.

Returns:

Number of columns in the vertical scrollbar.

property scrollbars_enabled: tuple[bool, bool]

A tuple of booleans that indicate if scrollbars are enabled.

Returns:

A tuple of (<vertical scrollbar enabled>, <horizontal scrollbar enabled>)

property scrollbars_space: tuple[int, int]

The number of cells occupied by scrollbars for width and height

set_class(add, *class_names)

Add or remove class(es) based on a condition.

Return type:

Self

Args:

add: Add the classes if True, otherwise remove them.

Returns:

Self.

set_classes(classes)

Replace all classes.

Return type:

Self

Args:

classes: A string containing space separated classes, or an

iterable of class names.

Returns:

Self.

set_interval(interval, callback=None, *, name=None, repeat=0, pause=False)

Call a function at periodic intervals.

Return type:

Timer

Args:

interval: Time between calls. callback: Function to call. name: Name of the timer object. repeat: Number of times to repeat the call or 0 for continuous. pause: Start the timer paused.

Returns:

A timer object.

set_loading(loading)

Set or reset the loading state of this widget.

A widget in a loading state will display a LoadingIndicator that obscures the widget.

Return type:

Awaitable

Args:

loading: True to put the widget into a loading state, or False to reset the loading state.

Returns:

An optional awaitable.

set_styles(css=None, **update_styles)

Set custom styles on this object.

Return type:

Self

Args:

css: Styles in CSS format. **update_styles: Keyword arguments map style names on to style.

Returns:

Self.

set_timer(delay, callback=None, *, name=None, pause=False)

Make a function call after a delay.

Return type:

Timer

Args:

delay: Time to wait before invoking callback. callback: Callback to call after time has expired. name: Name of the timer (for debug). pause: Start timer paused.

Returns:

A timer object.

show_horizontal_scrollbar: Reactive[bool]

Show a horizontal scrollbar?

show_vertical_scrollbar: Reactive[bool]

Show a horizontal scrollbar?

shrink: Reactive[bool]

Rich renderable may shrink below optimal size.

property siblings: list[Widget]

Get the widget’s siblings (self is removed from the return list).

Returns:

A list of siblings.

property size: Size

The size of the content area.

Returns:

Content area size.

async stop_animation(attribute, complete=True)

Stop an animation on an attribute.

Return type:

None

Args:

attribute: Name of the attribute whose animation should be stopped. complete: Should the animation be set to its final value?

Note:

If there is no animation scheduled or running, this is a no-op.

property text_style: Style

Get the text style object.

A widget’s style is influenced by its parent. for instance if a parent is bold, then the child will also be bold.

Returns:

A Rich Style.

toggle_class(*class_names)

Toggle class names on this Node.

Return type:

Self

Args:

*class_names: CSS class names to toggle.

Returns:

Self.

property tooltip: ConsoleRenderable | RichCast | str | None

Tooltip for the widget, or None for no tooltip.

property tree: Tree

A Rich tree to display the DOM.

Log this to visualize your app in the textual console.

Example:

`python self.log(self.tree) `

Returns:

A Tree renderable.

property vertical_scrollbar: ScrollBar

The vertical scrollbar (create if necessary).

Note:

This will create a scrollbar if one doesn’t exist.

Returns:

ScrollBar Widget.

property virtual_region: Region

The widget region relative to it’s container (which may not be visible, depending on scroll offset).

Returns:

The virtual region.

property virtual_region_with_margin: Region

The widget region relative to its container (including margin), which may not be visible, depending on the scroll offset.

Returns:

The virtual region of the Widget, inclusive of its margin.

virtual_size: Reactive[Size]

The virtual (scrollable) [size][textual.geometry.Size] of the widget.

property visible: bool

Is this widget visible in the DOM?

If a widget hasn’t had its visibility set explicitly, then it inherits it from its DOM ancestors.

This may be set explicitly to override inherited values. The valid values include the valid values for the visibility rule and the booleans True or False, to set the widget to be visible or invisible, respectively.

When a node is invisible, Textual will reserve space for it, but won’t display anything.

property visible_siblings: list[Widget]

A list of siblings which will be shown.

Returns:

List of siblings.

walk_children(filter_type=None, *, with_self=False, method='depth', reverse=False)

Walk the subtree rooted at this node, and return every descendant encountered in a list.

Return type:

list[DOMNode] | list[WalkType]

Args:

filter_type: Filter only this type, or None for no filter. with_self: Also yield self in addition to descendants. method: One of “depth” or “breadth”. reverse: Reverse the order (bottom up).

Returns:

A list of nodes.

watch(obj, attribute_name, callback, init=True)

Watches for modifications to reactive attributes on another object.

Example: :rtype: None

Here’s how you could detect when the app changes from dark to light mode (and vice versa).

```python def on_dark_change(old_value:bool, new_value:bool):

# Called when app.dark changes. print(“App.dark when from {old_value} to {new_value}”)

self.watch(self.app, “dark”, self.on_dark_change, init=False) ```

Args:

obj: Object containing attribute to watch. attribute_name: Attribute to watch. callback: A callback to run when attribute changes. init: Check watchers on first call.

watch_disabled()

Update the styles of the widget and its children when disabled is toggled.

Return type:

None

watch_has_focus(value)

Update from CSS if has focus state changes.

Return type:

None

watch_mouse_over(value)

Update from CSS if mouse over state changes.

Return type:

None

property window_region: Region

The region within the scrollable area that is currently visible.

Returns:

New region.

property workers: WorkerManager

The app’s worker manager. Shortcut for self.app.workers.