textual.widget
This module contains the Widget
class, the base class for all widgets.
AwaitMount
¶
BadWidgetName
¶
Bases: Exception
Raised when widget class names do not satisfy the required restrictions.
MountError
¶
Bases: WidgetError
Error raised when there was a problem with the mount request.
PseudoClasses
¶
Bases: NamedTuple
Used for render/render_line based widgets that use caching. This structure can be used as a cache-key.
Widget
¶
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 |
---|---|---|---|
|
Widget
|
Child widgets. |
()
|
|
str | None
|
The name of the widget. |
None
|
|
str | None
|
The ID of the widget in the DOM. |
None
|
|
str | None
|
The CSS classes for the widget. |
None
|
|
bool
|
Whether the widget is disabled or not. |
False
|
ALLOW_MAXIMIZE
class-attribute
¶
Defines default logic to allow the widget to be maximized.
None
Use default behavior (Focusable widgets may be maximized)False
Do not allow widget to be maximizedTrue
Allow widget to be maximized
absolute_offset
instance-attribute
¶
Force an absolute offset for the widget (used by tooltips).
allow_horizontal_scroll
property
¶
Check if horizontal scroll is permitted.
May be overridden if you want different logic regarding allowing scrolling.
allow_maximize
property
¶
Check if the widget may be maximized.
Returns:
Type | Description |
---|---|
bool
|
|
allow_vertical_scroll
property
¶
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(True)
Widget will highlight links automatically.
border_subtitle
class-attribute
instance-attribute
¶
A title to show in the bottom border (if there is one).
border_title
class-attribute
instance-attribute
¶
A title to show in the top border (if there is one).
can_focus_children
class-attribute
instance-attribute
¶
Widget's children may receive focus.
container_size
property
¶
container_viewport
property
¶
The viewport region (parent window).
Returns:
Type | Description |
---|---|
Region
|
The region that contains this widget. |
content_offset
property
¶
An offset from the Widget origin where the content begins.
Returns:
Type | Description |
---|---|
Offset
|
Offset from widget's origin. |
content_region
property
¶
Gets an absolute region containing the content (minus padding and border).
Returns:
Type | Description |
---|---|
Region
|
Screen region that contains a widget's content. |
content_size
property
¶
disabled
class-attribute
instance-attribute
¶
disabled = Reactive(False)
Is the widget disabled? Disabled widgets can not be interacted with, and are typically styled to look dimmer.
dock_gutter
property
¶
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(False)
Rich renderable may expand beyond optimal size.
gutter
property
¶
Spacing for padding / border / scrollbars.
Returns:
Type | Description |
---|---|
Spacing
|
Additional spacing around content area. |
has_focus
class-attribute
instance-attribute
¶
Does this widget have focus? Read only.
highlight_link_id
class-attribute
instance-attribute
¶
highlight_link_id = Reactive('')
The currently highlighted link id. Read only.
horizontal_scrollbar
property
¶
The 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
¶
The current hover style (style under the mouse cursor). Read only.
is_disabled
property
¶
Is the widget disabled either because disabled=True
or an ancestor has disabled=True
.
is_horizontal_scroll_end
property
¶
Is the horizontal scroll position at the maximum?
is_horizontal_scrollbar_grabbed
property
¶
Is the user dragging the vertical scrollbar?
is_mouse_over
property
¶
Is the mouse currently over this widget?
Note this will be True
if the mouse pointer is within the widget's region, even if
the mouse pointer is not directly over the widget (there could be another widget between
the mouse pointer and self).
is_vertical_scroll_end
property
¶
Is the vertical scroll position at the maximum?
is_vertical_scrollbar_grabbed
property
¶
Is the user dragging the vertical scrollbar?
layer
property
¶
layers
property
¶
layout
property
¶
Get the layout object if set in styles, or a default layout.
Returns:
Type | Description |
---|---|
Layout
|
A layout object. |
link_style_hover
property
¶
loading
class-attribute
instance-attribute
¶
loading = Reactive(False)
If set to True
this widget will temporarily be replaced with a loading indicator.
lock
instance-attribute
¶
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.
mouse_hover
class-attribute
instance-attribute
¶
Is the mouse over this widget? Read only.
offset
property
writable
¶
outer_size
property
¶
region
property
¶
scroll_offset
property
¶
Get the current scroll offset.
Returns:
Type | Description |
---|---|
Offset
|
Offset a container has been scrolled by. |
scroll_target_x
class-attribute
instance-attribute
¶
Scroll target destination, X coord.
scroll_target_y
class-attribute
instance-attribute
¶
Scroll target destination, Y coord.
scroll_x
class-attribute
instance-attribute
¶
The scroll position on the X axis.
scroll_y
class-attribute
instance-attribute
¶
The scroll position on the Y axis.
scrollable_content_region
property
¶
Gets an absolute region containing the scrollable content (minus padding, border, and scrollbars).
Returns:
Type | Description |
---|---|
Region
|
Screen region that contains a widget's content. |
scrollable_size
property
¶
scrollbar_corner
property
¶
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_size_horizontal
property
¶
Get the height used by the horizontal scrollbar.
Returns:
Type | Description |
---|---|
int
|
Number of rows in the horizontal scrollbar. |
scrollbar_size_vertical
property
¶
Get the width used by the vertical scrollbar.
Returns:
Type | Description |
---|---|
int
|
Number of columns in the vertical scrollbar. |
scrollbars_enabled
property
¶
scrollbars_space
property
¶
The number of cells occupied by scrollbars for width and height
show_horizontal_scrollbar
class-attribute
instance-attribute
¶
Show a horizontal scrollbar?
show_vertical_scrollbar
class-attribute
instance-attribute
¶
Show a vertical scrollbar?
shrink
class-attribute
instance-attribute
¶
shrink = Reactive(True)
Rich renderable may shrink below optimal size.
siblings
property
¶
size
property
¶
vertical_scrollbar
property
¶
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
¶
The widget region relative to its container (which may not be visible, depending on scroll offset).
Returns:
Type | Description |
---|---|
Region
|
The virtual region. |
virtual_region_with_margin
property
¶
The widget region relative to its container (including margin), which may not be visible, depending on the scroll offset.
Returns:
Type | Description |
---|---|
Region
|
The virtual region of the Widget, inclusive of its margin. |
visible_siblings
property
¶
window_region
property
¶
The region within the scrollable area that is currently visible.
Returns:
Type | Description |
---|---|
Region
|
New region. |
allow_focus
¶
allow_focus_children
¶
Check if a widget's children may be focused.
The base class returns can_focus_children
.
This method may be overridden if additional logic is required.
Returns:
Type | Description |
---|---|
bool
|
|
anchor
¶
anchor(*, animate=False)
Anchor the widget, which scrolls it into view (like scroll_visible), but also keeps it in view if the widget's size changes, or the size of its container changes.
Note
Anchored widgets will be un-anchored if the users scrolls the container.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
bool
|
|
False
|
animate
¶
animate(
attribute,
value,
*,
final_value=...,
duration=None,
speed=None,
delay=0.0,
easing=DEFAULT_EASING,
on_complete=None,
level="full"
)
Animate an attribute.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
str
|
Name of the attribute to animate. |
required |
|
float | Animatable
|
The value to animate to. |
required |
|
object
|
The final value of the animation. Defaults to |
...
|
|
float | None
|
The duration (in seconds) of the animation. |
None
|
|
float | None
|
The speed of the animation. |
None
|
|
float
|
A delay (in seconds) before the animation starts. |
0.0
|
|
EasingFunction | str
|
An easing method. |
DEFAULT_EASING
|
|
CallbackType | None
|
A callable to invoke when the animation is finished. |
None
|
|
AnimationLevel
|
Minimum level required for the animation to take place (inclusive). |
'full'
|
batch
async
¶
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.
begin_capture_print
¶
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 |
---|---|---|---|
|
bool
|
Whether to capture stdout. |
True
|
|
bool
|
Whether to capture stderr. |
True
|
blur
¶
Blur (un-focus) the widget.
Focus will be moved to the next available widget in the focus chain.
Returns:
Type | Description |
---|---|
Self
|
The |
can_view_entire
¶
can_view_entire(widget)
Check if a given widget is fully within 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
|
A widget that is a descendant of self. |
required |
Returns:
Type | Description |
---|---|
bool
|
|
can_view_partial
¶
can_view_partial(widget)
Check if a given widget at least partially visible within the current view (scrollable area).
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
Widget
|
A widget that is a descendant of self. |
required |
Returns:
Type | Description |
---|---|
bool
|
|
clear_cached_dimensions
¶
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
¶
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.
compose_add_child
¶
compose_add_child(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:
Name | Type | Description | Default |
---|---|---|---|
|
Widget
|
A Widget to add. |
required |
focus
¶
focus(scroll_visible=True)
get_child_by_id
¶
get_child_by_id(
id: str, expect_type: type[ExpectType]
) -> ExpectType
get_child_by_id(id, expect_type=None)
Return the first child (immediate descendent) of this node with the given ID.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
str
|
The ID of the child. |
required |
|
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
¶
get_child_by_type(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:
Name | Type | Description | Default |
---|---|---|---|
|
type[ExpectType]
|
The type of the child to search for. |
required |
Raises:
Type | Description |
---|---|
NoMatches
|
If no matching child is found. |
Returns:
Type | Description |
---|---|
ExpectType
|
The first immediate child widget with the expected type. |
get_content_height
¶
Called by Textual to get the height of the content area. May be overridden in a subclass.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
Size
|
Size of the container (immediate parent) widget. |
required |
|
Size
|
Size of the viewport. |
required |
|
int
|
Width of renderable. |
required |
Returns:
Type | Description |
---|---|
int
|
The height of the content. |
get_content_width
¶
Called by textual to get the width of the content area. May be overridden in a subclass.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
Size
|
Size of the container (immediate parent) widget. |
required |
|
Size
|
Size of the viewport. |
required |
Returns:
Type | Description |
---|---|
int
|
The optimal width of the content. |
get_loading_widget
¶
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
¶
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_style_at
¶
get_widget_by_id
¶
get_widget_by_id(
id: str, expect_type: type[ExpectType]
) -> ExpectType
get_widget_by_id(id, expect_type=None)
Return the first descendant widget with the given ID.
Performs a depth-first search rooted at this widget.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
str
|
The ID to search for in the subtree. |
required |
|
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
¶
Mount widgets below this widget (making this widget a container).
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
Widget
|
The widget(s) to mount. |
()
|
|
int | str | Widget | None
|
Optional location to mount before. An |
None
|
|
int | str | Widget | None
|
Optional location to mount after. An |
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
¶
Mount widgets from an iterable.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
Iterable[Widget]
|
An iterable of widgets. |
required |
|
int | str | Widget | None
|
Optional location to mount before. An |
None
|
|
int | str | Widget | None
|
Optional location to mount after. An |
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
¶
Move a child widget within its parent's list of children.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
int | Widget
|
The child widget to move. |
required |
|
int | Widget | None
|
Child widget or location index to move before. |
None
|
|
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
¶
Create a notification.
Tip
This method is thread-safe.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
str
|
The message for the notification. |
required |
|
str
|
The title for the notification. |
''
|
|
SeverityLevel
|
The severity of the notification. |
'information'
|
|
float | None
|
The timeout (in seconds) for the notification, or |
None
|
See App.notify
for the full
documentation for this method.
post_render
¶
Applies style attributes to the default renderable.
This method is called by Textual itself. It is unlikely you will need to call or implement this method.
Returns:
Type | Description |
---|---|
ConsoleRenderable
|
A new renderable. |
recompose
async
¶
Recompose the widget.
Recomposing will remove children and call self.compose
again to remount.
refresh
¶
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 |
---|---|---|---|
|
Region
|
Additional screen regions to mark as dirty. |
()
|
|
bool
|
Repaint the widget (will call render() again). |
True
|
|
bool
|
Also layout widgets in the view. |
False
|
|
bool
|
Re-compose the widget (will remove and re-mount children). |
False
|
Returns:
Type | Description |
---|---|
Self
|
The |
release_mouse
¶
Release the mouse.
Mouse events will only be sent when the mouse is over the widget.
remove
¶
Remove the Widget from the DOM (effectively deleting it).
Returns:
Type | Description |
---|---|
AwaitRemove
|
An awaitable object that waits for the widget to be removed. |
remove_children
¶
remove_children(selector='*')
Remove the immediate children of this Widget from the DOM.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
str | type[QueryType] | Iterable[Widget]
|
A CSS selector or iterable of widgets to remove. |
'*'
|
Returns:
Type | Description |
---|---|
AwaitRemove
|
An awaitable object that waits for the direct children to be removed. |
render
¶
Get text or Rich renderable for this widget.
Implement this for custom widgets.
Example
Returns:
Type | Description |
---|---|
RenderResult
|
Any renderable. |
render_str
¶
render_str(text_content)
scroll_down
¶
scroll_down(
*,
animate=True,
speed=None,
duration=None,
easing=None,
force=False,
on_complete=None,
level="basic",
immediate=False
)
Scroll one line down.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
bool
|
Animate scroll. |
True
|
|
float | None
|
Speed of scroll if |
None
|
|
float | None
|
Duration of animation, if |
None
|
|
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
|
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
|
CallbackType | None
|
A callable to invoke when the animation is finished. |
None
|
|
AnimationLevel
|
Minimum level required for the animation to take place (inclusive). |
'basic'
|
|
bool
|
If |
False
|
scroll_end
¶
scroll_end(
*,
animate=True,
speed=None,
duration=None,
easing=None,
force=False,
on_complete=None,
level="basic",
immediate=False,
x_axis=True,
y_axis=True
)
Scroll to the end of the container.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
bool
|
Animate scroll. |
True
|
|
float | None
|
Speed of scroll if |
None
|
|
float | None
|
Duration of animation, if |
None
|
|
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
|
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
|
CallbackType | None
|
A callable to invoke when the animation is finished. |
None
|
|
AnimationLevel
|
Minimum level required for the animation to take place (inclusive). |
'basic'
|
|
bool
|
If |
False
|
|
bool
|
Allow scrolling on X axis? |
True
|
|
bool
|
Allow scrolling on Y axis? |
True
|
scroll_home
¶
scroll_home(
*,
animate=True,
speed=None,
duration=None,
easing=None,
force=False,
on_complete=None,
level="basic",
immediate=False,
x_axis=True,
y_axis=True
)
Scroll to home position.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
bool
|
Animate scroll. |
True
|
|
float | None
|
Speed of scroll if animate is |
None
|
|
float | None
|
Duration of animation, if |
None
|
|
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
|
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
|
CallbackType | None
|
A callable to invoke when the animation is finished. |
None
|
|
AnimationLevel
|
Minimum level required for the animation to take place (inclusive). |
'basic'
|
|
bool
|
If |
False
|
|
bool
|
Allow scrolling on X axis? |
True
|
|
bool
|
Allow scrolling on Y axis? |
True
|
scroll_left
¶
scroll_left(
*,
animate=True,
speed=None,
duration=None,
easing=None,
force=False,
on_complete=None,
level="basic",
immediate=False
)
Scroll one cell left.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
bool
|
Animate scroll. |
True
|
|
float | None
|
Speed of scroll if |
None
|
|
float | None
|
Duration of animation, if |
None
|
|
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
|
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
|
CallbackType | None
|
A callable to invoke when the animation is finished. |
None
|
|
AnimationLevel
|
Minimum level required for the animation to take place (inclusive). |
'basic'
|
|
bool
|
If |
False
|
scroll_page_down
¶
scroll_page_down(
*,
animate=True,
speed=None,
duration=None,
easing=None,
force=False,
on_complete=None,
level="basic"
)
Scroll one page down.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
bool
|
Animate scroll. |
True
|
|
float | None
|
Speed of scroll if animate is |
None
|
|
float | None
|
Duration of animation, if |
None
|
|
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
|
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
|
CallbackType | None
|
A callable to invoke when the animation is finished. |
None
|
|
AnimationLevel
|
Minimum level required for the animation to take place (inclusive). |
'basic'
|
scroll_page_left
¶
scroll_page_left(
*,
animate=True,
speed=None,
duration=None,
easing=None,
force=False,
on_complete=None,
level="basic"
)
Scroll one page left.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
bool
|
Animate scroll. |
True
|
|
float | None
|
Speed of scroll if animate is |
None
|
|
float | None
|
Duration of animation, if |
None
|
|
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
|
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
|
CallbackType | None
|
A callable to invoke when the animation is finished. |
None
|
|
AnimationLevel
|
Minimum level required for the animation to take place (inclusive). |
'basic'
|
scroll_page_right
¶
scroll_page_right(
*,
animate=True,
speed=None,
duration=None,
easing=None,
force=False,
on_complete=None,
level="basic"
)
Scroll one page right.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
bool
|
Animate scroll. |
True
|
|
float | None
|
Speed of scroll if animate is |
None
|
|
float | None
|
Duration of animation, if |
None
|
|
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
|
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
|
CallbackType | None
|
A callable to invoke when the animation is finished. |
None
|
|
AnimationLevel
|
Minimum level required for the animation to take place (inclusive). |
'basic'
|
scroll_page_up
¶
scroll_page_up(
*,
animate=True,
speed=None,
duration=None,
easing=None,
force=False,
on_complete=None,
level="basic"
)
Scroll one page up.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
bool
|
Animate scroll. |
True
|
|
float | None
|
Speed of scroll if animate is |
None
|
|
float | None
|
Duration of animation, if |
None
|
|
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
|
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
|
CallbackType | None
|
A callable to invoke when the animation is finished. |
None
|
|
AnimationLevel
|
Minimum level required for the animation to take place (inclusive). |
'basic'
|
scroll_relative
¶
scroll_relative(
x=None,
y=None,
*,
animate=True,
speed=None,
duration=None,
easing=None,
force=False,
on_complete=None,
level="basic",
immediate=False
)
Scroll relative to current position.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
float | None
|
X distance (columns) to scroll, or |
None
|
|
float | None
|
Y distance (rows) to scroll, or |
None
|
|
bool
|
Animate to new scroll position. |
True
|
|
float | None
|
Speed of scroll if |
None
|
|
float | None
|
Duration of animation, if animate is |
None
|
|
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
|
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
|
CallbackType | None
|
A callable to invoke when the animation is finished. |
None
|
|
AnimationLevel
|
Minimum level required for the animation to take place (inclusive). |
'basic'
|
|
bool
|
If |
False
|
scroll_right
¶
scroll_right(
*,
animate=True,
speed=None,
duration=None,
easing=None,
force=False,
on_complete=None,
level="basic",
immediate=False
)
Scroll one cell right.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
bool
|
Animate scroll. |
True
|
|
float | None
|
Speed of scroll if animate is |
None
|
|
float | None
|
Duration of animation, if |
None
|
|
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
|
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
|
CallbackType | None
|
A callable to invoke when the animation is finished. |
None
|
|
AnimationLevel
|
Minimum level required for the animation to take place (inclusive). |
'basic'
|
|
bool
|
If |
False
|
scroll_to
¶
scroll_to(
x=None,
y=None,
*,
animate=True,
speed=None,
duration=None,
easing=None,
force=False,
on_complete=None,
level="basic",
immediate=False
)
Scroll to a given (absolute) coordinate, optionally animating.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
float | None
|
X coordinate (column) to scroll to, or |
None
|
|
float | None
|
Y coordinate (row) to scroll to, or |
None
|
|
bool
|
Animate to new scroll position. |
True
|
|
float | None
|
Speed of scroll if |
None
|
|
float | None
|
Duration of animation, if |
None
|
|
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
|
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
|
CallbackType | None
|
A callable to invoke when the animation is finished. |
None
|
|
AnimationLevel
|
Minimum level required for the animation to take place (inclusive). |
'basic'
|
|
bool
|
If |
False
|
Note
The call to scroll is made after the next refresh.
scroll_to_center
¶
scroll_to_center(
widget,
animate=True,
*,
speed=None,
duration=None,
easing=None,
force=False,
origin_visible=True,
on_complete=None,
level="basic",
immediate=False
)
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
|
The widget to scroll to the center of self. |
required |
|
bool
|
Whether to animate the scroll. |
True
|
|
float | None
|
Speed of scroll if animate is |
None
|
|
float | None
|
Duration of animation, if |
None
|
|
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
|
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
|
bool
|
Ensure that the top left corner of the widget remains visible after the scroll. |
True
|
|
CallbackType | None
|
A callable to invoke when the animation is finished. |
None
|
|
AnimationLevel
|
Minimum level required for the animation to take place (inclusive). |
'basic'
|
|
bool
|
If |
False
|
scroll_to_region
¶
scroll_to_region(
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",
x_axis=True,
y_axis=True,
immediate=False
)
Scrolls a given region in to view, if required.
This method will scroll the least distance required to move region
fully within
the scrollable area.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
Region
|
A region that should be visible. |
required |
|
Spacing | None
|
Optional spacing around the region. |
None
|
|
bool
|
|
True
|
|
float | None
|
Speed of scroll if |
None
|
|
float | None
|
Duration of animation, if |
None
|
|
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
|
bool
|
Scroll |
False
|
|
bool
|
Ensure that the top left of the widget is within the window. |
True
|
|
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
|
CallbackType | None
|
A callable to invoke when the animation is finished. |
None
|
|
AnimationLevel
|
Minimum level required for the animation to take place (inclusive). |
'basic'
|
|
bool
|
Allow scrolling on X axis? |
True
|
|
bool
|
Allow scrolling on Y axis? |
True
|
|
bool
|
If |
False
|
Returns:
Type | Description |
---|---|
Offset
|
The distance that was scrolled. |
scroll_to_widget
¶
scroll_to_widget(
widget,
*,
animate=True,
speed=None,
duration=None,
easing=None,
center=False,
top=False,
origin_visible=True,
force=False,
on_complete=None,
level="basic",
immediate=False
)
Scroll scrolling to bring a widget in to view.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
Widget
|
A descendant widget. |
required |
|
bool
|
|
True
|
|
float | None
|
Speed of scroll if |
None
|
|
float | None
|
Duration of animation, if |
None
|
|
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
|
bool
|
Scroll widget to top of container. |
False
|
|
bool
|
Ensure that the top left of the widget is within the window. |
True
|
|
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
|
CallbackType | None
|
A callable to invoke when the animation is finished. |
None
|
|
AnimationLevel
|
Minimum level required for the animation to take place (inclusive). |
'basic'
|
|
bool
|
If |
False
|
Returns:
Type | Description |
---|---|
bool
|
|
scroll_up
¶
scroll_up(
*,
animate=True,
speed=None,
duration=None,
easing=None,
force=False,
on_complete=None,
level="basic",
immediate=False
)
Scroll one line up.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
bool
|
Animate scroll. |
True
|
|
float | None
|
Speed of scroll if |
None
|
|
float | None
|
Duration of animation, if |
None
|
|
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
|
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
|
CallbackType | None
|
A callable to invoke when the animation is finished. |
None
|
|
AnimationLevel
|
Minimum level required for the animation to take place (inclusive). |
'basic'
|
|
bool
|
If |
False
|
scroll_visible
¶
scroll_visible(
animate=True,
*,
speed=None,
duration=None,
top=False,
easing=None,
force=False,
on_complete=None,
level="basic",
immediate=False
)
Scroll the container to make this widget visible.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
bool
|
Animate scroll. |
True
|
|
float | None
|
Speed of scroll if animate is |
None
|
|
float | None
|
Duration of animation, if |
None
|
|
bool
|
Scroll to top of container. |
False
|
|
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
|
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
|
CallbackType | None
|
A callable to invoke when the animation is finished. |
None
|
|
AnimationLevel
|
Minimum level required for the animation to take place (inclusive). |
'basic'
|
|
bool
|
If |
False
|
set_loading
¶
set_loading(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:
Name | Type | Description | Default |
---|---|---|---|
|
bool
|
|
required |
Returns:
Type | Description |
---|---|
None
|
An optional awaitable. |
stop_animation
async
¶
suppress_click
¶
Suppress a click event.
This will prevent a Click event being sent, if called after a mouse down event and before the click itself.
watch_disabled
¶
Update the styles of the widget and its children when disabled is toggled.
with_tooltip
¶
with_tooltip(tooltip)
Chainable method to set a tooltip.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
RenderableType | None
|
New tooltip, or |
required |
Returns:
Type | Description |
---|---|
Self
|
Self. |