Skip to content

Widget

The base class for widgets.

AwaitMount class

def __init__(self, parent, widgets):

An optional awaitable returned by mount and mount_all.

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

MountError class

Bases: WidgetError

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

PseudoClasses class

Bases: NamedTuple

Used for render/render_line based widgets that use caching. This structure can be used as a cache-key.

enabled instance-attribute

enabled: bool

Is 'enabled' applied?

focus instance-attribute

focus: bool

Is 'focus' applied?

hover instance-attribute

hover: bool

Is 'hover' applied?

Widget class

def __init__(
    self,
    *children,
    name=None,
    id=None,
    classes=None,
    disabled=False
):

Bases: DOMNode

A Widget is the base class for Textual widgets.

See also static for starting point for your own widgets.

Parameters
Name Type Description Default
*children Widget

Child widgets.

()
name str | None

The name of the widget.

None
id str | None

The ID of the widget in the DOM.

None
classes str | None

The CSS classes for the widget.

None
disabled bool

Whether the widget is disabled or not.

False

BORDER_SUBTITLE class-attribute

BORDER_SUBTITLE: str = ''

Initial value for border_subtitle attribute.

BORDER_TITLE class-attribute

BORDER_TITLE: str = ''

Initial value for border_title attribute.

allow_horizontal_scroll property

allow_horizontal_scroll: bool

Check if horizontal scroll is permitted.

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

allow_vertical_scroll property

allow_vertical_scroll: bool

Check if vertical scroll is permitted.

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

auto_links: Reactive[bool] = Reactive(True)

Widget will highlight links automatically.

border_subtitle class-attribute instance-attribute

border_subtitle: str | Text | None = _BorderTitle()

A title to show in the bottom border (if there is one).

border_title class-attribute instance-attribute

border_title: str | Text | None = _BorderTitle()

A title to show in the top border (if there is one).

can_focus class-attribute instance-attribute

can_focus: bool = False

Widget may receive focus.

can_focus_children class-attribute instance-attribute

can_focus_children: bool = True

Widget's children may receive focus.

container_size property

container_size: Size

The size of the container (parent widget).

Returns
Type Description
Size

Container size.

container_viewport property

container_viewport: Region

The viewport region (parent window).

Returns
Type Description
Region

The region that contains this widget.

content_offset property

content_offset: Offset

An offset from the Widget origin where the content begins.

Returns
Type Description
Offset

Offset from widget's origin.

content_region property

content_region: Region

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 property

content_size: Size

The size of the content area.

Returns
Type Description
Size

Content area size.

disabled class-attribute instance-attribute

disabled: Reactive[bool] = disabled

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

dock_gutter property

dock_gutter: Spacing

Space allocated to docks in the parent.

Returns
Type Description
Spacing

Space to be subtracted from scrollable area.

expand class-attribute instance-attribute

expand: Reactive[bool] = Reactive(False)

Rich renderable may expand beyond optimal size.

focusable property

focusable: bool

Can this widget currently be focused?

gutter property

gutter: Spacing

Spacing for padding / border / scrollbars.

Returns
Type Description
Spacing

Additional spacing around content area.

has_focus class-attribute instance-attribute

has_focus: Reactive[bool] = Reactive(False, repaint=False)

Does this widget have focus? Read only.

highlight_link_id: Reactive[str] = Reactive('')

The currently highlighted link id. Read only.

horizontal_scrollbar property

horizontal_scrollbar: ScrollBar

The a horizontal scrollbar.

Note

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

Returns
Type Description
ScrollBar

ScrollBar Widget.

hover_style class-attribute instance-attribute

hover_style: Reactive[Style] = Reactive(
    Style, repaint=False
)

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

is_container property

is_container: bool

Is this widget a container (contains other widgets)?

is_horizontal_scroll_end property

is_horizontal_scroll_end: bool

Is the horizontal scroll position at the maximum?

is_horizontal_scrollbar_grabbed property

is_horizontal_scrollbar_grabbed: bool

Is the user dragging the vertical scrollbar?

is_scrollable property

is_scrollable: bool

Can this widget be scrolled?

is_vertical_scroll_end property

is_vertical_scroll_end: bool

Is the vertical scroll position at the maximum?

is_vertical_scrollbar_grabbed property

is_vertical_scrollbar_grabbed: bool

Is the user dragging the vertical scrollbar?

layer property

layer: str

Get the name of this widgets layer.

Returns
Type Description
str

Name of layer.

layers property

layers: tuple[str, ...]

Layers of from parent.

Returns
Type Description
tuple[str, ...]

Tuple of layer names.

link_hover_style: Style

Style of links underneath the mouse cursor.

Returns
Type Description
Style

Rich Style.

link_style: Style

Style of links.

Returns
Type Description
Style

Rich style.

max_scroll_x property

max_scroll_x: int

The maximum value of scroll_x.

max_scroll_y property

max_scroll_y: int

The maximum value of scroll_y.

mouse_over class-attribute instance-attribute

