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

BadWidgetName class

Bases: Exception

Raised when widget class names do not satisfy the required restrictions.

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

Parameter	Default	Description
*children Widget	()	Child widgets.
name str | None	None	The name of the widget.
id str | None	None	The ID of the widget in the DOM.
classes str | None	None	The CSS classes for the widget.
disabled bool	False	Whether the widget is disabled or not.

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

auto_links: Reactive[bool] = Reactive(True)

Widget will highlight links automatically.

border_subtitle instance-attribute class-attribute

border_subtitle: str | Text | None = _BorderTitle()

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

border_title instance-attribute class-attribute

border_title: str | Text | None = _BorderTitle()

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

can_focus instance-attribute class-attribute

can_focus: bool = False

Widget may receive focus.

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

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

Does this widget have focus? Read only.

highlight_link_id instance-attribute class-attribute

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

The currently highlighted link id. Read only.

horizontal_scrollbar property

horizontal_scrollbar: ScrollBar

The horizontal scrollbar.

Note

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

Returns

Type	Description
ScrollBar	ScrollBar Widget.

hover_style instance-attribute class-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_mounted property

is_mounted: bool

Check if this widget is mounted.

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_style property

link_style: Style

Style of links.

Returns

Type	Description
Style	Rich style.

link_style_hover property

link_style_hover: Style

Style of links underneath the mouse cursor.

Returns

Type	Description
Style	Rich Style.

loading instance-attribute class-attribute

loading: Reactive[bool] = Reactive(False)

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

lock instance-attribute

lock = Lock()

asyncio lock to be used to synchronize the state of the widget.

Two different tasks might call methods on a widget at the same time, which might result in a race condition. This can be fixed by adding async with widget.lock: around the method calls.

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

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

Is the mouse over this widget? Read only.

offset writable property

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

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

The scroll position on the X axis.

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

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

Show a horizontal scrollbar?

show_vertical_scrollbar instance-attribute class-attribute

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

Show a vertical scrollbar?

shrink instance-attribute class-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 writable property

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

allow_focus method

def allow_focus(self):

Check if the widget is permitted to focus.

The base class returns can_focus. This method maybe overridden if additional logic is required.

Returns

Type	Description
bool	True if the widget may be focused, or False if it may not be focused.

allow_focus_children method

def allow_focus_children(self):

Check if a widget's children may be focused.

The base class returns can_focus_children. This method maybe overridden if additional logic is required.

Returns

Type	Description
bool	True if the widget's children may be focused, or False if the widget's children may not be focused.

animate method

def animate(
    self,
    attribute,
    value,
    *,
    final_value=...,
    duration=None,
    speed=None,
    delay=0.0,
    easing=DEFAULT_EASING,
    on_complete=None,
    level="full"
):

Animate an attribute.

Parameters

Parameter	Default	Description
attribute str	required	Name of the attribute to animate.
value float | Animatable	required	The value to animate to.
final_value object	...	The final value of the animation. Defaults to value if not set.
duration float | None	None	The duration (in seconds) of the animation.
speed float | None	None	The speed of the animation.
delay float	0.0	A delay (in seconds) before the animation starts.
easing EasingFunction | str	DEFAULT_EASING	An easing method.
on_complete CallbackType | None	None	A callable to invoke when the animation is finished.
level AnimationLevel	'full'	Minimum level required for the animation to take place (inclusive).

batch async

def batch(self):

Async context manager that combines widget locking and update batching.

Use this async context manager whenever you want to acquire the widget lock and batch app updates at the same time.

Example

async with container.batch():
    await container.remove_children(Button)
    await container.mount(Label("All buttons are gone."))

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

Parameter	Default	Description
stdout bool	True	Whether to capture stdout.
stderr bool	True	Whether to capture stderr.

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

Parameter	Default	Description
widget Widget	required	A widget that is a descendant of self.

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

Parameter	Default	Description
capture bool	True	True to capture or False to release.

check_message_enabled method

def check_message_enabled(self, message):

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

Parameters

Parameter	Default	Description
message Message	required	A message object

Returns

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

clear_cached_dimensions method

def clear_cached_dimensions(self):

Clear cached results of get_content_width and get_content_height.

Call if the widget's renderable changes size after the widget has been created.

Note

This is not required if you are extending Static.

compose method

def compose(self):

Called by Textual to create child widgets.

This method is called when a widget is mounted or by setting recompose=True when calling refresh().

Note that you don't typically need to explicitly call this method.

Example

def compose(self) -> ComposeResult:
    yield Header()
    yield Label("Press the button below:")
    yield Button()
    yield Footer()

compose_add_child method

def compose_add_child(self, widget):

Add a node to children.

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

Parameters

