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 event loop in depth

tvision-rs runs the entire application on one non-recursive event loop in Program. Every event (keystrokes, mouse motion, modal dialogs, window drags, mouse hold-tracking) routes through a single pass called pump_once. Modality and press-and-hold are capture handlers stacked on a LIFO capture stack (see Cross-view brokering & ViewId and the capture section below). Because the whole tree is owned behind a single &mut, exactly one thing at a time may borrow it: the single loop enforces this structurally.

Turbo Vision heritage: the C++ library had many loops. execView spun a nested blocking getEvent loop for every modal dialog; dragView spun another while you dragged a window; a pressed button spun its own while you held the mouse. Each re-entered the framework and re-borrowed the view tree, which Rust forbids. Every one of those nested loop bodies is now a capture handler.

run is the only outer loop

Program::run is the whole application loop. It pumps until something sets an end command, then asks the tree to validate that command; if it validates, return, otherwise clear it and keep pumping:

// Illustrative sketch — not a standalone program.
loop {
    self.end_state = None;
    while self.end_state.is_none() {
        self.pump_and_drive();        // one event, fully processed
    }
    let es = self.end_state.unwrap();
    if self.valid_end(es) {           // tree-wide valid() walk
        return es;
    }
}

Turbo Vision heritage: this mirrors TGroup::execute's while (!valid(endState)) pattern.

run_app is the same loop with one addition: any Command that survives all view routing is handed to your callback. That is where menu commands like "open the color picker" get serviced. Most applications call one of these two and never touch the machinery below.

One pass: pump_once

pump_once is one pass of the single loop. Each call goes once through these phases, in order:

PhaseWhat happens
ResizeQuery the terminal size; if it changed, relayout the whole tree. There is no Event::Resize; the backend is polled live.
Settle currencyApply any pending insert-time focus cascades so the event about to be dispatched sees a fully settled focus state.
Pick an eventDrain the internal queue first, else poll the backend with the frame-tick timeout; an idle pick may synthesize a mouse auto-repeat.
IdleNo event: fire expired timers as Event::Timer, refresh the status line's help context.
Pre-routeA KeyDown (always) or a MouseDown on the status line is offered to the status line first, so accelerators like F10/Alt-X fire even under a modal.
The dispatch gateDrop the event if it is a disabled command; otherwise offer it to the capture stack, then to normal view routing.
Deferred drainApply every queued effect once, in insertion order.
Cursor + redrawSet the hardware cursor, then redraw the whole tree and diff it to the screen.

The dispatch gate

Before an event reaches a view it passes a small gate. A command that is currently disabled is dropped here. tvision-rs uses a denylist, so unknown custom commands flow through untouched (see Commands & events). What survives is offered to the capture stack first; only if no handler consumes it does it go to the normal view-tree walk (program_handle_event). A modal handler that consumes every otherwise-unhandled event is the modal loop. A timer expiry skips the capture stack: C++ delivers it from idle inside the getEvent of every hold loop, so a drag or an open menu must not swallow it.