mouse_over: Reactive[bool] = Reactive(False, repaint=False)

Is the mouse over this widget? Read only.

offset property writable

offset: Offset

Widget offset from origin.

Returns
Type Description
Offset

Relative offset.

opacity property

opacity: float

Total opacity of widget.

outer_size property

outer_size: Size

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

Returns
Type Description
Size

Outer size.

region property

region: Region

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 property

scroll_offset: Offset

Get the current scroll offset.

Returns
Type Description
Offset

Offset a container has been scrolled by.

scroll_x class-attribute instance-attribute

scroll_x: Reactive[float] = Reactive(
    0.0, repaint=False, layout=False
)

The scroll position on the X axis.

scroll_y class-attribute instance-attribute

scroll_y: Reactive[float] = Reactive(
    0.0, repaint=False, layout=False
)

The scroll position on the Y axis.

scrollable_content_region property

scrollable_content_region: Region

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 property

scrollbar_corner: ScrollBarCorner

The scrollbar corner.

Note

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

Returns
Type Description
ScrollBarCorner

ScrollBarCorner Widget.

scrollbar_gutter property

scrollbar_gutter: Spacing

Spacing required to fit scrollbar(s).

Returns
Type Description
Spacing

Scrollbar gutter spacing.

scrollbar_size_horizontal property

scrollbar_size_horizontal: int

Get the height used by the horizontal scrollbar.

Returns
Type Description
int

Number of rows in the horizontal scrollbar.

scrollbar_size_vertical property

scrollbar_size_vertical: int

Get the width used by the vertical scrollbar.

Returns
Type Description
int

Number of columns in the vertical scrollbar.

scrollbars_enabled property

scrollbars_enabled: tuple[bool, bool]

A tuple of booleans that indicate if scrollbars are enabled.

Returns
Type Description
tuple[bool, bool]

A tuple of (, )

scrollbars_space property

scrollbars_space: tuple[int, int]

The number of cells occupied by scrollbars for width and height

show_horizontal_scrollbar class-attribute instance-attribute

show_horizontal_scrollbar: Reactive[bool] = Reactive(
    False, layout=True
)

Show a horizontal scrollbar?

show_vertical_scrollbar class-attribute instance-attribute

show_vertical_scrollbar: Reactive[bool] = Reactive(
    False, layout=True
)

Show a horizontal scrollbar?

shrink class-attribute instance-attribute

shrink: Reactive[bool] = Reactive(True)

Rich renderable may shrink below optimal size.

siblings property

siblings: list[Widget]

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

Returns
Type Description
list[Widget]

A list of siblings.

size property

size: Size

The size of the content area.

Returns
Type Description
Size

Content area size.

tooltip property writable

tooltip: RenderableType | None

Tooltip for the widget, or None for no tooltip.

vertical_scrollbar property

vertical_scrollbar: ScrollBar

The vertical scrollbar (create if necessary).

Note

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

Returns
Type Description
ScrollBar

ScrollBar Widget.

virtual_region property

virtual_region: Region

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

Returns
Type Description
Region

The virtual region.

virtual_region_with_margin 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
Type Description
Region

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

virtual_size class-attribute instance-attribute

virtual_size: Reactive[Size] = Reactive(
    Size(0, 0), layout=True
)

The virtual (scrollable) size of the widget.

visible_siblings property

visible_siblings: list[Widget]

A list of siblings which will be shown.

Returns
Type Description
list[Widget]

List of siblings.

window_region property

window_region: Region

The region within the scrollable area that is currently visible.

Returns
Type Description
Region

New region.

animate method

