Skip to content

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.