textual.widget

This module contains the Widget class, the base class for all widgets.

AwaitMount

AwaitMount(parent, widgets)

An optional awaitable returned by mount and mount_all.

Example

await self.mount(Static("foo"))

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.

enabled instance-attribute

enabled

Is 'enabled' applied?

focus instance-attribute

focus

Is 'focus' applied?

hover instance-attribute

hover

Is 'hover' applied?

Widget

Widget(
    *children,
    name=None,
    id=None,
    classes=None,
    disabled=False,
    markup=True
)

Bases: DOMNode

A Widget is the base class for Textual widgets.

See also static for starting point for your own widgets.

Parameters:

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

ALLOW_MAXIMIZE class-attribute

ALLOW_MAXIMIZE = None

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 maximized
• True Allow widget to be maximized

ALLOW_SELECT class-attribute

ALLOW_SELECT = True

Does this widget support automatic text selection? May be further refined with Widget.allow_select.

BORDER_SUBTITLE class-attribute

BORDER_SUBTITLE = ''

Initial value for border_subtitle attribute.

BORDER_TITLE class-attribute

BORDER_TITLE = ''

Initial value for border_title attribute.

FOCUS_ON_CLICK class-attribute

FOCUS_ON_CLICK = True

Should focusable widgets be automatically focused on click? Default return value of Widget.focus_on_click.

absolute_offset instance-attribute

absolute_offset = None

Force an absolute offset for the widget (used by tooltips).

allow_horizontal_scroll property

allow_horizontal_scroll

Check if horizontal scroll is permitted.

May be overridden if you want different logic regarding allowing scrolling.

allow_maximize property

allow_maximize

Check if the widget may be maximized.

Returns:

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

allow_select property

allow_select

Check if this widget permits text selection.

Returns:

Type	Description
bool	True if the widget supports text selection, otherwise False.

allow_vertical_scroll property

allow_vertical_scroll

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

border_subtitle = _BorderTitle()

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

border_title class-attribute instance-attribute

border_title = _BorderTitle()

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

can_focus class-attribute instance-attribute

can_focus = False

Widget may receive focus.

can_focus_children class-attribute instance-attribute

can_focus_children = True

Widget's children may receive focus.

container_scroll_offset property

container_scroll_offset

The scroll offset the nearest container ancestor.

container_size property

container_size

The size of the container (parent widget).

Returns:

Type	Description
Size	Container size.

container_viewport property

container_viewport

The viewport region (parent window).

Returns:

Type	Description
Region	The region that contains this widget.

content_offset property

content_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

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

The size of the content area.

Returns:

Type	Description
Size	Content area size.

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

dock_gutter

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.

first_child property

first_child

Is this the first widget in its siblings?

first_of_type property

first_of_type

Is this the first widget of its type in its siblings?

focusable property

focusable

Can this widget currently be focused?

gutter property

gutter

Spacing for padding / border / scrollbars.

Returns:

Type	Description
Spacing	Additional spacing around content area.

has_focus class-attribute instance-attribute

has_focus = Reactive(False, repaint=False)

Does this widget have focus? Read only.

has_focus_within property

has_focus_within

Are any descendants focused?

highlight_link_id class-attribute instance-attribute

highlight_link_id = Reactive('')

The currently highlighted link id. Read only.

horizontal_scrollbar property

horizontal_scrollbar

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

hover_style = Reactive(Style, repaint=False)

The current hover style (style under the mouse cursor). Read only.

is_anchored property

is_anchored

Is this widget anchored?

See anchor() for an explanation of anchoring.

is_container property

is_container

Is this widget a container (contains other widgets)?

is_disabled property

is_disabled

Is the widget disabled either because disabled=True or an ancestor has disabled=True.

is_even property

is_even

Is this widget at an evenly numbered position within its siblings?

is_horizontal_scroll_end property

is_horizontal_scroll_end

Is the horizontal scroll position at the maximum?

is_horizontal_scrollbar_grabbed property

is_horizontal_scrollbar_grabbed

Is the user dragging the vertical scrollbar?

is_in_maximized_view property

is_in_maximized_view

Is this widget, or a parent maximized?

is_maximized property

is_maximized

Is this widget maximized?

is_mounted property

is_mounted

Check if this widget is mounted.

is_mouse_over property

is_mouse_over

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

is_odd

Is this widget at an oddly numbered position within its siblings?

