Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Cross-view brokering & ViewId

A scroller needs to know how far its scrollbars have moved; a list box needs to push its position back into them. In tvision-rs, ownership is a downward tree of Box<dyn View>, and every up- or sideways link is a handle, a ViewId, in place of a raw pointer. The event loop resolves handles and performs the actual cross-view reads and writes at a safe point when no other borrow is active. See Pointers & infoPtr → handles for the broader handle design.

Turbo Vision heritage: in C++ the two views held raw TView* pointers at each other and called across directly. Rust forbids that aliased mutable access; the broker pattern replaces it.

ViewId as identity

A ViewId is a Copy, globally-unique identity: internally one NonZeroU64, minted from a single monotonic process counter when a view is inserted into its group (Group::insert), and stamped into the view's own ViewState. It is not an index into any store. You can stash it freely (in a sibling link, a focus stack, a capture handler) because it borrows nothing. Use Option<ViewId> for "no link"; the NonZeroU64 gives that a free niche, so it costs no extra size.

Resolving a handle back to the live view is a tree-walk: View::find_mut(id) recurses through the groups and hands back a &mut dyn View, or None. A handle whose view has since been removed resolves to None. There is no dangling slot to alias, so no generational validation is needed.

Why a leaf can't reach its sibling

During event handling a leaf view holds only &mut Context (the downward borrow). It cannot reach back up to its parent group, let alone sideways to a sibling: the borrow checker would be holding two &mut into the same tree. So a scroller that wants to read its scrollbars, or write new parameters into them, has no inline way to do it.

The pump is the broker

The leaf does not act directly. It requests the cross-view read or write as a deferred effect, and the event loop, which owns the whole tree, performs it at deferred-apply time, when the entire tree is reachable through the root group. The pump is the broker.

The pattern is the same each time: resolve each participant in its own find_mut, so only one &mut is live at a time, then either call through the View trait (virtual dispatch) or downcast to the concrete type via as_any_mut() depending on what the effect needs.

// Illustrative sketch — not a standalone program.
// At deferred-apply, inside the pump, `group` is the whole tree:
let hv = h_bar_id
    .and_then(|id| group.find_mut(id))   // resolve one bar
    .and_then(|view| view.value())       // read its value via the value protocol
    .and_then(field_int);                // -> Option<i32>
// ...read the v-bar the same way, then call the target through the View trait:
if let Some(view) = group.find_mut(target) {
    view.apply_scroll_sync(hv, vv, &mut ctx);  // virtual dispatch — no downcast
}

Reads cross the seam through the value protocol (View::value() → FieldValue::Int), so the broker never needs to know the sibling's concrete type to read a number. Writes use a defaulted View trait method when the effect can be expressed generically. The callee overrides what it needs without the pump knowing the concrete type.

The scroll-family read-syncs (Scroller, all list-viewer variants, Outline viewer, and Editor) share a single hook View::apply_scroll_sync(h, v, ctx) and a single deferred variant Deferred::ScrollSync { target, h, v }. Each widget overrides apply_scroll_sync to interpret the Option<i32> deltas per its own semantics (Scroller and Outline use unwrap_or(0); Editor preserves None to skip an axis). For composite widgets such as the text editor, the #[delegate(to = field)] macro forwards apply_scroll_sync to the inner view automatically, so the pump calls it without knowing the wrapper.

Two further syncs, Deferred::IndicatorSetValue and Deferred::PageStackSync, are also downcast-free but keep their own hooks (View::set_indicator_value and View::apply_page_sync) because their payloads are not scroll deltas and the shared (h, v) hook would not fit (§2.1).

A downcast (as_any_mut() + downcast_mut) is used only where the effect requires the concrete struct and no trait hook fits: ScrollBarSetParams (the write direction, scroller → ScrollBar) and SplitterDivider (Splitter's divider-move op). These remain as downcast sites by design.

Each cross-view interaction is its own deferred variant (ScrollSync, ScrollBarSetParams, IndicatorSetValue, PageStackSync, and so on), so adding a new brokered relationship means adding a variant instead of threading a new pointer.

Avoiding feedback loops

A read-sync that writes back (the list viewer pushes its new position into the v-bar) could re-enter forever. It does not, because the scrollbar's parameter setter, ScrollBar::set_params, is change-guarded: it re-broadcasts cmScrollBarChanged only when the value actually changes. Writing back the value the bar already holds is a silent no-op, and the cycle goes quiet on the next pump.

Broadcast as a message

Beyond the scroller/list synchronization use-case, broadcasts are the general "shout to the tree" primitive in tvision-rs. Any view can post a broadcast via Context::broadcast(command, source) and any other view can handle it. The canonical pattern has two flavors:

1. "Who handled this?" probe: a broadcast where the sender watches whether any recipient clears the event. The scroller itself uses this: it does not clear cmScrollBarChanged on receipt (it returns at once); the broadcast propagates to every child in the group. Another common probe is cmCommandSetChanged: the status line and menu bar handle it to regray their items without any explicit callback.

2. "Find topmost of type": a broadcast cleared by the first handler that matches some condition. Because broadcasts are delivered top-to-bottom (frontmost child first), the highest Z-order handler wins:

// Post a broadcast; clear it in the handler that claims it:
ctx.broadcast(Command::MY_QUERY, None);

// In a view's handle_event:
if let Event::Broadcast { command, .. } = ev {
    if *command == Command::MY_QUERY {
        // Handle, then consume so lower views don't see it.
        ev.clear();
    }
}

Because "consumed" in tvision-rs means Event::Nothing (clearing the event in place, no return value), there is no separate "handled" flag to check. If the event is still live after the delivery, it was not handled by any child.

A broadcast also carries an optional source: Option<ViewId>, which names the subject of the broadcast. The sender is not recorded there. The scrollbar sets itself as source when it broadcasts cmScrollBarChanged; a scroller with two bars uses source to tell which bar fired without downcasting.

The "find the right one" idiom uses this filtering:

// Inside a view that reacts to its own scrollbar and ignores the other:
if let Event::Broadcast { command, source }  = ev {
    if *command == Command::SCROLL_BAR_CHANGED && *source == Some(self.v_scroll_bar_id) {
        // This is our bar — handle the scroll.
        // Do NOT clear — broadcasts are conventionally left live.
    }
}

Leaving the broadcast live is deliberate. Several handlers can react to one broadcast, and the loop delivers it to every child. A handler that does clear a broadcast uses it as a "claim" signal. Both patterns are valid; the convention for pure-notification broadcasts is to leave them live.

Source: src/view/context.rs (Context::broadcast), src/view/group.rs (broadcast arm of route_event).