Parameter	Default	Description
widget Widget	required	A Widget to add.

end_capture_print method

def end_capture_print(self):

End print capture (set with begin_capture_print).

focus method

def focus(self, scroll_visible=True):

Give focus to this widget.

Parameters

Parameter	Default	Description
scroll_visible bool	True	Scroll parent to make this widget visible.

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

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

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 the first immediate child of a given type.

Only returns exact matches, and so will not match subclasses of the given type.

Parameters

Parameter	Default	Description
expect_type type[ExpectType]	required	The type of the child to search for.

Raises

Type	Description
NoMatches	If no matching child is found.

Returns

Type	Description
ExpectType	The first immediate child widget with the expected type.

get_component_rich_style method

def get_component_rich_style(self, name, *, partial=False):

Get a Rich style for a component.

Parameters

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

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

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

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

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

Returns

Type	Description
int	The optimal width of the content.

get_loading_widget method

def get_loading_widget(self):

Get a widget to display a loading indicator.

The default implementation will defer to App.get_loading_widget.

Returns

Type	Description
Widget	A widget in place of this widget to indicate a loading.

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

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

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

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

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

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

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

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

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_composed_widgets async

def mount_composed_widgets(self, widgets):

Called by Textual to mount widgets after compose.

There is generally no need to implement this method in your application. See Lazy for a class which uses this method to implement lazy mounting.

Parameters

Parameter	Default	Description
widgets list[Widget]	required	A list of child widgets.

move_child method

def move_child(self, child, *, before=None, after=None):

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

Parameters

Parameter	Default	Description
child int | Widget	required	The child widget to move.
before int | Widget | None	None	Child widget or location index to move before.
after int | Widget | None	None	Child widget or location index to move after.

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

Parameter	Default	Description
message str	required	The message for the notification.
title str	''	The title for the notification.
severity SeverityLevel	'information'	The severity of the notification.
timeout float	Notification.timeout	The timeout (in seconds) for the notification.

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

Parameter	Default	Description
message Message	required	Message to post.

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.

recompose async

def recompose(self):

Recompose the widget.

Recomposing will remove children and call self.compose again to remount.

refresh method

def refresh(
    self,
    *regions,
    repaint=True,
    layout=False,
    recompose=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

Parameter	Default	Description
*regions Region	()	Additional screen regions to mark as dirty.
repaint bool	True	Repaint the widget (will call render() again).
layout bool	False	Also layout widgets in the view.
recompose bool	False	Re-compose the widget (will remove and re-mount children).

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, selector='*'):

Remove the immediate children of this Widget from the DOM.

Parameters

Parameter	Default	Description
selector str | type[QueryType]	'*'	A CSS selector to specify which direct children to remove.

Returns

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

render method

def render(self):

Get text or Rich renderable for this widget.

Implement this for custom widgets.

Example

from textual.app import RenderableType
from textual.widget import Widget

class CustomWidget(Widget):
    def render(self) -> RenderableType:
        return "Welcome to [bold red]Textual[/]!"

Returns

Type	Description
RenderResult	Any renderable.

render_line method

def render_line(self, y):

Render a line of content.

Parameters

Parameter	Default	Description
y int	required	Y Coordinate of line.

Returns

Type	Description
Strip	A rendered line.

render_lines method

def render_lines(self, crop):

Render the widget in to lines.

Parameters

Parameter	Default	Description
crop Region	required	Region within visible area to render.

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

Parameter	Default	Description
text_content str | Text	required	Text or str.

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

Parameter	Default	Description
action str	required	Action encoded as a string.

scroll_down method

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

Scroll one line down.

Parameters

Parameter	Default	Description
animate bool	True	Animate scroll.
speed float | None	None	Speed of scroll if animate is True; or None to use duration.
duration float | None	None	Duration of animation, if animate is True and speed is None.
easing EasingFunction | str | None	None	An easing method for the scrolling animation.
force bool	False	Force scrolling even when prohibited by overflow styling.
on_complete CallbackType | None	None	A callable to invoke when the animation is finished.
level AnimationLevel	'basic'	Minimum level required for the animation to take place (inclusive).

scroll_end method

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

Scroll to the end of the container.

Parameters

Parameter	Default	Description
animate bool	True	Animate scroll.
speed float | None	None	Speed of scroll if animate is True; or None to use duration.
duration float | None	None	Duration of animation, if animate is True and speed is None.
easing EasingFunction | str | None	None	An easing method for the scrolling animation.
force bool	False	Force scrolling even when prohibited by overflow styling.
on_complete CallbackType | None	None	A callable to invoke when the animation is finished.
level AnimationLevel	'basic'	Minimum level required for the animation to take place (inclusive).

scroll_home method

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

Scroll to home position.

Parameters

