Struct BoxTree 

pub struct BoxTree { /* private fields */ }

Implementations

impl BoxTree

pub fn with_backend(backend: GridF64) -> Self

pub fn element_meta(&self, id: NodeId) -> Option<ElementMeta>

pub fn set_element_meta( &mut self, id: NodeId, meta: Option<ElementMeta>, ) -> bool

pub fn element_id_of(&self, id: NodeId) -> Option<ElementId>

pub fn focus_nav_meta(&self, id: NodeId) -> Option<FocusNavMeta>

pub fn set_focus_nav_meta(&mut self, id: NodeId, focus: FocusNavMeta) -> bool

pub fn is_focusable(&self, id: NodeId) -> bool

Returns true when this node can receive focus by any means.

pub fn is_keyboard_navigable(&self, id: NodeId) -> bool

Returns true when this node participates in keyboard traversal.

pub fn set_focusable(&mut self, id: NodeId, focusable: bool) -> bool

Sets whether this node can receive focus at all.

Clearing focusability also clears keyboard navigation.

pub fn set_keyboard_navigable( &mut self, id: NodeId, keyboard_navigable: bool, ) -> bool

Sets whether this node participates in keyboard traversal.

Enabling keyboard navigation also enables focusability.

pub fn reparent(&mut self, id: NodeId, new_parent: Option<NodeId>)

pub fn remove(&mut self, id: NodeId)

Methods from Deref<Target = Tree<GridF64>>

pub fn needs_commit(&self) -> bool

Returns true if the tree has uncommitted geometry or structural changes.

When this returns true, cached world-space values (such as [Tree::world_transform] and [Tree::world_bounds]) and spatial-index-backed query results are only valid after calling [Tree::commit].

Note: not all updates require a commit. Changes to [LocalNode] flags or z_index take effect immediately and do not affect this value.

pub fn push_child(&mut self, parent: Option<NodeId>, local: LocalNode) -> NodeId

Create a node and append it as the last child of parent (or as a root if None).

The returned [NodeId] becomes live immediately, but world-space data (world_transform, world_bounds) and the spatial index are only updated on the next call to [Tree::commit].

pub fn insert_child_at( &mut self, parent: Option<NodeId>, index: usize, local: LocalNode, ) -> NodeId

Create a node and insert it at index in parent’s children (or root list if None).

In debug builds, panics if index > children.len(). The returned [NodeId] becomes live immediately, but world-space data and the spatial index are only updated on the next call to [Tree::commit].

pub fn set_children(&mut self, parent: Option<NodeId>, children: &[NodeId])

Reorder parent’s children to match the provided slice.

Only NodeIds that are current live children of parent are kept; others are ignored. Does not create or remove nodes.

pub fn remove(&mut self, id: NodeId)

Remove a node (and its subtree) from the tree.

The node becomes stale immediately, but damage and spatial index updates are finalized on the next call to [Tree::commit].

pub fn reparent(&mut self, id: NodeId, new_parent: Option<NodeId>)

Reparent id under new_parent.

This marks the subtree dirty; world-space transforms/bounds and the spatial index are updated on the next call to [Tree::commit]. The node is appended as the last child of new_parent (or as the last root if None).

pub fn set_local_transform(&mut self, id: NodeId, tf: Affine) -> bool

Update local transform.

Returns true when the local value changed. This marks the node as dirty for transform and index updates and sets [Tree::needs_commit] to true.

[Tree::commit] is what synchronizes world bounds into the spatial index. Spatial-index- backed queries continue to use the last committed index until commit runs.

pub fn set_world_position( &mut self, id: NodeId, world_pos: Option<Point>, ) -> bool

Set or clear a world-space position override for this node.

This records a world-space position target and resolves it during [Tree::commit]. At commit time, the commit traversal computes an effective local translation from the current parent world transform (including rotation/scale), while preserving the node’s authored local rotation/scale.

Why this is useful:

• Interactive updates (dragging, fixed overlays, animations) can write desired world positions in O(1), without ancestor walks per event.
• Parent transforms can change in the same frame; resolving at commit uses the final parent world transform for that frame.
• Work stays in the existing commit traversal, where world transforms/index updates already happen.

