Widget

widget

AwaitMount

An awaitable returned by mount() and mount_all().

Example

await self.mount(Static("foo"))

MountError

Bases: WidgetError

Error raised when there was a problem with the mount request.

RenderCache

Bases: NamedTuple

Stores results of a previous render.

Widget

Bases: DOMNode

A Widget is the base class for Textual widgets.

See also static for starting point for your own widgets.

allow_horizontal_scroll: bool property

Check if horizontal scroll is permitted.

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

Returns:

Type	Description
bool	True if the widget may scroll horizontally.

allow_vertical_scroll: bool property

Check if vertical scroll is permitted.

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

Returns:

Type	Description
bool	True if the widget may scroll vertically.

auto_links class-attribute

Widget will highlight links automatically.

border_subtitle class-attribute

The one-line border subtitle, which may contain markup to be parsed.

border_title class-attribute

The one-line border title, which may contain markup to be parsed.

can_focus: bool class-attribute

Widget may receive focus.

can_focus_children: bool class-attribute

Widget's children may receive focus.

container_size: Size property

The size of the container (parent widget).

Returns:

Type	Description
Size	Container size.

container_viewport: Region property

The viewport region (parent window).

Returns:

Type	Description
Region	The region that contains this widget.

content_offset: Offset property

An offset from the Widget origin where the content begins.

Returns:

Type	Description
Offset	Offset from widget's origin.

content_region: Region property

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

Returns:

Type	Description
Region	Screen region that contains a widget's content.

content_size: Size property

Get the size of the content area.

expand class-attribute

Rich renderable may expand.

focusable: bool property

Can this widget currently receive focus?

focusable_children: list[Widget] property

Get the children which may be focused.

Returns:

Type	Description
list[Widget]	List of widgets that can receive focus.

gutter: Spacing property

Spacing for padding / border / scrollbars.

Returns:

Type	Description
Spacing	Additional spacing around content area.

horizontal_scrollbar: ScrollBar property

Get a vertical scrollbar (create if necessary).

Returns:

Type	Description
ScrollBar	ScrollBar Widget.

is_container: bool property

Check if this widget is a container (contains other widgets).

Returns:

Type	Description
bool	True if this widget is a container.

is_scrollable: bool property

Check if this Widget may be scrolled.

Returns:

Type	Description
bool	True if this widget may be scrolled.

is_transparent: bool property

Check if the background styles is not set.

Returns:

Type	Description
bool	True if there is background color, otherwise False.

layer: str property

Get the name of this widgets layer.

Returns:

Type	Description
str	Name of layer.

layers: tuple[str, ...] property

Layers of from parent.

Returns:

Type	Description
tuple[str, ...]	Tuple of layer names.

link_hover_style: Style property

Style of links with mouse hover.

link_style: Style property

Style of links.

max_scroll_x: int property

The maximum value of scroll_x.

max_scroll_y: int property

The maximum value of scroll_y.

offset: Offset writable property

Widget offset from origin.

Returns:

Type	Description
Offset	Relative offset.

outer_size: Size property

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

Returns:

Type	Description
Size	Outer size.

region: Region property

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

Raises:

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

Returns:

Type	Description
Region	Region within screen occupied by widget.

scroll_offset: Offset property

Get the current scroll offset.

Returns:

Type	Description
Offset	Offset a container has been scrolled by.

scrollable_content_region: Region property

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

Returns:

Type	Description
Region	Screen region that contains a widget's content.

scrollbar_corner: ScrollBarCorner property

Return the ScrollBarCorner - the cells that appear between the horizontal and vertical scrollbars (only when both are visible).

scrollbar_gutter: Spacing property

Spacing required to fit scrollbar(s).

Returns:

Type	Description
Spacing	Scrollbar gutter spacing.

scrollbar_size_horizontal: int property

Get the height used by the horizontal scrollbar.

Returns:

Type	Description
int	Number of rows in the horizontal scrollbar.

scrollbar_size_vertical: int property

Get the width used by the vertical scrollbar.

Returns:

Type	Description
int	Number of columns in the vertical scrollbar.

scrollbars_enabled: tuple[bool, bool] property

A tuple of booleans that indicate if scrollbars are enabled.

Returns:

Type	Description
tuple[bool, bool]	A tuple of (, )

scrollbars_space: tuple[int, int] property

The number of cells occupied by scrollbars for width and height

shrink class-attribute

Rich renderable may shrink.

siblings: list[Widget] property

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

Returns:

Type	Description
list[Widget]	A list of siblings.

size: Size property

The size of the content area.

Returns:

Type	Description
Size	Content area size.

vertical_scrollbar: ScrollBar property

Get a vertical scrollbar (create if necessary).

Returns:

Type	Description
ScrollBar	ScrollBar Widget.

virtual_region: Region property