Parameter	Default	Description
animate bool	True	Animate scroll.
speed float | None	None	Speed of scroll if animate is True; or None to use duration.
duration float | None	None	Duration of animation, if animate is True and speed is None.
easing EasingFunction | str | None	None	An easing method for the scrolling animation.
force bool	False	Force scrolling even when prohibited by overflow styling.
on_complete CallbackType | None	None	A callable to invoke when the animation is finished.
level AnimationLevel	'basic'	Minimum level required for the animation to take place (inclusive).

scroll_left method

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

Scroll one cell left.

Parameters

Parameter	Default	Description
animate bool	True	Animate scroll.
speed float | None	None	Speed of scroll if animate is True; or None to use duration.
duration float | None	None	Duration of animation, if animate is True and speed is None.
easing EasingFunction | str | None	None	An easing method for the scrolling animation.
force bool	False	Force scrolling even when prohibited by overflow styling.
on_complete CallbackType | None	None	A callable to invoke when the animation is finished.
level AnimationLevel	'basic'	Minimum level required for the animation to take place (inclusive).

scroll_page_down method

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

Scroll one page down.

Parameters

Parameter	Default	Description
animate bool	True	Animate scroll.
speed float | None	None	Speed of scroll if animate is True; or None to use duration.
duration float | None	None	Duration of animation, if animate is True and speed is None.
easing EasingFunction | str | None	None	An easing method for the scrolling animation.
force bool	False	Force scrolling even when prohibited by overflow styling.
on_complete CallbackType | None	None	A callable to invoke when the animation is finished.
level AnimationLevel	'basic'	Minimum level required for the animation to take place (inclusive).

scroll_page_left method

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

Scroll one page left.

Parameters

Parameter	Default	Description
animate bool	True	Animate scroll.
speed float | None	None	Speed of scroll if animate is True; or None to use duration.
duration float | None	None	Duration of animation, if animate is True and speed is None.
easing EasingFunction | str | None	None	An easing method for the scrolling animation.
force bool	False	Force scrolling even when prohibited by overflow styling.
on_complete CallbackType | None	None	A callable to invoke when the animation is finished.
level AnimationLevel	'basic'	Minimum level required for the animation to take place (inclusive).

scroll_page_right method

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

Scroll one page right.

Parameters

Parameter	Default	Description
animate bool	True	Animate scroll.
speed float | None	None	Speed of scroll if animate is True; or None to use duration.
duration float | None	None	Duration of animation, if animate is True and speed is None.
easing EasingFunction | str | None	None	An easing method for the scrolling animation.
force bool	False	Force scrolling even when prohibited by overflow styling.
on_complete CallbackType | None	None	A callable to invoke when the animation is finished.
level AnimationLevel	'basic'	Minimum level required for the animation to take place (inclusive).

scroll_page_up method

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

Scroll one page up.

Parameters

Parameter	Default	Description
animate bool	True	Animate scroll.
speed float | None	None	Speed of scroll if animate is True; or None to use duration.
duration float | None	None	Duration of animation, if animate is True and speed is None.
easing EasingFunction | str | None	None	An easing method for the scrolling animation.
force bool	False	Force scrolling even when prohibited by overflow styling.
on_complete CallbackType | None	None	A callable to invoke when the animation is finished.
level AnimationLevel	'basic'	Minimum level required for the animation to take place (inclusive).

scroll_relative method

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

Scroll relative to current position.

Parameters

Parameter	Default	Description
x float | None	None	X distance (columns) to scroll, or None for no change.
y float | None	None	Y distance (rows) to scroll, or None for no change.
animate bool	True	Animate to new scroll position.
speed float | None	None	Speed of scroll if animate is True. Or None to use duration.
duration float | None	None	Duration of animation, if animate is True and speed is None.
easing EasingFunction | str | None	None	An easing method for the scrolling animation.
force bool	False	Force scrolling even when prohibited by overflow styling.
on_complete CallbackType | None	None	A callable to invoke when the animation is finished.
level AnimationLevel	'basic'	Minimum level required for the animation to take place (inclusive).

scroll_right method

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

Scroll one cell right.

Parameters

Parameter	Default	Description
animate bool	True	Animate scroll.
speed float | None	None	Speed of scroll if animate is True; or None to use duration.
duration float | None	None	Duration of animation, if animate is True and speed is None.
easing EasingFunction | str | None	None	An easing method for the scrolling animation.
force bool	False	Force scrolling even when prohibited by overflow styling.
on_complete CallbackType | None	None	A callable to invoke when the animation is finished.
level AnimationLevel	'basic'	Minimum level required for the animation to take place (inclusive).

scroll_to method