Semantics:

• Some(point): enable/update the world-position override used for committed world-space results.
• None: clear the override and return to pure local-transform positioning.
• Descendants inherit the moved world transform on commit, so children move with this node.
• [Tree::local_transform] continues to return the authored local transform; the override only affects committed world-space accessors such as [Tree::world_transform] and [Tree::world_bounds].

Calling this method is O(1); commit performs the world update.

pub fn set_local_clip(&mut self, id: NodeId, clip: Option<RoundedRect>) -> bool

Update local clip.

Returns true when the local value changed. This marks the node as dirty for clip and index updates and sets [Tree::needs_commit] to true.

[Tree::commit] is what synchronizes world bounds into the spatial index. Spatial-index- backed queries continue to use the last committed index until commit runs.

pub fn clipped_local_clip(&self, id: NodeId) -> Option<RoundedRect>

Return the node’s committed local clip after ancestor clipping, in local space.

This only reports clipping when the node defines a local_clip itself. If the node has no local clip, this returns None even when ancestors clip it.

The ancestor contribution is derived from committed world-space clip AABBs, inverse-projected into this node’s local space, then intersected with the node’s own local clip. Under non-axis-aligned transforms such as rotation or shear, this is therefore an AABB approximation of ancestor clipping in local space rather than the exact clipped shape. Rounded corners are preserved only when the corresponding corner of the local clip remains intact after that AABB intersection.

If [Tree::needs_commit] is true, this still uses the most recently committed ancestor clip and world transform data, so the result may be stale relative to current local mutations.

Returns None for stale identifiers.

pub fn set_z_index(&mut self, id: NodeId, z: i32)

Update z index.

The change takes effect immediately and does not require a [Tree::commit].

pub fn set_local_bounds(&mut self, id: NodeId, bounds: Rect) -> bool

Update local bounds.

Returns true when the local value changed. This marks the node as dirty for layout and index updates and sets [Tree::needs_commit] to true.

[Tree::commit] is what synchronizes world bounds into the spatial index. Spatial-index- backed queries continue to use the last committed index until commit runs.

pub fn set_flags(&mut self, id: NodeId, flags: NodeFlags)

Update node flags.

The change takes effect immediately and does not require a [Tree::commit].

pub fn world_transform(&self, id: NodeId) -> Option<Affine>

Return the cached world transform for a live node as of the last [Tree::commit].

The returned [Affine] maps from the node’s local coordinate space into the tree’s root/world space. Any active [Tree::set_world_position] override is reflected here after [Tree::commit]. If [Tree::needs_commit] is true, this still returns the most recently committed value, which may be stale relative to current local data. Returns None for stale identifiers.

pub fn world_bounds(&self, id: NodeId) -> Option<Rect>

Return the cached world-space axis-aligned bounding box for a live node.

This is the loose AABB computed during [Tree::commit], after applying local transforms and any active clips. It fully contains the transformed bounds but may not be tight, especially under rotation or rounded clips. This is the same AABB used for spatial indexing and rectangle queries. If [Tree::needs_commit] is true, this still returns the most recently committed value, which may be stale relative to current local data. Returns None for stale identifiers.

pub fn local_clip(&self, id: NodeId) -> Option<Option<RoundedRect>>

Return the local clip for a live node.

This is the clip set through [Tree::set_local_clip]. It does not require a [Tree::commit] to be observed here. Returns None for stale identifiers.

pub fn local_transform(&self, id: NodeId) -> Option<Affine>

Return the local transform for a live node.

This is the authored transform set through [Tree::set_local_transform]. It does not require a [Tree::commit] to be observed here, and an active [Tree::set_world_position] override does not mutate the value returned by this accessor. Returns None for stale identifiers.

pub fn local_bounds(&self, id: NodeId) -> Option<Rect>

Return the local bounds for a live node.

This is the rectangle set through [Tree::set_local_bounds]. It does not require a [Tree::commit] to be observed here. Returns None for stale identifiers.

pub fn commit(&mut self) -> Damage

Run the batched update and return coarse damage.