While a modal view runs, program_handle_event does not use the root route for keys, commands, pastes and the mouse wheel. It hands them to the innermost modal view alone (CaptureStack::modal_view), as C++ TGroup::execute does, and drops a command the modal leaves unhandled. The program-level steps (menu bar hot keys, Alt+1..9, the Command::QUIT catch, Tile and Cascade, run_app's callback) see none of these events. Mouse clicks and broadcasts keep the root route; broadcasts reach the whole tree.

The deferred drain

A view is borrowed downward during dispatch as &mut dyn View plus a Context; it cannot reach back up to the loop-owned capture stack, command set, or sibling views. So instead of acting inline it queues the effect, and the pump applies the whole queue in one pass after dispatch: capture pushes, command enable/disable, bounds changes, modal close, focus moves, and the cross-view broker syncs. This is the Deferred channel; it has its own page, Deferred effects. Two rules matter here: the drain runs even when the pre-route consumed the event, and it runs once: anything an effect re-queues waits for the next pump (a loop-until-empty could spin).

Because capture pushes are deferred, a freshly pushed handler sees the next event, not the one that pushed it. The push and the first handled event are always separated by at least one pump boundary.

The capture stack

The CaptureStack is the LIFO list of CaptureHandlers that implements modality, dragging, press-and-hold, and menu sessions: anything that needs to intercept events globally before normal routing. Each handler is offered every event and returns a CaptureFlow:

  • Pass: not mine; offer it to the next lower handler, then to the view tree.
  • Consumed: handled; stop routing, stay on the stack.
  • ConsumedPop: handled, and remove myself (for example a modal closing).

The return value is authoritative. Handlers do not signal "consumed" by clearing the event. A handler holds a ViewId, never a view reference. Concrete handlers include a bounds-gating modal frame, window dragging and keyboard resize, mouse hold-tracking, and the menu session. Before every dispatch the pump re-syncs each bounds-gating handler from the live tree (sync_gate_bounds), so a dialog you have just dragged stays clickable in its new position.

The Phase field

A focused-event dispatch (a KeyDown or Command) visits three legs of the view tree in order: the pre-process children, the focused child, then the post-process children. A view that participates in more than one leg, or needs to know which leg it is on, reads ctx.phase().

The three values of Phase:

PhaseWhich viewsTypical use
PreProcessChildren with options.pre_process = trueAlt-letter accelerators (menu bar), global hot-keys
FocusedThe current child only (no option gate)Ordinary key handling, text input
PostProcessChildren with options.post_process = truePlain-letter hot-keys on buttons, check-boxes, labels

The group sets the phase on the shared Context before each leg and restores the previous value after it, so a nested group that re-enters the three-phase router always sees its own legs and never the outer group's:

// Sketch of what Group::handle_event does for focused events
// (src/view/group.rs — the three-phase router body).
ctx.set_phase(Phase::PreProcess);
for child in pre_process_children { child.handle_event(ev, ctx); }

ctx.set_phase(Phase::Focused);
current_child.handle_event(ev, ctx);

ctx.set_phase(Phase::PostProcess);
for child in post_process_children { child.handle_event(ev, ctx); }

ctx.set_phase(saved);   // restore for the outer group

A leaf handler reads the phase to decide whether to act:

#![allow(unused)]
fn main() {
use tvision_rs as tv;
use tv::event::Event;
use tv::view::{Phase, View, ViewState, Context, DrawCtx};
struct MyButton { state: ViewState }
impl View for MyButton {
    fn state(&self) -> &ViewState { &self.state }
    fn state_mut(&mut self) -> &mut ViewState { &mut self.state }
    fn draw(&mut self, _ctx: &mut DrawCtx) {}
fn handle_event(&mut self, ev: &mut Event, ctx: &mut Context) {
    if let Event::KeyDown(k) = ev {
        match ctx.phase() {
            Phase::PreProcess => {
                // Alt-letter accelerator: fires before the focused view sees it.
                if tv::is_alt_hotkey(k, 'O') { ev.clear(); /* open */ }
            }
            Phase::Focused => {
                // Focused key: Enter / Escape handled here.
                if k.key == tv::Key::Enter { ev.clear(); }
            }
            Phase::PostProcess => {
                // Plain-letter hot-key: fires after the focused view.
                if tv::is_plain_hotkey(k, 'O') { ev.clear(); }
            }
        }
    }
}
}
}

Sources: Phase in src/view/view.rs; Context::phase / set_phase in src/view/context.rs; the router body in src/view/group.rs.

Turbo Vision heritage: ports phaseType (views.h). In the C++ code the phase was an owner field (owner->phase); because tvision-rs views have no up-pointer the phase rides the Context instead (deviation D4).

Cursor shape: insert vs overwrite

When a view wants to show a hardware cursor it sets State::cursor_vis (via ViewState::show_cursor) and also sets the cursor shape: the normal caret for the insertion point (normal_cursor, the default) or a block for overwrite mode (block_cursor), controlled by State::cursor_ins.

#![allow(unused)]
fn main() {
use tvision_rs as tv;
use tv::view::{View, ViewState, Context, DrawCtx};
use tv::event::Event;
struct MyEditor { state: ViewState, insert_mode: bool }
impl View for MyEditor {
    fn state(&self) -> &ViewState { &self.state }
    fn state_mut(&mut self) -> &mut ViewState { &mut self.state }
    fn draw(&mut self, _ctx: &mut DrawCtx) {}
fn handle_event(&mut self, ev: &mut Event, ctx: &mut Context) {
    if let Event::KeyDown(k) = ev {
        if k.key == tv::Key::Insert {
            self.insert_mode = !self.insert_mode;
            if self.insert_mode {
                self.state.normal_cursor();   // normal caret = insert point
            } else {
                self.state.block_cursor();    // block = overwrite
            }
            ev.clear();
        }
    }
}
}
}

After each pump_once the event loop walks the current-child chain from the root group downward via Group::cursor_request to find the deepest focused view that has cursor_vis = true. The result (or None if no view wants a cursor) is placed on the renderer before the redraw step:

// src/app/program.rs — end of pump_once
let cursor = group.cursor_request()   // descends through current children
    .filter(|p| root_extent.contains(*p)) // hidden past the screen edge
    .map(|p| p + group_origin)
    .map(|p| (p.x.max(0) as u16, p.y.max(0) as u16));
renderer.set_cursor(cursor);
renderer.set_caret_size(group.caret_size()); // same chain: block or normal
renderer.render(|buf| { /* whole-tree redraw */ });

View::caret_size follows the same current-child chain and reads cursor_ins on the focused view: CARET_INSERT (100, a block) when it is set, else CARET_NORMAL (1). While the cursor is shown, the renderer passes this size to Backend::set_caret_size. The crossterm backend shows CARET_INSERT as a blinking block and keeps the terminal's own caret shape for CARET_NORMAL, as the original's ncurses display does. It restores the terminal's caret shape on exit and suspend.

A view that wants no cursor leaves cursor_vis = false; it never calls show_cursor. A view that loses focus keeps whatever cursor_vis value it had, but the walk only descends through focused children, so the cursor is hidden until the view is focused again.

The walk also clips the cursor, as C++ TVCursor does. Each group on the chain returns None when it or its current child is hidden, when the cursor lies outside the child's extent, or when a visible sibling above the child in Z-order covers the cursor cell. So the cursor disappears when it is scrolled out of its field, when it is outside the window that holds it, past the screen edge, or under another window.

Sources: State::cursor_ins / block_cursor / normal_cursor / View::caret_size in src/view/view.rs; Group::cursor_request / Group::caret_size in src/view/group.rs; resetCursor walk in src/app/program.rs.

Turbo Vision heritage: ports sfCursorVis and sfCursorIns from views.h. The TView::resetCursor tree-walk is realized by Group::cursor_request, and TVCursor::decideCaretSize by View::caret_size.

Marking an event handled

A handler signals "I consumed this event, stop routing" by calling ev.clear() on the &mut Event it received. clear() sets the event to Event::Nothing, the consumed-event sentinel. Every subsequent routing step first tests ev.is_nothing() and skips the delivery if true, so no further handler sees it.

#![allow(unused)]
fn main() {
use tvision_rs as tv;
use tv::event::Event;
use tv::view::{View, ViewState, Context, DrawCtx};
struct MyView { state: ViewState }
impl View for MyView {
    fn state(&self) -> &ViewState { &self.state }
    fn state_mut(&mut self) -> &mut ViewState { &mut self.state }
    fn draw(&mut self, _ctx: &mut DrawCtx) {}
fn handle_event(&mut self, ev: &mut Event, ctx: &mut Context) {
    match ev {
        Event::Command(cmd) if *cmd == tv::command::Command::OK => {
            // Handle it, then consume so no other handler sees it.
            ev.clear();
        }
        _ => {}   // unhandled — leave ev alone; it will propagate
    }
}
}
}

"Who handled it" is recorded in-place on the event. There is no shared flag and no out-of-band consumed signal. After routing returns to the caller, an ev.is_nothing() test tells the caller whether anything consumed the event.

Sources: Event::clear / Event::is_nothing / Event::Nothing in src/event/mod.rs.

Turbo Vision heritage: ports clearEvent (views.h). The C++ convention was to assign what = evNothing; ev.clear() is the idiomatic Rust spelling of the same thing.

Background work each idle pass

An idle pass is a pump_once call where the backend returned no event and no mouse auto-repeat was due: the None => arm in the event-pick step. Idle passes occur at the frame-tick cadence (roughly 20 ms) whenever the user is not typing or moving the mouse.

On an idle pass the pump does three things before falling through to the normal redraw:

  1. Fires the command-set-changed broadcast. If the enabled/disabled command set changed since the last broadcast, a Command::COMMAND_SET_CHANGED broadcast is queued so buttons and menu items can re-gray themselves.
  2. Drains expired timers. Each timer whose deadline has passed is collected and queued as a typed Event::Timer(id). A view matches the id against its own timer handles to know which timer fired.
  3. Refreshes the status line. The status line gets the current help context, so it can show the items for that context. The help context comes from the open menu, if a menu is open. Otherwise it comes from the topmost modal view. With no modal view open, it comes from the application root, which follows the focus chain down to the focused view.

After pump_once returns, the outer pump_and_drive fires the optional idle hook registered with Program::set_on_idle:

#![allow(unused)]
fn main() {
use tvision_rs as tv;
fn _demo(program: &mut tv::app::Program, rx: std::sync::mpsc::Receiver<String>) {
let refresh = tv::Command::custom("myapp.refresh");
program.set_on_idle(move |p| {
    // Called on every idle pass — roughly every 20 ms with no user input.
    // Keep this callback cheap: it runs on the loop's frame cadence.
    let mut got_data = false;
    while let Ok(_line) = rx.try_recv() {
        // ... store the line in state the views share ...
        got_data = true;
    }
    if got_data {
        p.broadcast(refresh, None); // only when there is something new
    }
});
}
}

The hook gets &mut Program. To reach the views it queues events: Program::broadcast(command, source) queues a broadcast, and Program::put_event(ev) queues any event. The hook does not dispatch them itself. The next pump pass takes the queued event before it polls the backend, and routes it like an input event. In C++, idle() sends its broadcasts at once with message(); here they arrive one pump pass later.

Only one idle hook is held at a time; a second set_on_idle call replaces the first. The hook fires during any loop level, including while a modal dialog is open, because pump_and_drive drives both the outer and inner (exec_view) loops.

For exact timing, meaning actions that must fire at a specific wall-clock instant, register a timer with Context::set_timer instead. The timer expires at the exact deadline and arrives as Event::Timer on an idle pass.

Sources: the None => arm of pump_once and Program::set_on_idle in src/app/program.rs.

Turbo Vision heritage: idle-pass logic ports TProgram::idle (tprogram.cpp). The idiomatic successor to overriding TProgram::idle is Program::set_on_idle.

Where events come from

Every event in tvision-rs enters the loop through a single acquisition path inside pump_once:

  1. Internal queue first. out_events (a VecDeque) is drained before polling the backend. Timer expirations, command re-posts, and events injected by capture handlers or deferred effects all land here and are processed in first-in-first-out order on the next pump passes.
  2. Backend poll if the queue is empty. renderer.backend_mut().poll_event(timeout) blocks for up to timeout (the frame-tick, typically 20 ms) and returns the next terminal event, or None on timeout.
  3. Mouse-auto synthesizer. If both the queue and the backend returned None, and a mouse button is held, MouseAutoState::synthesize may produce a synthetic Event::MouseAuto at the configured repeat cadence.
// src/app/program.rs — the event-pick step (pump_once, step 3)
let ev = match out_events.pop_front() {
    Some(e) => Some(e),
    None    => renderer.backend_mut().poll_event(timeout),
};
let ev = match ev {
    Some(e) => { mouse_auto.observe(&e, now); Some(e) }
    None    => mouse_auto.synthesize(now),
};

There is no app-level override of this path. Instead:

  • Periodic work: set_on_idle or a timer (Context::set_timer).
  • Inject an event programmatically: push to the internal queue (out_events.push_back(ev)) from a deferred effect or from top-level code.
  • Deterministic test events: push events to the HeadlessBackend's queue; poll_event pops them without blocking.

Sources: pump_once (the event-pick and mouse-auto steps) in src/app/program.rs.

Turbo Vision heritage: ports the role of TProgram::getEvent (tprogram.cpp). There is no virtual getEvent override point; the idiomatic substitutes are the timer queue, set_on_idle, and the headless event queue for tests.

Where to go next