def scroll_to(
    self,
    x=None,
    y=None,
    *,
    animate=True,
    speed=None,
    duration=None,
    easing=None,
    force=False,
    on_complete=None,
    level="basic"
):

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

Parameters

Parameter	Default	Description
x float | None	None	X coordinate (column) to scroll to, or None for no change.
y float | None	None	Y coordinate (row) to scroll to, or None for no change.
animate bool	True	Animate to new scroll position.
speed float | None	None	Speed of scroll if animate is True; or None to use duration.
duration float | None	None	Duration of animation, if animate is True and speed is None.
easing EasingFunction | str | None	None	An easing method for the scrolling animation.
force bool	False	Force scrolling even when prohibited by overflow styling.
on_complete CallbackType | None	None	A callable to invoke when the animation is finished.
level AnimationLevel	'basic'	Minimum level required for the animation to take place (inclusive).

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,
    level="basic"
):

Scroll this widget to the center of self.

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

Parameters

Parameter	Default	Description
widget Widget	required	The widget to scroll to the center of self.
animate bool	True	Whether to animate the scroll.
speed float | None	None	Speed of scroll if animate is True; or None to use duration.
duration float | None	None	Duration of animation, if animate is True and speed is None.
easing EasingFunction | str | None	None	An easing method for the scrolling animation.
force bool	False	Force scrolling even when prohibited by overflow styling.
origin_visible bool	True	Ensure that the top left corner of the widget remains visible after the scroll.
on_complete CallbackType | None	None	A callable to invoke when the animation is finished.
level AnimationLevel	'basic'	Minimum level required for the animation to take place (inclusive).

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,
    level="basic"
):

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

Parameter	Default	Description
region Region	required	A region that should be visible.
spacing Spacing | None	None	Optional spacing around the region.
animate bool	True	True to animate, or False to jump.
speed float | None	None	Speed of scroll if animate is True; or None to use duration.
duration float | None	None	Duration of animation, if animate is True and speed is None.
easing EasingFunction | str | None	None	An easing method for the scrolling animation.
top bool	False	Scroll region to top of container.
origin_visible bool	True	Ensure that the top left of the widget is within the window.
force bool	False	Force scrolling even when prohibited by overflow styling.
on_complete CallbackType | None	None	A callable to invoke when the animation is finished.
level AnimationLevel	'basic'	Minimum level required for the animation to take place (inclusive).

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,
    level="basic"
):

Scroll scrolling to bring a widget in to view.

Parameters

Parameter	Default	Description
widget Widget	required	A descendant widget.
animate bool	True	True to animate, or False to jump.
speed float | None	None	Speed of scroll if animate is True; or None to use duration.
duration float | None	None	Duration of animation, if animate is True and speed is None.
easing EasingFunction | str | None	None	An easing method for the scrolling animation.
top bool	False	Scroll widget to top of container.
origin_visible bool	True	Ensure that the top left of the widget is within the window.
force bool	False	Force scrolling even when prohibited by overflow styling.
on_complete CallbackType | None	None	A callable to invoke when the animation is finished.
level AnimationLevel	'basic'	Minimum level required for the animation to take place (inclusive).

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,
    level="basic"
):

Scroll one line up.

Parameters

Parameter	Default	Description
animate bool	True	Animate scroll.
speed float | None	None	Speed of scroll if animate is True; or None to use duration.
duration float | None	None	Duration of animation, if animate is True and speed is None.
easing EasingFunction | str | None	None	An easing method for the scrolling animation.
force bool	False	Force scrolling even when prohibited by overflow styling.
on_complete CallbackType | None	None	A callable to invoke when the animation is finished.
level AnimationLevel	'basic'	Minimum level required for the animation to take place (inclusive).

scroll_visible method

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

Scroll the container to make this widget visible.

Parameters

Parameter	Default	Description
animate bool	True	Animate scroll.
speed float | None	None	Speed of scroll if animate is True; or None to use duration.
duration float | None	None	Duration of animation, if animate is True and speed is None.
top bool	False	Scroll to top of container.
easing EasingFunction | str | None	None	An easing method for the scrolling animation.
force bool	False	Force scrolling even when prohibited by overflow styling.
on_complete CallbackType | None	None	A callable to invoke when the animation is finished.
level AnimationLevel	'basic'	Minimum level required for the animation to take place (inclusive).

set_loading method

def set_loading(self, loading):

Set or reset the loading state of this widget.

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

Parameters

Parameter	Default	Description
loading bool	required	True to put the widget into a loading state, or False to reset the loading state.

Returns

Type	Description
Awaitable	An optional awaitable.

stop_animation async

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

Stop an animation on an attribute.

Parameters

Parameter	Default	Description
attribute str	required	Name of the attribute whose animation should be stopped.
complete bool	True	Should the animation be set to its final value?

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.