textual.dom
The module contains DOMNode
, the base class for any object within the Textual Document Object Model,
which includes all Widgets, Screens, and Apps.
WalkMethod
module-attribute
¶
Valid walking methods for the DOMNode.walk_children
method.
BadIdentifier
¶
Bases: Exception
Exception raised if you supply a id
attribute or class name in the wrong format.
DOMNode
¶
Bases: MessagePump
The base class for object that can be in the Textual DOM (App and Widget)
ancestors
property
¶
ancestors_with_self
property
¶
auto_refresh
property
writable
¶
Number of seconds between automatic refresh, or None
for no automatic refresh.
background_colors
property
¶
children
property
¶
classes
class-attribute
instance-attribute
¶
CSS class names for this node.
colors
property
¶
css_identifier_styled
property
¶
css_path_nodes
property
¶
css_tree
property
¶
A Rich tree to display the DOM, annotated with the node's CSS.
Log this to visualize your app in the textual console.
Returns:
Type | Description |
---|---|
Tree
|
A Tree renderable. |
display
property
writable
¶
displayed_children
property
¶
parent
property
¶
The parent node.
All nodes have parent once added to the DOM, with the exception of the App which is the root node.
rich_style
property
¶
screen
property
¶
The screen containing this node.
Returns:
Type | Description |
---|---|
'Screen[object]'
|
A screen object. |
Raises:
Type | Description |
---|---|
NoScreen
|
If this node isn't mounted (and has no screen). |
text_style
property
¶
Get the text style object.
A widget's style is influenced by its parent. for instance if a parent is bold, then the child will also be bold.
Returns:
Type | Description |
---|---|
Style
|
A Rich Style. |
tree
property
¶
A Rich tree to display the DOM.
Log this to visualize your app in the textual console.
Returns:
Type | Description |
---|---|
Tree
|
A Tree renderable. |
visible
property
writable
¶
Is this widget visible in the DOM?
If a widget hasn't had its visibility set explicitly, then it inherits it from its DOM ancestors.
This may be set explicitly to override inherited values.
The valid values include the valid values for the visibility
rule and the booleans
True
or False
, to set the widget to be visible or invisible, respectively.
When a node is invisible, Textual will reserve space for it, but won't display anything.
action_toggle
async
¶
action_toggle(attribute_name)
add_class
¶
add_class(*class_names, update=True)
check_action
¶
check_action(action, parameters)
Check whether an action is enabled.
Implement this method to add logic for dynamic actions / bindings.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
str
|
The name of an action. |
required |
|
A tuple of any action parameters. |
required |
Returns:
Type | Description |
---|---|
bool | None
|
|
data_bind
¶
Bind reactive data so that changes to a reactive automatically change the reactive on another widget.
Reactives may be given as positional arguments or keyword arguments. See the guide on data binding.
Example
Raises:
Type | Description |
---|---|
ReactiveError
|
If the data wasn't bound. |
Returns:
Type | Description |
---|---|
Self
|
Self. |
get_component_styles
¶
Get a "component" styles object (must be defined in COMPONENT_CLASSES classvar).
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
Name of the component. |
required |
Raises:
Type | Description |
---|---|
KeyError
|
If the component class doesn't exist. |
Returns:
Type | Description |
---|---|
RenderStyles
|
A Styles object. |
get_pseudo_classes
¶
has_class
¶
has_class(*class_names)
has_pseudo_class
¶
has_pseudo_class(class_name)
has_pseudo_classes
¶
has_pseudo_classes(class_names)
mutate_reactive
¶
mutate_reactive(reactive)
Force an update to a mutable reactive.
Textual will automatically detect when a reactive is set to a new value, but it is unable to detect if a value is mutated (such as updating a list, dict, or attribute of an object). If you do wish to use a collection or other mutable object in a reactive, then you can call this method after your reactive is updated. This will ensure that all the reactive superpowers work.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
Reactive[ReactiveType]
|
A reactive property (use the class scope syntax, i.e. |
required |
notify_style_update
¶
Called after styles are updated.
Implement this in a subclass if you want to clear any cached data when the CSS is reloaded.
query_children
¶
query_children(selector=None)
Query the DOM for the immediate children that match a selector or widget type.
Note that this will not return child widgets more than a single level deep. If you want to a query to potentially match all children in the widget tree, see query.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
str | type[QueryType] | None
|
A CSS selector, widget type, or |
None
|
Returns:
Type | Description |
---|---|
DOMQuery[Widget] | DOMQuery[QueryType]
|
A query object. |
query_one
¶
query_one(selector, expect_type=None)
Get a widget from this widget's children that matches a selector or widget type.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
str | type[QueryType]
|
A selector or widget type. |
required |
|
type[QueryType] | None
|
Require the object be of the supplied type, or None for any type. |
None
|
Raises:
Type | Description |
---|---|
WrongType
|
If the wrong type was found. |
NoMatches
|
If no node matches the query. |
TooManyMatches
|
If there is more than one matching node in the query. |
Returns:
Type | Description |
---|---|
QueryType | Widget
|
A widget matching the selector. |
refresh_bindings
¶
remove_class
¶
remove_class(*class_names, update=True)
run_worker
¶
run_worker(
work,
name="",
group="default",
description="",
exit_on_error=True,
start=True,
exclusive=False,
thread=False,
)
Run work in a worker.
A worker runs a function, coroutine, or awaitable, in the background as an async task or as a thread.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
WorkType[ResultType]
|
A function, async function, or an awaitable object to run in a worker. |
required |
|
str | None
|
A short string to identify the worker (in logs and debugging). |
''
|
|
str
|
A short string to identify a group of workers. |
'default'
|
|
str
|
A longer string to store longer information on the worker. |
''
|
|
bool
|
Exit the app if the worker raises an error. Set to |
True
|
|
bool
|
Start the worker immediately. |
True
|
|
bool
|
Cancel all workers in the same group. |
False
|
|
bool
|
Mark the worker as a thread worker. |
False
|
Returns:
Type | Description |
---|---|
Worker[ResultType]
|
New Worker instance. |
set_class
¶
set_reactive
¶
Sets a reactive value without invoking validators or watchers.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
Reactive[ReactiveType]
|
A reactive property (use the class scope syntax, i.e. |
required |
|
ReactiveType
|
New value of reactive. |
required |
Raises:
Type | Description |
---|---|
AttributeError
|
If the first argument is not a reactive. |
sort_children
¶
Sort child widgets with an optional key function.
If key
is not provided then widgets will be sorted in the order they are constructed.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
Callable[[Widget], SupportsRichComparison] | None
|
A callable which accepts a widget and returns something that can be sorted,
or |
None
|
|
bool
|
Sort in descending order. |
False
|
toggle_class
¶
toggle_class(*class_names)
walk_children
¶
walk_children(
filter_type: type[WalkType],
*,
with_self: bool = False,
method: WalkMethod = "depth",
reverse: bool = False
) -> list[WalkType]
walk_children(
filter_type=None,
*,
with_self=False,
method="depth",
reverse=False
)
Walk the subtree rooted at this node, and return every descendant encountered in a list.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
type[WalkType] | None
|
Filter only this type, or None for no filter. |
None
|
|
bool
|
Also yield self in addition to descendants. |
False
|
|
WalkMethod
|
One of "depth" or "breadth". |
'depth'
|
|
bool
|
Reverse the order (bottom up). |
False
|
Returns:
Type | Description |
---|---|
list[DOMNode] | list[WalkType]
|
A list of nodes. |
watch
¶
watch(obj, attribute_name, callback, init=True)
Watches for modifications to reactive attributes on another object.
Example:
Here's how you could detect when the app changes from dark to light mode (and vice versa).
```python
def on_dark_change(old_value:bool, new_value:bool):
# Called when app.dark changes.
print("App.dark when from {old_value} to {new_value}")
self.watch(self.app, "dark", self.on_dark_change, init=False)
```
Parameters:
Name | Type | Description | Default |
---|---|---|---|
|
DOMNode
|
Object containing attribute to watch. |
required |
|
str
|
Attribute to watch. |
required |
|
WatchCallbackType
|
A callback to run when attribute changes. |
required |
|
bool
|
Check watchers on first call. |
True
|