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
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: 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: 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: Style

Style of links.

Returns
Type Description
Style

Rich style.

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 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 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 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 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 of the animate.

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.

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

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

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
RenderableType

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.