is_on_screen property

is_on_screen

Check if the node was displayed in the last screen update.

is_scrollable property

is_scrollable

Can this widget be scrolled?

is_scrolling property

is_scrolling

Is this widget currently scrolling?

is_vertical_scroll_end property

is_vertical_scroll_end

Is the vertical scroll position at the maximum?

is_vertical_scrollbar_grabbed property

is_vertical_scrollbar_grabbed

Is the user dragging the vertical scrollbar?

last_child property

last_child

Is this the last widget in its siblings?

last_of_type property

last_of_type

Is this the last widget of its type in its siblings?

layer property

layer

Get the name of this widgets layer.

Returns:

Type	Description
str	Name of layer.

layers property

layers

Layers of from parent.

Returns:

Type	Description
tuple[str, ...]	Tuple of layer names.

layout property

layout

Get the layout object if set in styles, or a default layout.

Returns:

Type	Description
Layout	A layout object.

link_style property

link_style

Style of links.

Returns:

Type	Description
Style	Rich style.

link_style_hover property

link_style_hover

Style of links underneath the mouse cursor.

Returns:

Type	Description
Style	Rich Style.

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

lock = RLock()

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

The maximum value of scroll_x.

max_scroll_y property

max_scroll_y

The maximum value of scroll_y.

mouse_hover class-attribute instance-attribute

mouse_hover = Reactive(False, repaint=False)

Is the mouse over this widget? Read only.

offset property writable

offset

Widget offset from origin.

Returns:

Type	Description
Offset	Relative offset.

opacity property

opacity

Total opacity of widget.

outer_size property

outer_size

The size of the widget (including padding and border).

Returns:

Type	Description
Size	Outer size.

region property

region

The region occupied by this widget, relative to the Screen.

Raises:

Type	Description
NoScreen	If there is no screen.
NoWidget	If the widget is not on the screen.

Returns:

Type	Description
Region	Region within screen occupied by widget.

scroll_offset property

scroll_offset

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_x = Reactive(0.0, repaint=False)

Scroll target destination, X coord.

scroll_target_y class-attribute instance-attribute

scroll_target_y = Reactive(0.0, repaint=False)

Scroll target destination, Y coord.

scroll_x class-attribute instance-attribute

scroll_x = Reactive(0.0, repaint=False, layout=False)

The scroll position on the X axis.

scroll_y class-attribute instance-attribute

scroll_y = Reactive(0.0, repaint=False, layout=False)

The scroll position on the Y axis.

scrollable_content_region property

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

scrollable_size property

scrollable_size

The size of the scrollable content.

Returns:

Type	Description
Size	Scrollable content size.

scrollbar_corner property

scrollbar_corner

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 required to fit scrollbar(s).

Returns:

Type	Description
Spacing	Scrollbar gutter spacing.

scrollbar_size_horizontal property

scrollbar_size_horizontal

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

Get the width used by the vertical scrollbar.

Returns:

Type	Description
int	Number of columns in the vertical scrollbar.

scrollbars_enabled property

scrollbars_enabled

A tuple of booleans that indicate if scrollbars are enabled.

Returns:

Type	Description
tuple[bool, bool]	A tuple of (, )

scrollbars_space property

scrollbars_space

The number of cells occupied by scrollbars for width and height

select_container property

select_container

The widget's container used when selecting text..

Returns:

Type	Description
Widget	A widget which contains this widget.

show_horizontal_scrollbar class-attribute instance-attribute

show_horizontal_scrollbar = Reactive(False, layout=True)

Show a horizontal scrollbar?

show_vertical_scrollbar class-attribute instance-attribute

show_vertical_scrollbar = Reactive(False, layout=True)

Show a vertical scrollbar?

shrink class-attribute instance-attribute

shrink = Reactive(True)

Rich renderable may shrink below optimal size.

siblings property

siblings

Get the widget's siblings (self is removed from the return list).

Returns:

Type	Description
list[Widget]	A list of siblings.

size property

size

The size of the content area.

Returns:

Type	Description
Size	Content area size.

text_selection property

text_selection

Text selection information, or None if no text is selected in this widget.

tooltip property writable

tooltip

Tooltip for the widget, or None for no tooltip.

vertical_scrollbar property

vertical_scrollbar

The vertical scrollbar (create if necessary).

Note

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

Returns:

Type	Description