textual.walk

Functions for walking the DOM.

Note

For most purposes you would be better off using query, which uses these functions internally.

walk_breadth_first ¶

walk_breadth_first(
    root, filter_type=None, *, with_root=True
)

Walk the tree breadth first (children first).

Note

Avoid changing the DOM (mounting, removing etc.) while iterating with this function. Consider walk_children which doesn't have this limitation.

Parameters:

Name	Type	Description	Default
`root`	`DOMNode`	The root note (starting point).	required
`filter_type`	`type[WalkType] \| None`	Optional DOMNode subclass to filter by, or `None` for no filter.	`None`
`with_root`	`bool`	Include the root in the walk.	`True`

Returns:

Type	Description
`Iterable[DOMNode] \| Iterable[WalkType]`	An iterable of DOMNodes, or the type specified in `filter_type`.

walk_breadth_search_id(root, node_id, *, with_root=True)

Special case to walk breadth first searching for a node with a given id.

This is more efficient than walk_breadth_first for this special case, as it can use an index.

Parameters:

Name	Type	Description	Default
`root`	`DOMNode`	The root node (starting point).	required
`node_id`	`str`	Node id to search for.	required
`with_root`	`bool`	Consider the root node? If the root has the node id, then return it.	`True`

Returns:

Type	Description
`DOMNode \| None`	A DOMNode if a node was found, otherwise `None`.

walk_depth_first(root, filter_type=None, *, with_root=True)

Walk the tree depth first (parents first).

Note

Avoid changing the DOM (mounting, removing etc.) while iterating with this function. Consider walk_children which doesn't have this limitation.

Parameters:

Name	Type	Description	Default
`root`	`DOMNode`	The root note (starting point).	required
`filter_type`	`type[WalkType] \| None`	Optional DOMNode subclass to filter by, or `None` for no filter.	`None`
`with_root`	`bool`	Include the root in the walk.	`True`

Returns:

Type	Description
`Iterable[DOMNode] \| Iterable[WalkType]`	An iterable of DOMNodes, or the type specified in `filter_type`.

walk_selectable_widgets(root, bounds, bounded)

Walk the tree depth first in select order (top to bottom, then left to right).

Parameters:

Name	Type	Description	Default
`root`	`DOMNode`	The root note (starting point).	required
`bounds`	`Shape`	A Shape object that defines the selection bounds.	required
`bounded`	`set[DOMNode]`	Container widgets that require a bounds check.	required

Returns:

Type	Description
`Iterable[Widget]`	An iterable of DOMNodes.