Skip to content

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.

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.

Style of links with mouse hover.

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.