Dom node
A DOMNode is a 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
class
¶
Bases: Exception
Exception raised if you supply a id
attribute or class name in the wrong format.
DOMNode
class
¶
Bases: MessagePump
The base class for object that can be in the Textual DOM (App and Widget)
SCOPED_CSS
class-attribute
¶
Should default css be limited to the widget type?
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.
add_class
method
¶
Add class names to this Node.
Parameters
Name | Type | Description | Default |
---|---|---|---|
*class_names |
str
|
CSS class names to add. |
()
|
Returns
Type | Description |
---|---|
Self
|
Self. |
get_component_styles
method
¶
Get a "component" styles object (must be defined in COMPONENT_CLASSES classvar).
Parameters
Name | Type | Description | Default |
---|---|---|---|
name |
str
|
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
method
¶
has_class
method
¶
has_pseudo_class
method
¶
notify_style_update
method
¶
Called after styles are updated.
Implement this in a subclass if you want to clear any cached data when the CSS is reloaded.
query
method
¶
query_one
method
¶
Get a single Widget matching the given selector or selector type.
Parameters
Name | Type | Description | Default |
---|---|---|---|
selector |
str | type[QueryType]
|
A selector. |
required |
expect_type |
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. |
remove_class
method
¶
Remove class names from this Node.
Parameters
Name | Type | Description | Default |
---|---|---|---|
*class_names |
str
|
CSS class names to remove. |
()
|
Returns
Type | Description |
---|---|
Self
|
Self. |
run_worker
method
¶
def run_worker(
self,
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 |
---|---|---|---|
work |
WorkType[ResultType]
|
A function, async function, or an awaitable object to run in a worker. |
required |
name |
str | None
|
A short string to identify the worker (in logs and debugging). |
''
|
group |
str
|
A short string to identify a group of workers. |
'default'
|
description |
str
|
A longer string to store longer information on the worker. |
''
|
exit_on_error |
bool
|
Exit the app if the worker raises an error. Set to |
True
|
start |
bool
|
Start the worker immediately. |
True
|
exclusive |
bool
|
Cancel all workers in the same group. |
False
|
thread |
bool
|
Mark the worker as a thread worker. |
False
|
Returns
Type | Description |
---|---|
Worker[ResultType]
|
New Worker instance. |
set_class
method
¶
Add or remove class(es) based on a condition.
Parameters
Name | Type | Description | Default |
---|---|---|---|
add |
bool
|
Add the classes if True, otherwise remove them. |
required |
Returns
Type | Description |
---|---|
Self
|
Self. |
set_classes
method
¶
set_styles
method
¶
Set custom styles on this object.
Parameters
Name | Type | Description | Default |
---|---|---|---|
css |
str | None
|
Styles in CSS format. |
None
|
**update_styles |
Keyword arguments map style names on to style. |
{}
|
Returns
Type | Description |
---|---|
Self
|
Self. |
toggle_class
method
¶
Toggle class names on this Node.
Parameters
Name | Type | Description | Default |
---|---|---|---|
*class_names |
str
|
CSS class names to toggle. |
()
|
Returns
Type | Description |
---|---|
Self
|
Self. |
walk_children
method
¶
Walk the subtree rooted at this node, and return every descendant encountered in a list.
Parameters
Name | Type | Description | Default |
---|---|---|---|
filter_type |
type[WalkType] | None
|
Filter only this type, or None for no filter. |
None
|
with_self |
bool
|
Also yield self in addition to descendants. |
False
|
method |
WalkMethod
|
One of "depth" or "breadth". |
'depth'
|
reverse |
bool
|
Reverse the order (bottom up). |
False
|
Returns
Type | Description |
---|---|
list[DOMNode] | list[WalkType]
|
A list of nodes. |
watch
method
¶
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).
Parameters
Name | Type | Description | Default |
---|---|---|---|
obj |
DOMNode
|
Object containing attribute to watch. |
required |
attribute_name |
str
|
Attribute to watch. |
required |
callback |
WatchCallbackType
|
A callback to run when attribute changes. |
required |
init |
bool
|
Check watchers on first call. |
True
|