Struct TreeView 

pub struct TreeView<T: 'static> { /* private fields */ }

Implementations

impl<T: 'static> TreeView<T>

pub fn new( model: TreeModel<T>, delegate: impl Fn(&T, &FlatEntry, bool) -> Box<dyn Widget> + 'static, ) -> Self

Create a new TreeView backed by a TreeModel<T>.

The delegate receives (&item, &FlatEntry, selected) and returns a boxed widget. The FlatEntry provides depth, has_children, and is_expanded for rendering indentation and expand/collapse toggles.

pub fn new_with_context( model: TreeModel<T>, delegate: impl Fn(&T, &FlatEntry, bool, &TreeRowContext<'_, T>) -> Box<dyn Widget> + 'static, ) -> Self

Like new, but the delegate also receives a TreeRowContext from which .toggle_callback() can be pulled in a single line — eliminating the need to manually clone the slice handle outside the closure.

let _w = TreeView::new_with_context(model, |item, entry, selected, ctx| {
    Box::new(
        StandardTreeItem::new(lit!(&item.title))
            .from_entry(entry)
            .selected(selected)
            .on_chevron_toggle_rc(ctx.toggle_callback())
    )
});

pub fn from_source<S: TreeDataSource<Item = T>>( source: S, delegate: impl Fn(&T, &TreeRow, bool) -> Box<dyn Widget> + 'static, ) -> Self

Create a TreeView backed by any TreeDataSource — an external source of truth (e.g. an entity store) carrying its own Key, so it needs no TreeModel mirror. The delegate receives (&item, &TreeRow, selected); TreeRow exposes depth / has_children / is_expanded and a one-call chevron toggle_callback(). Drop validation + lazy windowing route through the source’s can_accept / accept_drop / row_state.

pub fn from_source_keyed<S: TreeDataSource<Item = T>>( source: S, keyed: KeyedSelectionModel<S::Key>, delegate: impl Fn(&T, &TreeRow, bool) -> Box<dyn Widget> + 'static, ) -> Self

where S::Key: ItemKey,

Like from_source but with keyed selection: the KeyedSelectionModel<S::Key> tracks selection by source identity, so it survives expand / collapse / filter / reorder and stays consistent across two views of the same source. The view stays TreeView<T> — the Key is captured here. Pruning consults the source’s contains_key, so a collapsed-but-present node keeps its selection.

pub fn enabled(self, enabled: impl Into<Prop<bool>>) -> Self

Enable or disable the whole view. A disabled view greys out and stops accepting focus / selection / keyboard input (arena-gated).

pub fn overscroll_behavior(self, behavior: OverscrollBehavior) -> Self

Set the scroll-chaining behavior at the boundary (default OverscrollBehavior::Chain; Contain disables chaining to an ancestor scrollable).

pub fn item_height(self, height: f32) -> Self

Set the fixed height per row (default 28.0) — the uniform fast path. Mutually exclusive with item_height_fn and auto_item_height; the last mode setter wins.

pub fn smooth_scrolling(self, enabled: bool) -> Self

Enable or disable animated wheel scrolling (enabled by default). When disabled, wheel events snap immediately to the new offset.

pub fn smooth_scroll_duration(self, duration: Duration) -> Self

Duration of the smooth scroll animation (default 150 ms).

pub fn scroll_signal(self, scroll: Signal<f32>) -> Self

Scroll from a signal the caller owns, so the position survives the view.

A TreeView mints its own by default, which is right for a tree whose lifetime is the writer’s: it is created once and scrolls until they leave. It is wrong for one inside a dock, whose content is torn down and rebuilt whenever the layout changes – opening a panel beside it, or the first reveal of the band a result previews into. The tree comes back at the top, and the row the writer was reading is somewhere above it.

Hold the signal wherever the model lives and the position outlives the widget, as the expand set already does.

⚠ Pass an animated signal (Signal::new_animated) unless smooth scrolling is off: the view animates this one, and a plain signal makes every wheel notch a jump.

pub fn scroll_bar_style(self, style: ScrollBarMode) -> Self

How the scroll bar is displayed (default Permanent). Overlay and Thin float the bar over the content instead of reserving a layout column for it, mirroring ScrollArea::scroll_bar_style.

pub fn item_height_fn(self, f: impl Fn(usize) -> f32 + 'static) -> Self

Per-row heights from a callback over the flat (visible) index. The callback must be pure (same index + same data → same height); it is re-swept from the first changed flat index on every model change or expand/collapse. No measurement pass runs.

pub fn auto_item_height(self, estimated: f32) -> Self

Auto-measured row heights: each realized row is measured at the tree’s content width (height-for-width), unrealized rows assume estimated. Scroll anchoring keeps content above the viewport stationary as estimates are corrected; measured heights above a toggled row survive expand/collapse (divergence-driven invalidation).

pub fn row_click_expands(self, b: bool) -> Self

Whether a row-body PointerUp on a branch row auto-toggles its expansion (default true). Set to false when the delegate provides its own chevron tap target (e.g. StandardTreeItem) — without this, the auto-toggle fires in addition to the chevron’s own click and they cancel out, leaving the row expanded only on body clicks.

pub fn selection(self, sel: SelectionModel) -> Self

Set the index-based selection model (visible positions). Unlike ListView (where every structural change carries an insert/remove DataChange the selection index-shifts against), a TreeView’s structural changes — including expand/collapse — surface only as a version bump, with no delta to shift a selected index by. The keyboard cursor tracks its row by identity (a RowAnchor), and in a single selection the view keeps the cursor on the selected row, so the selection follows that row to its new position. In a multiple selection a moved row’s old index is only clamped into range, not followed. A selected row that disappears — removed, or hidden by a collapse — leaves the selection at its clamped position in either mode. For selection that survives all of these, use keyed_selection instead.

pub fn keyed_selection(self, keyed: KeyedSelectionModel<NodeId>) -> Self

Set a keyed selection model (by NodeId). Selection is tracked by node identity, so it survives expand / collapse, filtering, and node moves — and stays consistent if two views share the model. Pruned of deleted nodes on each slice change. Mutually exclusive with selection (last one set wins).

pub fn reorderable(self, enabled: bool) -> Self

Enable intra-widget drag reordering.

When enabled, tree rows can be dragged to reparent or reorder them. Before/Into/After is chosen by where in the row the pointer drops; the move is cycle-guarded — a drop onto the node itself or into its own subtree is refused and shows no insertion line. Keyboard equivalent: Alt+ArrowUp/Down.

pub fn exportable(self, mode: DragTransferMode) -> Self

where T: Clone,

Make rows droppable outside this view — on a DropTarget, another data view, or the OS.

A dragged row (or the whole selection, when the pressed row is part of a multi-selection) carries clones of its items in a public RowDragData<T>, so a foreign receiver can pull them out with payload.get_typed::<RowDragData<T>>() / DropTarget::on_drop_typed::<RowDragData<T>>() — no serialization. This also makes rows a drag source even without reorderable.

mode chooses what happens to the origin rows once a foreign target accepts them: DragTransferMode::Move removes them (via the source’s on_drag_out, or on_rows_transferred_out), DragTransferMode::Copy leaves them. A same-view reorder is never a transfer, so mode never affects it. Requires T: Clone.

pub fn export_external( self, f: impl Fn(&[T]) -> Vec<(String, Vec<u8>)> + 'static, ) -> Self

where T: Clone,

Additionally advertise the dragged rows as MIME data so they can be dropped on a DropZone or exported to another application / window via the OS. f maps the dragged items to (mime_type, bytes) pairs (e.g. text/plain, text/uri-list, an app-specific application/x-…). Implies exportable (defaulting to DragTransferMode::Move if not already set). Requires T: Clone.

pub fn on_rows_transferred_out( self, f: impl Fn(&[usize], &mut EventContext<'_>) + 'static, ) -> Self

Override how rows moved out to a foreign target are removed from this view. Receives the dragged rows’ indices (descending-safe) and the live context. Without this, an exportable Move drag removes them through the source’s on_drag_out (works out of the box for a TreeSlice/TreeModel).

pub fn accept_foreign_rows(self, accept: bool) -> Self

Accept exported rows dropped from a different view or source without writing a custom TreeDataSource. Pair with on_rows_received, which is handed the dropped items and the insertion index. (Same-view reorder is reorderable; a custom TreeDataSource can still accept foreign drops through its can_accept/accept_drop instead.)

pub fn on_rows_received( self, f: impl Fn(Vec<T>, usize, &mut EventContext<'_>) + 'static, ) -> Self

Handler for rows accepted via accept_foreign_rows: (items, insertion_index, ctx). Insert them into your model at the index.

pub fn on_activate( self, f: impl Fn(usize, &mut EventContext<'_>) + 'static, ) -> Self

Set the row-activation handler — invoked with the flat row index on a primary click on the row body (per activate_on, which defaults to a double click), or Enter on the focused row. Activation is distinct from selection: arrow-key navigation and Space move / toggle the selection but do not activate, so a view can open/commit a row on a deliberate click/Enter without firing on every navigation step.

pub fn activate_on(self, mode: ActivateOn) -> Self

Choose single- vs double-click activation (default ActivateOn::DoubleClick — the cross-platform convention; pass SingleClick for the KDE/web/Scrivener feel). Enter activates in either mode.

pub fn row_tooltip_sticky(self, on: bool) -> Self

Whether a composite row tooltip offers dwell-to-sticky promotion. Default true.

Turn it off for a read-only row card: with nothing to reach into there is nothing to pin, so the countdown indicator would promise an interaction that does not exist and the surface would outlive the pointer for no reason.

pub fn row_tooltip( self, f: impl Fn(usize, &T) -> Option<LocalizedString> + 'static, ) -> Self

Per-row plain tooltip: one line of text for the row under the pointer.

The resolver receives the row’s flat index and its item; returning None leaves that row without a tip. Mutually exclusive with row_rich_tooltip and row_composite_tooltip — last setter wins, matching the per-widget tooltip matrix.

Opens to the row’s trailing side, never below it: rows stack vertically, so a tip below would cover the next row.

pub fn row_rich_tooltip( self, f: impl Fn(usize, &T) -> Option<RichTooltipSource> + 'static, ) -> Self

Per-row rich tooltip — a registry key or inline TooltipContent, both of which convert into RichTooltipSource. See row_tooltip for the shared semantics.

pub fn row_composite_tooltip( self, f: impl Fn(usize, &T) -> Option<Box<dyn Widget>> + 'static, ) -> Self

Per-row composite tooltip — an arbitrary widget tree describing the row.

The body is built for every realized row (the virtualization window) and rebuilt with it, so keep the resolver cheap and defer anything costly to the body’s own first paint, which only runs if the tip is actually shown. See row_tooltip for the rest.

pub fn type_ahead_label(self, label: impl Fn(&T) -> String + 'static) -> Self

Enable type-ahead (“type to jump”): typing a printable character while the tree has keyboard focus jumps the selection to the next visible row whose label starts with the accumulated search term, wrapping around (Qt keyboardSearch / macOS & Windows type-select). label(&item) yields the searchable text; matching is ASCII-case-insensitive. A pause longer than the type_ahead_timeout starts a fresh term.

pub fn type_ahead_timeout(self, timeout: Duration) -> Self

Reset window between keystrokes before the type-ahead search term clears (default 500 ms). A zero duration disables type-ahead.

pub fn expand(&self, node: NodeId)

Expand a node programmatically. No-op on the from_source path (which owns its own expand state — use the source’s set_expanded).

pub fn collapse(&self, node: NodeId)

Collapse a node programmatically. No-op on the from_source path.

pub fn toggle(&self, node: NodeId)

Toggle a node’s expand/collapse state. No-op on the from_source path.

pub fn expand_all(&self)

Expand all nodes. No-op on the from_source path.

pub fn collapse_all(&self)

Collapse all nodes. No-op on the from_source path.

pub fn tree_slice(&self) -> Option<&TreeSlice<T>>

Access the internal TreeSlice (for persistence of expand state). None on the from_source path, which has no TreeSlice (the external source owns expand state).

impl<T: 'static> TreeView<T>

pub fn handle(&self) -> TreeViewHandle

A handle that scrolls this tree once it is mounted.

Take it while describing the tree, before the view is handed to ctx.add(...); it stays attached to the view across rebuilds. See TreeViewHandle.

Trait Implementations

impl<T: 'static> Debug for TreeView<T>

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

Formats the value using the given formatter.

impl<T: 'static> Widget for TreeView<T>

fn context_menu_key_target(&self) -> Option<WidgetId>

The context-menu key opens the current row’s menu, not the tree’s.

A TreeView is focusable and its rows deliberately are not — the container owns focus and set_selected is what tells assistive technology which row is current (see list_item_a11y, which says so explicitly). So the dispatcher’s default of “the focused widget” would open the tree’s own menu, in the widget family where a per-row menu matters most.

The row the user means is the keyboard cursor if they have navigated, else the first selected row. Only realized rows have a widget, so a cursor scrolled outside the virtualization window resolves to nothing and the menu falls back to the tree — right, because there is no row on screen for it to be about.

fn build(&mut self, ctx: &mut BuildContext<'_>) -> Vec<WidgetId>

Compose child widgets. Called once after the widget is placed in the arena, and again whenever the widget is marked for rebuild — a BindingLevel::Rebuild binding, rebuild_single_widget, or a density switch. A theme or locale switch does not rebuild: set_theme and set_locale mark layout + paint dirty and leave the built subtree standing, so anything derived from the theme or the locale must be read per pass or bound to a signal rather than captured here. Takes &mut self — store child IDs, signal handles, any state needed later. Returns the list of root child IDs (empty for leaf widgets).

fn layout_response( &self, proposal: SizeProposal, _ctx: &LayoutContext<'_>, ) -> LayoutResponse

Respond to the parent’s size proposal with this widget’s wanted size, grow/shrink weights, and compression floor (see [LayoutResponse]).

fn place_children( &self, bounds: Rect, _proposal: SizeProposal, children: &mut [WidgetPlacement], _ctx: &LayoutContext<'_>, )

Position children within the allocated bounds.

fn paint(&self, bounds: Rect, canvas: &mut Canvas, ctx: &PaintContext<'_>)

Draw the widget’s visual representation.

fn accessibility(&self, builder: &mut AccessNodeBuilder)

Declare this widget’s accessibility identity.

fn as_any(&self) -> Option<&dyn Any>

Downcast hook. Default implementation returns None; concrete widgets override with Some(self) when they want to expose their concrete type to test-level introspection or reflection. The trait already bounds on std::any::Any so concrete types satisfy the 'static requirement.

fn children(&self) -> Vec<WidgetId>

Return the child widget IDs that this widget manages.

fn clips_children(&self) -> bool

Whether this widget clips its children to its bounds.

fn type_name(&self) -> &'static str

Concrete type name of this widget (e.g. "teksilo_widgets::button::Button"). The default implementation resolves at the impl site via std::any::type_name::<Self>(), so calls through &dyn Widget correctly dispatch to the monomorphized fn for the concrete type — getting the concrete name through the vtable without per-impl boilerplate.

fn cacheable_layout(&self) -> bool

Whether this widget’s layout_response may be memoized by the per-pass layout cache. Defaults to true.

fn wants_after_paint(&self) -> bool

Whether this widget wants its after_paint hook to fire each frame. Returning false (the default) saves a virtual call per widget per frame for the vast majority of widgets that don’t aggregate descendant geometry.

fn after_paint(&self, _view: &WidgetTreeView<'_>, _ctx: &PaintContext<'_>)

Called once per frame after this widget’s subtree has finished painting. Receives a read-only view of the layout-resolved arena so a parent can read its descendants’ final bounds — e.g. TitleBar aggregates its drag region and control-button rects into a single HitRegions payload for the Windows backend’s WM_NCHITTEST.

fn wants_post_paint(&self) -> bool

Whether this widget wants its post_paint hook to fire each frame. Returning false (the default) saves a virtual call per widget per frame for the vast majority of widgets that don’t draw a foreground over their children.

fn post_paint( &self, _bounds: Rect, _canvas: &mut Canvas, _ctx: &PaintContext<'_>, )

Draw a foreground layer over this widget’s children.

fn wants_descendant_redirects(&self) -> bool

Whether this widget wants the AT walker to consult its a11y_redirect_descendant hook for every descendant during AT tree emission, not just its direct arena children.

fn culls_children(&self) -> bool

Whether this widget decides, on every layout pass, which of its children exist at all.

fn a11y_redirect_descendant( &self, _self_id: WidgetId, _descendant: WidgetId, ) -> Option<NodeId>

Optional redirection hook for AT-tree placement of a child.

fn accessible_title_hint(&self) -> Option<String>

Suggest an accessible title to an enclosing container that wraps this widget as content — typically a modal / dialog shell that wants to propagate the inner content’s visible title as the shell’s own accessible name.

fn accessible_title_node(&self) -> Option<WidgetId>

The widget that paints this one’s title, when it has one.

fn initial_focus_hint(&self) -> Option<WidgetId>

Optional hint that directs initial focus to a specific descendant when this widget is the root of a deferred-built modal surface.

fn accessibility_proxy(&self) -> Option<WidgetId>

The descendant whose accessibility node stands for this widget.

fn accessibility_children(&self) -> Option<Vec<WidgetId>>

Optional override for the child ORDER presented to assistive technology, when it must differ from the paint / z-order child order returned by children.

fn as_any_mut(&mut self) -> Option<&mut (dyn Any + 'static)>

Mutable counterpart of as_any. Default returns None; widgets that want to expose mutable state to tests (e.g. so a test can mutate a Scene inside a SceneView post-layout) override with Some(self). Should follow the same opt-in pattern as as_any: only widgets that opt into & introspection should opt into &mut.

fn focus_reveal_rect(&self, _bounds: Rect) -> Option<Rect>

The rectangle (in absolute tree coordinates) that best represents this widget when the framework reveals it into an ancestor scroll area on focus gain. Returning None (the default) reveals the widget’s whole bounds — correct for most controls.

fn hit_shape(&self, _local_point: Point, _bounds: Rect) -> bool

Whether the point lies inside this widget’s actual shape, not just its rectangular bounds. Consulted by hit-testing right after the bounds check: returning false for a point that is inside the bounding box makes the widget transparent to the click there, so it falls through to whatever sibling is painted underneath (the same machinery as a fully pass-through node, but shape-aware).

fn accepts_child_hit(&self, _child: WidgetId, _point: Point) -> bool

Veto a hit on one of this widget’s direct children, per point.

fn hit_outset(&self, _kind: PointerKind, _tokens: &InputTokens) -> EdgeInsets

How far outside its own bounds this widget still absorbs a press, per edge, for the pointer that is asking.

fn hit_slop(&self, _kind: PointerKind, _tokens: &InputTokens) -> Option<HitSlop>

This widget’s own say in the miss-only slop pass, overriding the density default for its node.

fn hit_distance(&self, local_point: Point, bounds: Rect) -> Option<f32>

How far a missed press is from this widget’s actual silhouette, in the widget’s own bounds space.

fn target_regions(&self, _bounds: Rect) -> Vec<TargetRegion>

The interactive sub-regions this widget paints inside its own single node — a scroll bar’s thumb, a slider’s knob, a header cell’s filter affordance.

fn preserves_children_on_rebuild(&self) -> bool

How rebuild_single_widget treats this widget’s existing children when re-running its build().

fn tooltip_has_content(&self) -> bool

Whether this widget, used as tooltip content, currently has anything worth showing.

fn declare_shortcuts(&self) -> Vec<Shortcut>

Declare the rebindable keyboard shortcuts this widget exposes, without installing handlers. The framework calls this at arena insertion time (before build()) and at certain lazy boundaries (e.g. Switcher walks declarations on its not-yet-mounted Pending slots), so settings UIs and the ShortcutRegistry see the keystrokes the moment the owning container mounts — even if build() hasn’t run.

fn take_handler_set(&mut self) -> Option<HandlerSet>

Extract attached handler set from a WidgetWithHandlers wrapper. Called during arena insertion to transfer handlers to the WidgetNode. Default: returns None (no attached handlers).