def animate(
    self,
    attribute,
    value,
    *,
    final_value=Ellipsis,
    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.

Ellipsis
duration float | None

The duration of the animate.

None
speed float | None

The speed of the animation.

None
delay float

A delay (in seconds) before the animation starts.

0.0
easing EasingFunction | str

An easing method.

DEFAULT_EASING
on_complete CallbackType | None

A callable to invoke when the animation is finished.

None

begin_capture_print method

def begin_capture_print(self, 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 message.

Call end_capture_print to disable print capture.

Parameters
Name Type Description Default
stdout bool

Capture stdout.

True
stderr bool

Capture stderr.

True

blur method

def blur(self):

Blur (un-focus) the widget.

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

Returns
Type Description
Self

The Widget instance.

can_view method

def can_view(self, 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.

Parameters
Name Type Description Default
widget Widget

A widget that is a descendant of self.

required
Returns
Type Description
bool

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

capture_mouse method

def capture_mouse(self, 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.

True

check_message_enabled method

def check_message_enabled(self, 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 method

def compose(self):

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()

end_capture_print method

def end_capture_print(self):

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

focus method

def focus(self, scroll_visible=True):

Give focus to this widget.

Parameters
Name Type Description Default
scroll_visible bool

Scroll parent to make this widget visible.

True
Returns
Type Description
Self

The Widget instance.

get_child_by_id method

def get_child_by_id(self, 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.

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 method

def get_child_by_type(self, 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 method

def get_component_rich_style(self, 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 method

def get_content_height(self, 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 method

def get_content_width(self, 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_class_state method

def get_pseudo_class_state(self):

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

Returns
Type Description
PseudoClasses

A PseudoClasses object describing the pseudo classes that are present.

get_pseudo_classes method

def get_pseudo_classes(self):

Pseudo classes for a widget.

Returns
Type Description
Iterable[str]

Names of the pseudo classes.

get_style_at method

def get_style_at(self, 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 method

def get_widget_by_id(self, 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 method

def mount(self, *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 method

def mount_all(self, 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 method

def move_child(self, 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

Child widget or location index to move before.

None
after int | Widget | None

Child widget or location index 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.

notify method

def notify(
    self,
    message,
    *,
    title="",
    severity="information",
    timeout=Notification.timeout
):

Create a notification.

Tip

This method is thread-safe.

Parameters
Name Type Description Default
message str

The message for the notification.

required
title str

The title for the notification.

''
severity SeverityLevel

The severity of the notification.

'information'
timeout float

The timeout for the notification.

Notification.timeout

See App.notify for the full documentation for this method.

post_message method

def post_message(self, 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 method

def post_render(self, renderable):

Applies style attributes to the default renderable.

Returns
Type Description
ConsoleRenderable

A new renderable.

refresh method

def refresh(self, *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).

True
layout bool

Also layout widgets in the view.

False
Returns
Type Description
Self

The Widget instance.

release_mouse method

def release_mouse(self):

Release the mouse.

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

remove method

def remove(self):

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

Returns
Type Description
AwaitRemove

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

remove_children method

def remove_children(self):

Remove all children of this Widget from the DOM.

Returns
Type Description
AwaitRemove

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

render method

def render(self):

Get renderable for widget.

Returns
Type Description
RenderableType

Any renderable.

render_line method

def render_line(self, 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 method

def render_lines(self, 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 method

def render_str(self, 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.

run_action async

def run_action(self, action):

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 method

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

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
on_complete CallbackType | None

A callable to invoke when the animation is finished.

None

scroll_end method

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

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
on_complete CallbackType | None

A callable to invoke when the animation is finished.

None

scroll_home method

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

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
on_complete CallbackType | None

A callable to invoke when the animation is finished.

None

scroll_left method

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

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
on_complete CallbackType | None

A callable to invoke when the animation is finished.

None

scroll_page_down method

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

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
on_complete CallbackType | None

A callable to invoke when the animation is finished.

None

scroll_page_left method

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

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
on_complete CallbackType | None

A callable to invoke when the animation is finished.

None

scroll_page_right method

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

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
on_complete CallbackType | None

A callable to invoke when the animation is finished.

None

scroll_page_up method

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

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
on_complete CallbackType | None

A callable to invoke when the animation is finished.

None

scroll_relative method

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

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
on_complete CallbackType | None

A callable to invoke when the animation is finished.

None

scroll_right method

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

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
on_complete CallbackType | None

A callable to invoke when the animation is finished.

None

scroll_to method

def scroll_to(
    self,
    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.

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
on_complete CallbackType | None

A callable to invoke when the animation is finished.

None
Note

The call to scroll is made after the next refresh.

scroll_to_center method

def scroll_to_center(
    self,
    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.

Parameters
Name Type Description Default
widget Widget

The widget to scroll to the center of self.

required
animate bool

Whether to animate the 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
origin_visible bool

Ensure that the top left corner of the widget remains visible after the scroll.

True
on_complete CallbackType | None

A callable to invoke when the animation is finished.

None

scroll_to_region method

def scroll_to_region(
    self,
    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.

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
origin_visible bool

Ensure that the top left of the widget is within the window.

True
force bool

Force scrolling even when prohibited by overflow styling.

False
on_complete CallbackType | None

A callable to invoke when the animation is finished.

None
Returns
Type Description
Offset

The distance that was scrolled.

scroll_to_widget method

def scroll_to_widget(
    self,
    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.

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
origin_visible bool

Ensure that the top left of the widget is within the window.

True
force bool

Force scrolling even when prohibited by overflow styling.

False
on_complete CallbackType | None

A callable to invoke when the animation is finished.

None
Returns
Type Description
bool

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

scroll_up method

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

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
on_complete CallbackType | None

A callable to invoke when the animation is finished.

None

scroll_visible method

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

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
on_complete CallbackType | None

A callable to invoke when the animation is finished.

None

stop_animation async

def stop_animation(self, attribute, complete=True):

Stop an animation on an attribute.

Parameters
Name Type Description Default
attribute str

Name of the attribute whose animation should be stopped.

required
complete bool

Should the animation be set to its final value?

True
Note

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

watch_disabled method

def watch_disabled(self):

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

watch_has_focus method

def watch_has_focus(self, value):

Update from CSS if has focus state changes.

watch_mouse_over method

def watch_mouse_over(self, value):

Update from CSS if mouse over state changes.

WidgetError class

Bases: Exception

Base widget error.