The widget region relative to it's container. Which may not be visible, depending on scroll offset.

virtual_region_with_margin: Region property

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

Returns:

Type	Description
Region	The virtual region of the Widget, inclusive of its margin.

visible_siblings: list[Widget] property

A list of siblings which will be shown.

Returns:

Type	Description
list[Widget]	List of siblings.

window_region: Region property

The region within the scrollable area that is currently visible.

Returns:

Type	Description
Region	New region.

animate(attribute, value, *, final_value=..., duration=None, speed=None, delay=0.0, easing=DEFAULT_EASING, on_complete=None)

Animate an attribute.

Parameters:

Name	Type	Description	Default
attribute	str	Name of the attribute to animate.	required
value	float | Animatable	The value to animate to.	required
final_value	object	The final value of the animation. Defaults to value if not set.	...
duration	float | None	The duration of the animate. Defaults to None.	None
speed	float | None	The speed of the animation. Defaults to None.	None
delay	float	A delay (in seconds) before the animation starts. Defaults to 0.0.	0.0
easing	EasingFunction | str	An easing method. Defaults to "in_out_cubic".	DEFAULT_EASING
on_complete	CallbackType | None	A callable to invoke when the animation is finished. Defaults to None.	None

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.

Parameters:

Name	Type	Description	Default
capture	bool	True to capture or False to release. Defaults to True.	True

check_message_enabled(message)

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

Parameters:

Name	Type	Description	Default
message	Message	A message object	required

Returns:

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

compose()

Called by Textual to create child widgets.

Extend this to build a UI.

Example

def compose(self) -> ComposeResult:
    yield Header()
    yield Container(
        Tree(), Viewer()
    )
    yield Footer()

focus(scroll_visible=True)

Give focus to this widget.

Parameters:

Name	Type	Description	Default
scroll_visible	bool	Scroll parent to make this widget visible. Defaults to True.	True

get_child_by_id(id, expect_type=None)

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

Parameters:

Name	Type	Description	Default
id	str	The ID of the child.	required
expect_type	type[ExpectType] | None	Require the object be of the supplied type, or None for any type. Defaults to None.	None

Returns:

Type	Description
ExpectType | Widget	The first child of this node with the ID.

Raises:

Type	Description
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.

Parameters:

Name	Type	Description	Default
expect_type	type[ExpectType]	The type of the expected child.	required

Raises:

Type	Description
NoMatches	If no valid child is found.

Returns:

Type	Description
ExpectType	A widget.

get_component_rich_style(name, *, partial=False)

Get a Rich style for a component.

Parameters:

Name	Type	Description	Default
name	str	Name of component.	required
partial	bool	Return a partial style (not combined with parent).	False

Returns:

Type	Description
Style	A Rich style object.

get_content_height(container, viewport, width)

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

Parameters:

Name	Type	Description	Default
container	Size	Size of the container (immediate parent) widget.	required
viewport	Size	Size of the viewport.	required
width	int	Width of renderable.	required

Returns:

Type	Description
int	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.

Parameters:

Name	Type	Description	Default
container	Size	Size of the container (immediate parent) widget.	required
viewport	Size	Size of the viewport.	required

Returns:

Type	Description
int	The optimal width of the content.

get_pseudo_classes()

Pseudo classes for a widget.

Returns:

Type	Description
Iterable[str]	Names of the pseudo classes.

get_style_at(x, y)

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

Parameters:

Name	Type	Description	Default
x	int	X coordinate relative to the widget.	required
y	int	Y coordinate relative to the widget.	required

Returns:

Type	Description
Style	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.

Parameters:

Name	Type	Description	Default
id	str	The ID to search for in the subtree.	required
expect_type	type[ExpectType] | None	Require the object be of the supplied type, or None for any type.	None

Returns:

Type	Description
ExpectType | Widget	The first descendant encountered with this ID.

Raises:

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

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

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

Parameters:

Name	Type	Description	Default
*widgets	Widget	The widget(s) to mount.	()
before	int | str | Widget | None	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.	None
after	int | str | Widget | None	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.	None

Returns:

Type	Description
AwaitMount	An awaitable object that waits for widgets to be mounted.

Raises:

Type	Description
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.

Parameters:

Name	Type	Description	Default
widgets	Iterable[Widget]	An iterable of widgets.	required
before	int | str | Widget | None	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.	None
after	int | str | Widget | None	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.	None

Returns:

Type	Description
AwaitMount	An awaitable object that waits for widgets to be mounted.

Raises:

Type	Description
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.

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

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

Parameters:

Name	Type	Description	Default
child	int | Widget	The child widget to move.	required
before	int | Widget | None	Optional location to move before. An int is the index of the child to move before, a str is a query_one query to find the widget to move before.	None
after	int | Widget | None	Optional location to move after. An int is the index of the child to move after, a str is a query_one query to find the widget to move after.	None

