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

The Deferred channel

In C++ Turbo Vision a view acts on anything at any time. While handling an event it can call endModal up its owner chain, enableCommand on the application, close() on itself, or reach across to a sibling scrollbar, all inline, because every object holds raw pointers to everything around it.

A Rust port cannot work that way, and this constraint shapes one of the framework's central seams.

Why a leaf can't act directly

While tvision-rs dispatches an event, the view tree is a live &mut borrow stack: root → desktop → window → frame → the focused control. Each ancestor is already borrowed mutably above the view on the stack. So the view being handled cannot reach up (its parents are borrowed) or sideways (a fresh root.find_mut(id) would alias a borrow already held higher up). It also does not hold the loop-owned state a C++ view could reach: the capture stack that drives modal dialogs, or the program's command set.

The view therefore does not act immediately. It records a request, and the event loop carries it out after dispatch unwinds and the tree is free again. That request is one variant of Deferred.

The shape of it

A view never constructs a Deferred itself. It calls a method on the Context it was handed (the downward context from pointers → handles, where there are no up-pointers), and that method pushes the variant onto a single queue. The loop drains the queue once per pump, in insertion order, and applies each effect against the state it owns.

#![allow(unused)]
fn main() {
use tvision_rs as tv;
fn _demo(ctx: &mut tv::Context, id: tv::ViewId) {
// inside a view's handle_event: "close me" — recorded, not performed.
ctx.request_close(id);
}
}

Each variant names an effect on loop-owned state that the view could not perform inline. They fall into four disjoint families by what they touch:

FamilyEffectsC++ equivalent
Capture stackpush a capture handler (drives modal input)TGroup mouse capture
Command setenable / disable a commandenableCommand / disableCommand
View treechange bounds, set a state flag, close, focus, sync scrollbars, launch a view-triggered modal (OpenModal)setState, close, sibling pointers, execView from a view
Loop stateend the (modal) loop with a commandendModal

Because the families are disjoint, the order in which the loop applies effects across families never changes the result; effects within one family keep the order in which they were requested.

Why this shape

The alternative, giving every view a back-reference to the program, is the raw-pointer aliasing the port set out to remove. Deferring satisfies the borrow checker and keeps the rule short: a view describes what it wants; the one place that owns the tree decides when and how. A new capability costs a new variant, not a new parameter threaded through every view.

A deferred effect lands after the current event finishes. A pushed capture handler, for instance, sees the next event, never the one being handled. Other parts of the framework depend on this timing.

Going deeper

This page covers the reasons. For the mechanics (how the loop drains the queue, how the cross-view broker resolves sibling scrollbars, and how to add a new effect) see Deferred effects and The event loop in depth.