Widget
widget
¶
AwaitMount
¶
An awaitable returned by mount() and mount_all().
Example
await self.mount(Static("foo"))
MountError
¶
Bases: WidgetError
Error raised when there was a problem with the mount request.
RenderCache
¶
Widget
¶
Bases: DOMNode
A Widget is the base class for Textual widgets.
See also static for starting point for your own widgets.
allow_horizontal_scroll: bool
property
¶
Check if horizontal scroll is permitted.
May be overridden if you want different logic regarding allowing scrolling.
Returns:
Type | Description |
---|---|
bool
|
True if the widget may scroll horizontally. |
allow_vertical_scroll: bool
property
¶
Check if vertical scroll is permitted.
May be overridden if you want different logic regarding allowing scrolling.
Returns:
Type | Description |
---|---|
bool
|
True if the widget may scroll vertically. |
auto_links
class-attribute
¶
Widget will highlight links automatically.
border_subtitle
class-attribute
¶
The one-line border subtitle, which may contain markup to be parsed.
border_title
class-attribute
¶
The one-line border title, which may contain markup to be parsed.
can_focus: bool
class-attribute
¶
Widget may receive focus.
can_focus_children: bool
class-attribute
¶
Widget's children may receive focus.
container_size: Size
property
¶
container_viewport: Region
property
¶
The viewport region (parent window).
Returns:
Type | Description |
---|---|
Region
|
The region that contains this widget. |
content_offset: Offset
property
¶
An offset from the Widget origin where the content begins.
Returns:
Type | Description |
---|---|
Offset
|
Offset from widget's origin. |
content_region: 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: Size
property
¶
Get the size of the content area.
expand
class-attribute
¶
Rich renderable may expand.
focusable: bool
property
¶
Can this widget currently receive focus?
focusable_children: list[Widget]
property
¶
gutter: Spacing
property
¶
Spacing for padding / border / scrollbars.
Returns:
Type | Description |
---|---|
Spacing
|
Additional spacing around content area. |
horizontal_scrollbar: ScrollBar
property
¶
Get a vertical scrollbar (create if necessary).
Returns:
Type | Description |
---|---|
ScrollBar
|
ScrollBar Widget. |
is_container: bool
property
¶
Check if this widget is a container (contains other widgets).
Returns:
Type | Description |
---|---|
bool
|
True if this widget is a container. |
is_scrollable: bool
property
¶
Check if this Widget may be scrolled.
Returns:
Type | Description |
---|---|
bool
|
True if this widget may be scrolled. |
is_transparent: bool
property
¶
Check if the background styles is not set.
Returns:
Type | Description |
---|---|
bool
|
|
layer: str
property
¶
layers: tuple[str, ...]
property
¶
link_hover_style: Style
property
¶
Style of links with mouse hover.
link_style: Style
property
¶
Style of links.
max_scroll_x: int
property
¶
The maximum value of scroll_x
.
max_scroll_y: int
property
¶
The maximum value of scroll_y
.
offset: Offset
writable
property
¶
outer_size: Size
property
¶
region: Region
property
¶
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: Offset
property
¶
Get the current scroll offset.
Returns:
Type | Description |
---|---|
Offset
|
Offset a container has been scrolled by. |
scrollable_content_region: 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. |
scrollbar_corner: ScrollBarCorner
property
¶
Return the ScrollBarCorner - the cells that appear between the horizontal and vertical scrollbars (only when both are visible).
scrollbar_gutter: Spacing
property
¶
scrollbar_size_horizontal: int
property
¶
Get the height used by the horizontal scrollbar.
Returns:
Type | Description |
---|---|
int
|
Number of rows in the horizontal scrollbar. |
scrollbar_size_vertical: int
property
¶
Get the width used by the vertical scrollbar.
Returns:
Type | Description |
---|---|
int
|
Number of columns in the vertical scrollbar. |
scrollbars_enabled: tuple[bool, bool]
property
¶
scrollbars_space: tuple[int, int]
property
¶
The number of cells occupied by scrollbars for width and height
shrink
class-attribute
¶
Rich renderable may shrink.
siblings: list[Widget]
property
¶
size: Size
property
¶
vertical_scrollbar: ScrollBar
property
¶
Get a vertical scrollbar (create if necessary).
Returns:
Type | Description |
---|---|
ScrollBar
|
ScrollBar Widget. |
virtual_region: Region
property
¶
The widget region relative to it's container. Which may not be visible, depending on scroll offset.
virtual_region_with_margin: Region
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: list[Widget]
property
¶
window_region: Region
property
¶
The region within the scrollable area that is currently visible.
Returns:
Type | Description |
---|---|
Region
|
New region. |
animate(attribute, value, *, final_value=..., duration=None, speed=None, delay=0.0, easing=DEFAULT_EASING, on_complete=None)
¶
Animate an attribute.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
attribute |
str
|
Name of the attribute to animate. |
required |
value |
float | Animatable
|
The value to animate to. |
required |
final_value |
object
|
The final value of the animation. Defaults to |
...
|
duration |
float | None
|
The duration of the animate. Defaults to None. |
None
|
speed |
float | None
|
The speed of the animation. Defaults to None. |
None
|
delay |
float
|
A delay (in seconds) before the animation starts. Defaults to 0.0. |
0.0
|
easing |
EasingFunction | str
|
An easing method. Defaults to "in_out_cubic". |
DEFAULT_EASING
|
on_complete |
CallbackType | None
|
A callable to invoke when the animation is finished. Defaults to None. |
None
|
capture_mouse(capture=True)
¶
Capture (or release) the mouse.
When captured, mouse events will go to this widget even when the pointer is not directly over the widget.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
capture |
bool
|
True to capture or False to release. Defaults to True. |
True
|
check_message_enabled(message)
¶
compose()
¶
focus(scroll_visible=True)
¶
Give focus to this widget.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
scroll_visible |
bool
|
Scroll parent to make this widget visible. Defaults to True. |
True
|
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 |
---|---|---|---|
id |
str
|
The ID of the child. |
required |
expect_type |
type[ExpectType] | None
|
Require the object be of the supplied type, or None for any type. Defaults to None. |
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(expect_type)
¶
get_component_rich_style(name, *, partial=False)
¶
get_content_height(container, viewport, width)
¶
Called by Textual to get the height of the content area. May be overridden in a subclass.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
container |
Size
|
Size of the container (immediate parent) widget. |
required |
viewport |
Size
|
Size of the viewport. |
required |
width |
int
|
Width of renderable. |
required |
Returns:
Type | Description |
---|---|
int
|
The height of the content. |
get_content_width(container, viewport)
¶
Called by textual to get the width of the content area. May be overridden in a subclass.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
container |
Size
|
Size of the container (immediate parent) widget. |
required |
viewport |
Size
|
Size of the viewport. |
required |
Returns:
Type | Description |
---|---|
int
|
The optimal width of the content. |
get_pseudo_classes()
¶
get_style_at(x, y)
¶
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 |
---|---|---|---|
id |
str
|
The ID to search for in the subtree. |
required |
expect_type |
type[ExpectType] | None
|
Require the object be of the supplied type, or None for any type. |
None
|
Returns:
Type | Description |
---|---|
ExpectType | Widget
|
The first descendant encountered with this ID. |
Raises:
Type | Description |
---|---|
NoMatches
|
if no children could be found for this ID. |
WrongType
|
if the wrong type was found. |
mount(*widgets, before=None, after=None)
¶
Mount widgets below this widget (making this widget a container).
Parameters:
Name | Type | Description | Default |
---|---|---|---|
*widgets |
Widget
|
The widget(s) to mount. |
()
|
before |
int | str | Widget | None
|
Optional location to mount before. An |
None
|
after |
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(widgets, *, before=None, after=None)
¶
Mount widgets from an iterable.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
widgets |
Iterable[Widget]
|
An iterable of widgets. |
required |
before |
int | str | Widget | None
|
Optional location to mount before. An |
None
|
after |
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(child, before=None, after=None)
¶
Move a child widget within its parent's list of children.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
child |
int | Widget
|
The child widget to move. |
required |
before |
int | Widget | None
|
Optional location to move before. An |
None
|
after |
int | Widget | None
|
Optional location to move after. An |
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.
post_message(message)
¶
post_render(renderable)
¶
Applies style attributes to the default renderable.
Returns:
Type | Description |
---|---|
ConsoleRenderable
|
A new renderable. |
refresh(*regions, repaint=True, layout=False)
¶
Initiate a refresh of the widget.
This method sets an internal flag to perform a refresh, which will be done on the next idle event. Only one refresh will be done even if this method is called multiple times.
By default this method will cause the content of the widget to refresh, but not change its size. You can also
set layout=True
to perform a layout.
Warning
It is rarely necessary to call this method explicitly. Updating styles or reactive attributes will do this automatically.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
*regions |
Region
|
Additional screen regions to mark as dirty. |
()
|
repaint |
bool
|
Repaint the widget (will call render() again). Defaults to True. |
True
|
layout |
bool
|
Also layout widgets in the view. Defaults to False. |
False
|
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. |
render()
¶
Get renderable for widget.
Returns:
Type | Description |
---|---|
RenderableType
|
Any renderable. |
render_line(y)
¶
render_lines(crop)
¶
render_str(text_content)
¶
reset_focus()
¶
Reset the focus (move it to the next available widget).
run_action(action)
async
¶
Perform a given action, with this widget as the default namespace.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
action |
str
|
Action encoded as a string. |
required |
scroll_down(*, animate=True, speed=None, duration=None, easing=None, force=False)
¶
Scroll one line down.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
animate |
bool
|
Animate scroll. |
True
|
speed |
float | None
|
Speed of scroll if |
None
|
duration |
float | None
|
Duration of animation, if |
None
|
easing |
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
force |
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
scroll_end(*, animate=True, speed=None, duration=None, easing=None, force=False)
¶
Scroll to the end of the container.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
animate |
bool
|
Animate scroll. |
True
|
speed |
float | None
|
Speed of scroll if |
None
|
duration |
float | None
|
Duration of animation, if |
None
|
easing |
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
force |
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
scroll_home(*, animate=True, speed=None, duration=None, easing=None, force=False)
¶
Scroll to home position.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
animate |
bool
|
Animate scroll. |
True
|
speed |
float | None
|
Speed of scroll if animate is |
None
|
duration |
float | None
|
Duration of animation, if |
None
|
easing |
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
force |
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
scroll_left(*, animate=True, speed=None, duration=None, easing=None, force=False)
¶
Scroll one cell left.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
animate |
bool
|
Animate scroll. |
True
|
speed |
float | None
|
Speed of scroll if |
None
|
duration |
float | None
|
Duration of animation, if |
None
|
easing |
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
force |
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
scroll_page_down(*, animate=True, speed=None, duration=None, easing=None, force=False)
¶
Scroll one page down.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
animate |
bool
|
Animate scroll. |
True
|
speed |
float | None
|
Speed of scroll if animate is |
None
|
duration |
float | None
|
Duration of animation, if |
None
|
easing |
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
force |
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
scroll_page_left(*, animate=True, speed=None, duration=None, easing=None, force=False)
¶
Scroll one page left.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
animate |
bool
|
Animate scroll. |
True
|
speed |
float | None
|
Speed of scroll if animate is |
None
|
duration |
float | None
|
Duration of animation, if |
None
|
easing |
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
force |
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
scroll_page_right(*, animate=True, speed=None, duration=None, easing=None, force=False)
¶
Scroll one page right.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
animate |
bool
|
Animate scroll. |
True
|
speed |
float | None
|
Speed of scroll if animate is |
None
|
duration |
float | None
|
Duration of animation, if |
None
|
easing |
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
force |
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
scroll_page_up(*, animate=True, speed=None, duration=None, easing=None, force=False)
¶
Scroll one page up.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
animate |
bool
|
Animate scroll. |
True
|
speed |
float | None
|
Speed of scroll if animate is |
None
|
duration |
float | None
|
Duration of animation, if |
None
|
easing |
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
force |
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
scroll_relative(x=None, y=None, *, animate=True, speed=None, duration=None, easing=None, force=False)
¶
Scroll relative to current position.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
x |
float | None
|
X distance (columns) to scroll, or |
None
|
y |
float | None
|
Y distance (rows) to scroll, or |
None
|
animate |
bool
|
Animate to new scroll position. |
True
|
speed |
float | None
|
Speed of scroll if |
None
|
duration |
float | None
|
Duration of animation, if animate is |
None
|
easing |
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
force |
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
scroll_right(*, animate=True, speed=None, duration=None, easing=None, force=False)
¶
Scroll one cell right.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
animate |
bool
|
Animate scroll. |
True
|
speed |
float | None
|
Speed of scroll if animate is |
None
|
duration |
float | None
|
Duration of animation, if |
None
|
easing |
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
force |
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
scroll_to(x=None, y=None, *, animate=True, speed=None, duration=None, easing=None, force=False)
¶
Scroll to a given (absolute) coordinate, optionally animating.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
x |
float | None
|
X coordinate (column) to scroll to, or |
None
|
y |
float | None
|
Y coordinate (row) to scroll to, or |
None
|
animate |
bool
|
Animate to new scroll position. |
True
|
speed |
float | None
|
Speed of scroll if |
None
|
duration |
float | None
|
Duration of animation, if |
None
|
easing |
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
force |
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
Note
The call to scroll is made after the next refresh.
scroll_to_region(region, *, spacing=None, animate=True, speed=None, duration=None, easing=None, top=False, force=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 |
Region
|
A region that should be visible. |
required |
spacing |
Spacing | None
|
Optional spacing around the region. |
None
|
animate |
bool
|
|
True
|
speed |
float | None
|
Speed of scroll if |
None
|
duration |
float | None
|
Duration of animation, if |
None
|
easing |
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
top |
bool
|
Scroll |
False
|
force |
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
Returns:
Type | Description |
---|---|
Offset
|
The distance that was scrolled. |
scroll_to_widget(widget, *, animate=True, speed=None, duration=None, easing=None, top=False, force=False)
¶
Scroll scrolling to bring a widget in to view.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
widget |
Widget
|
A descendant widget. |
required |
animate |
bool
|
|
True
|
speed |
float | None
|
Speed of scroll if |
None
|
duration |
float | None
|
Duration of animation, if |
None
|
easing |
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
top |
bool
|
Scroll widget to top of container. |
False
|
force |
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
Returns:
Type | Description |
---|---|
bool
|
|
scroll_up(*, animate=True, speed=None, duration=None, easing=None, force=False)
¶
Scroll one line up.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
animate |
bool
|
Animate scroll. |
True
|
speed |
float | None
|
Speed of scroll if |
None
|
duration |
float | None
|
Duration of animation, if |
None
|
easing |
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
force |
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
scroll_visible(animate=True, *, speed=None, duration=None, top=False, easing=None, force=False)
¶
Scroll the container to make this widget visible.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
animate |
bool
|
Animate scroll. |
True
|
speed |
float | None
|
Speed of scroll if animate is |
None
|
duration |
float | None
|
Duration of animation, if |
None
|
top |
bool
|
Scroll to top of container. |
False
|
easing |
EasingFunction | str | None
|
An easing method for the scrolling animation. |
None
|
force |
bool
|
Force scrolling even when prohibited by overflow styling. |
False
|
validate_border_subtitle(subtitle)
¶
Ensure we only use a single line for the border subtitle.
validate_border_title(title)
¶
Ensure we only use a single line for the border title.
watch_disabled()
¶
Update the styles of the widget and its children when disabled is toggled.
watch_has_focus(value)
¶
Update from CSS if has focus state changes.
watch_mouse_over(value)
¶
Update from CSS if mouse over state changes.