This recomputes world-space transforms, bounds, and clips for all live nodes reachable from roots, synchronizes their AABBs into the spatial index, and returns a [Damage] summary capturing added/removed/moved regions. Call this after mutating any LocalNode fields or tree structure before issuing queries.

Note: not all updates require a commit. Changes to [LocalNode] flags or z_index take effect immediately (they do not affect world-space data or the spatial index).

pub fn hit_test_point(&self, point: Point, filter: QueryFilter) -> Option<Hit>

Hit test a world-space point and, if any node matches, return the topmost node and its path to root as a [Hit].

• point is interpreted in world coordinates.
• Nodes must satisfy the [QueryFilter] and contain the point within their world-space bounds and clip to be eligible.
• Among candidates, z_index is compared at the lowest common ancestor branch; if tied, child index at the LCA wins (later child = higher priority); when one node is an ancestor of the other, the deeper node wins.
• If [Tree::needs_commit] is true, this still queries the most recently committed spatial index and cached world-space data, so the result may be stale relative to current local mutations.

pub fn hit_test_visual_stack( &self, point: Point, filter: QueryFilter, ) -> Vec<NodeId>

Hit test a world-space point and return the full visual hit stack.

Unlike [Tree::hit_test_point], this returns all matching nodes, not just the topmost. The result is ordered deterministically by z_index, tree depth, and [NodeId] recency tie-break (id_is_newer).

pub fn intersect_rect<'a>( &'a self, rect: Rect, filter: QueryFilter, ) -> impl Iterator<Item = NodeId> + 'a

Iterate live nodes whose world-space bounds intersect a world-space rectangle.

Edges of the rectangle and bounding boxes are included in the intersection, meaning that a rectangle and bounding box that share (part of) an edge are considered to overlap.

• rect is interpreted in world coordinates.
• Nodes must satisfy the [QueryFilter] and have a non-empty intersection between their world-space bounds and the supplied rectangle to be yielded.
• The returned [NodeId]s are in an unspecified order; no z-sorting is applied.
• If [Tree::needs_commit] is true, this still queries the most recently committed spatial index, so the result may be stale relative to current local mutations.

pub fn containing_point<'a>( &'a self, point: Point, filter: QueryFilter, ) -> impl Iterator<Item = NodeId> + 'a

Iterate live nodes whose world-space bounds contain a world-space point.

Edges of the bounding boxes are included in the contains-check, having the same semantics as [Aabb2D::contains_point][understory_index::Aabb2D::contains_point], meaning that a point exactly on the edge of a bounding box is contained by that bounding box.

• point is interpreted in world coordinates.
• Nodes must satisfy the [QueryFilter] and contain the given point to be yielded.
• The returned [NodeId]s are in an unspecified order; no z-sorting is applied.
• If [Tree::needs_commit] is true, this still queries the most recently committed spatial index, so the result may be stale relative to current local mutations.

pub fn is_alive(&self, id: NodeId) -> bool

Returns true if id refers to a live node.

A NodeId is considered live if its slot exists and its generation matches the current generation stored in that slot. See [NodeId] docs for the generational semantics.

pub fn z_index(&self, id: NodeId) -> Option<i32>

Returns the z-index of a node if the identifier is live.

pub fn parent_of(&self, id: NodeId) -> Option<NodeId>

Returns the parent of a node if live, or None for roots or stale ids.

pub fn flags(&self, id: NodeId) -> Option<NodeFlags>

Returns the flags of a node if the identifier is live.

pub fn next_depth_first(&self, current: NodeId) -> Option<NodeId>

Get the next node in depth-first traversal order.

Returns None if no next node exists or if the current node is stale. This is a standard tree traversal that does not wrap around.

pub fn prev_depth_first(&self, current: NodeId) -> Option<NodeId>

Get the previous node in reverse depth-first traversal order.

Returns None if no previous node exists or if the current node is stale. This is a standard tree traversal that does not wrap around.

pub fn children_of(&self, id: NodeId) -> &[NodeId]

Get the children of a node, or empty slice if node is stale.

Trait Implementations

impl Debug for BoxTree

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for BoxTree

fn default() -> Self

Returns the “default value” for a type.

impl Deref for BoxTree

type Target = Tree<Grid<f64>>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for BoxTree

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.