Raises:

Type	Description
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.

post_message(message)

Post a message to this widget.

Parameters:

Name	Type	Description	Default
message	Message	Message to post.	required

Returns:

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

post_render(renderable)

Applies style attributes to the default renderable.

Returns:

Type	Description
ConsoleRenderable	A new renderable.

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

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

Parameters:

Name	Type	Description	Default
*regions	Region	Additional screen regions to mark as dirty.	()
repaint	bool	Repaint the widget (will call render() again). Defaults to True.	True
layout	bool	Also layout widgets in the view. Defaults to False.	False

release_mouse()

Release the mouse.

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

remove()

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

Returns:

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

render()

Get renderable for widget.

Returns:

Type	Description
RenderableType	Any renderable.

render_line(y)

Render a line of content.

Parameters:

Name	Type	Description	Default
y	int	Y Coordinate of line.	required

Returns:

Type	Description
Strip	A rendered line.

render_lines(crop)

Render the widget in to lines.

Parameters:

Name	Type	Description	Default
crop	Region	Region within visible area to render.	required

Returns:

Type	Description
list[Strip]	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.

Parameters:

Name	Type	Description	Default
text_content	str | Text	Text or str.	required

Returns:

Type	Description
Text	A text object.

reset_focus()

Reset the focus (move it to the next available widget).

run_action(action) async

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

Parameters:

Name	Type	Description	Default
action	str	Action encoded as a string.	required

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

Scroll one line down.

Parameters:

Name	Type	Description	Default
animate	bool	Animate scroll.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False

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

Scroll to the end of the container.

Parameters:

Name	Type	Description	Default
animate	bool	Animate scroll.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False

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

Scroll to home position.

Parameters:

Name	Type	Description	Default
animate	bool	Animate scroll.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False

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

Scroll one cell left.

Parameters:

Name	Type	Description	Default
animate	bool	Animate scroll.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False

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

Scroll one page down.

Parameters:

Name	Type	Description	Default
animate	bool	Animate scroll.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False

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

Scroll one page left.

Parameters:

Name	Type	Description	Default
animate	bool	Animate scroll.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False

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

Scroll one page right.

Parameters:

Name	Type	Description	Default
animate	bool	Animate scroll.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False

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

Scroll one page up.

Parameters:

Name	Type	Description	Default
animate	bool	Animate scroll.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False

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

Scroll relative to current position.

Parameters:

Name	Type	Description	Default
x	float | None	X distance (columns) to scroll, or None for no change.	None
y	float | None	Y distance (rows) to scroll, or None for no change.	None
animate	bool	Animate to new scroll position.	True
speed	float | None	Speed of scroll if animate is True. Or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False

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

Scroll one cell right.

Parameters:

Name	Type	Description	Default
animate	bool	Animate scroll.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False

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

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

Parameters:

Name	Type	Description	Default
x	float | None	X coordinate (column) to scroll to, or None for no change.	None
y	float | None	Y coordinate (row) to scroll to, or None for no change.	None
animate	bool	Animate to new scroll position.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False

Note

The call to scroll is made after the next refresh.

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

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.

Parameters:

Name	Type	Description	Default
region	Region	A region that should be visible.	required
spacing	Spacing | None	Optional spacing around the region.	None
animate	bool	True to animate, or False to jump.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
top	bool	Scroll region to top of container.	False
force	bool	Force scrolling even when prohibited by overflow styling.	False

Returns:

Type	Description
Offset	The distance that was scrolled.

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

Scroll scrolling to bring a widget in to view.

Parameters:

Name	Type	Description	Default
widget	Widget	A descendant widget.	required
animate	bool	True to animate, or False to jump.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
top	bool	Scroll widget to top of container.	False
force	bool	Force scrolling even when prohibited by overflow styling.	False

Returns:

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

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

Scroll one line up.

Parameters:

Name	Type	Description	Default
animate	bool	Animate scroll.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False

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

Scroll the container to make this widget visible.

Parameters:

Name	Type	Description	Default
animate	bool	Animate scroll.	True
speed	float | None	Speed of scroll if animate is True; or None to use duration.	None
duration	float | None	Duration of animation, if animate is True and speed is None.	None
top	bool	Scroll to top of container.	False
easing	EasingFunction | str | None	An easing method for the scrolling animation.	None
force	bool	Force scrolling even when prohibited by overflow styling.	False

validate_border_subtitle(subtitle)

Ensure we only use a single line for the border subtitle.

validate_border_title(title)

Ensure we only use a single line for the border title.

watch_disabled()

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

watch_has_focus(value)

Update from CSS if has focus state changes.

watch_mouse_over(value)

Update from CSS if mouse over state changes.

WidgetError

Bases: Exception

Base widget error.