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 class-attribute instance-attribute

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 class-attribute instance-attribute

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 property

link_hover_style: Style

Style of links underneath the mouse cursor.

Returns

Type	Description
Style	Rich Style.

link_style property

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.