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

WalkMethod: TypeAlias = Literal['depth', 'breadth']

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.

DOMError class

Bases: Exception

Base exception class for errors relating to the DOM.

DOMNode class

def __init__(self, *, name=None, id=None, classes=None):

Bases: MessagePump

The base class for object that can be in the Textual DOM (App and Widget)

SCOPED_CSS class-attribute

SCOPED_CSS: bool = True

Should default css be limited to the widget type?

ancestors property

ancestors: list[DOMNode]

A list of ancestor nodes Nodes by tracing ancestors all the way back to App.

Returns

Type	Description
list[DOMNode]	A list of nodes.

ancestors_with_self property

ancestors_with_self: list[DOMNode]

A list of Nodes by tracing a path all the way back to App.

Note

This is inclusive of self.

Returns

Type	Description
list[DOMNode]	A list of nodes.

auto_refresh property writable

auto_refresh: float | None

Number of seconds between automatic refresh, or None for no automatic refresh.

background_colors property

background_colors: tuple[Color, Color]

The background color and the color of the parent's background.

Returns

Type	Description
tuple[Color, Color]	(<background color>, <color>)

children property

children: Sequence['Widget']

A view on to the children.

Returns

Type	Description
Sequence['Widget']	The node's children.

classes class-attribute instance-attribute

classes = _ClassesDescriptor()

CSS class names for this node.

colors property

colors: tuple[Color, Color, Color, Color]

The widget's background and foreground colors, and the parent's background and foreground colors.

Returns

Type	Description
tuple[Color, Color, Color, Color]	(<parent background>, <parent color>, <background>, <color>)

css_identifier property

css_identifier: str

A CSS selector that identifies this DOM node.

css_identifier_styled property

css_identifier_styled: Text

A syntax highlighted CSS identifier.

Returns

Type	Description
Text	A Rich Text object.

css_path_nodes property

css_path_nodes: list[DOMNode]

A list of nodes from the App to this node, forming a "path".

Returns

Type	Description
list[DOMNode]	A list of nodes, where the first item is the App, and the last is this node.

css_tree property

css_tree: Tree

A Rich tree to display the DOM, annotated with the node's CSS.

Log this to visualize your app in the textual console.

Example

self.log(self.css_tree)

Returns

Type	Description
Tree	A Tree renderable.

display property writable

display: bool

Should the DOM node be displayed?

May be set to a boolean to show or hide the node, or to any valid value for the display rule.

Example

my_widget.display = False  # Hide my_widget

displayed_children property

displayed_children: list[Widget]

The child nodes which will be displayed.

Returns

Type	Description
list[Widget]	A list of nodes.

id property writable

id: str | None

The ID of this node, or None if the node has no ID.

is_modal property

is_modal: bool

Is the node a modal?

name property

name: str | None

The name of the node.

parent property

parent: DOMNode | None

The parent node.

All nodes have parent once added to the DOM, with the exception of the App which is the root node.

pseudo_classes property

pseudo_classes: frozenset[str]

A (frozen) set of all pseudo classes.

rich_style property

rich_style: Style

Get a Rich Style object for this DOMNode.

Returns

Type	Description
Style	A Rich style.

screen property

screen: 'Screen[object]'

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

text_style: Style

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

tree: Tree

A Rich tree to display the DOM.

Log this to visualize your app in the textual console.

Example

self.log(self.tree)

Returns

Type	Description
Tree	A Tree renderable.

visible property writable

visible: bool

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.

workers property

workers: WorkerManager

The app's worker manager. Shortcut for self.app.workers.

add_class method

def add_class(self, *class_names):

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

def get_component_styles(self, name):

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

def get_pseudo_classes(self):

Get any pseudo classes applicable to this Node, e.g. hover, focus.

Returns

Type	Description
Iterable[str]	Iterable of strings, such as a generator.

has_class method

def has_class(self, *class_names):

Check if the Node has all the given class names.

Parameters

Name	Type	Description	Default
*class_names	str	CSS class names to check.	()

Returns

Type	Description
bool	True if the node has all the given class names, otherwise False.

has_pseudo_class method

def has_pseudo_class(self, *class_names):

Check for pseudo classes (such as hover, focus etc)

Parameters

Name	Type	Description	Default
*class_names	str	The pseudo classes to check for.	()

Returns

Type	Description
bool	True if the DOM node has those pseudo classes, False if not.

notify_style_update method

def notify_style_update(self):

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

def query(self, selector=None):

Get a DOM query matching a selector.

Parameters

Name	Type	Description	Default
selector	str | type[QueryType] | None	A CSS selector or None for all nodes.	None

Returns

Type	Description
DOMQuery[Widget] | DOMQuery[QueryType]	A query object.

query_one method

def query_one(self, selector, expect_type=None):

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

def remove_class(self, *class_names):

Remove class names from this Node.

Parameters

Name	Type	Description	Default
*class_names	str	CSS class names to remove.	()

Returns

Type	Description
Self	Self.

reset_styles method

def reset_styles(self):

Reset styles back to their initial state.

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 False to suppress exceptions.	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

def set_class(self, add, *class_names):

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

def set_classes(self, classes):

Replace all classes.

Parameters

Name	Type	Description	Default
classes	str | Iterable[str]	A string containing space separated classes, or an iterable of class names.	required

Returns

Type	Description
Self	Self.

set_styles method

def set_styles(self, css=None, **update_styles):

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

def toggle_class(self, *class_names):

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

def walk_children(
    self,
    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
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

def watch(self, 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).

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

NoScreen class

Bases: DOMError

Raised when the node has no associated screen.

check_identifiers function

def check_identifiers(description, *names):

Validate identifier and raise an error if it fails.

Parameters

Name	Type	Description	Default
description	str	Description of where identifier is used for error message.	required
*names	str	Identifiers to check.	()