Dom node

dom

BadIdentifier

Bases: Exception

raised by check_identifiers.

DOMNode

Bases: MessagePump

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

ancestors: list[DOMNode] property

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

ancestors_with_self: list[DOMNode] property

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

Note

This is inclusive of self.

auto_refresh: float | None writable property

Interval to refresh widget, or None for no automatic refresh.

background_colors: tuple[Color, Color] property

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

children: Sequence[Widget] property

A view on to the children.

classes: frozenset[str] property

A frozenset of the current classes set on the widget.

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

The widget's foreground and background colors, and its parent's (base) colors.

css_identifier: str property

A CSS selector that identifies this DOM node.

css_identifier_styled: Text property

A stylized CSS identifier.

css_path_nodes: list[DOMNode] property

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

css_tree: Tree property

Get a Rich tree object which will recursively render the structure of the node tree, which also displays CSS and size information.

display: bool writable property

Should the DOM node be displayed?

displayed_children: list[Widget] property

The children which don't have display: none set.

id: str | None writable property

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

name: str | None property

The name of the node.

parent: DOMNode | None property

The parent node.

pseudo_classes: frozenset[str] property

A set of all pseudo classes

rich_style: Style property

Get a Rich Style object for this DOMNode.

screen: Screen property

The screen that this node is contained within.

Note

This may not be the currently active screen within the app.

text_style: 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	Rich Style object.

tree: Tree property

Get a Rich tree object which will recursively render the structure of the node tree.

visible: bool writable property

Is the DOM node visible?

add_class(*class_names)

Add class names to this Node.

Parameters:

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

compose_add_child(widget)

Add a node to children.

This is used by the compose process when it adds children. There is no need to use it directly, but you may want to override it in a subclass if you want children to be attached to a different node.

Parameters:

Name	Type	Description	Default
widget	Widget	A Widget to add.	required

get_component_styles(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()

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(*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(*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()

Called after styles are updated.

query(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. Defaults to None.	None

Returns:

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

query_one(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. Defaults to None.	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(*class_names)

Remove class names from this Node.

Parameters:

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

reset_styles()

Reset styles back to their initial state

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

set_styles(css=None, **update_styles)

Set custom styles on this object.

toggle_class(*class_names)

Toggle class names on this Node.

Parameters:

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

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
filter_type	type[WalkType] | None	Filter only this type, or None for no filter. Defaults to None.	None
with_self	bool	Also yield self in addition to descendants. Defaults to False.	False
method	WalkMethod	One of "depth" or "breadth". Defaults to "depth".	'depth'
reverse	bool	Reverse the order (bottom up). Defaults to False.	False

Returns:

Type	Description
list[DOMNode] | list[WalkType]	A list of nodes.

watch(obj, attribute_name, callback, init=True)

Watches for modifications to reactive attributes on another object.

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

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.	()

Returns:

Type	Description
None	True if the name is valid.