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.
execViewspun a nested blockinggetEventloop for every modal dialog;dragViewspun 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'swhile (!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:
| Phase | What happens |
|---|---|
| Resize | Query the terminal size; if it changed, relayout the whole tree. There is no Event::Resize; the backend is polled live. |
| Settle currency | Apply any pending insert-time focus cascades so the event about to be dispatched sees a fully settled focus state. |
| Pick an event | Drain the internal queue first, else poll the backend with the frame-tick timeout; an idle pick may synthesize a mouse auto-repeat. |
| Idle | No event: fire expired timers as Event::Timer, refresh the status line's help context. |
| Pre-route | A 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 gate | Drop the event if it is a disabled command; otherwise offer it to the capture stack, then to normal view routing. |
| Deferred drain | Apply every queued effect once, in insertion order. |
| Cursor + redraw | Set 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:
| Phase | Which views | Typical use |
|---|---|---|
PreProcess | Children with options.pre_process = true | Alt-letter accelerators (menu bar), global hot-keys |
Focused | The current child only (no option gate) | Ordinary key handling, text input |
PostProcess | Children with options.post_process = true | Plain-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 theContextinstead (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
sfCursorVisandsfCursorInsfromviews.h. TheTView::resetCursortree-walk is realized byGroup::cursor_request, andTVCursor::decideCaretSizebyView::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 assignwhat = 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:
- Fires the command-set-changed broadcast. If the enabled/disabled command
set changed since the last broadcast, a
Command::COMMAND_SET_CHANGEDbroadcast is queued so buttons and menu items can re-gray themselves. - 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. - 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 overridingTProgram::idleisProgram::set_on_idle.
Where events come from
Every event in tvision-rs enters the loop through a single acquisition path
inside pump_once:
- Internal queue first.
out_events(aVecDeque) 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. - Backend poll if the queue is empty.
renderer.backend_mut().poll_event(timeout)blocks for up totimeout(the frame-tick, typically 20 ms) and returns the next terminal event, orNoneon timeout. - Mouse-auto synthesizer. If both the queue and the backend returned
None, and a mouse button is held,MouseAutoState::synthesizemay produce a syntheticEvent::MouseAutoat 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_idleor 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_eventpops 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 virtualgetEventoverride point; the idiomatic substitutes are the timer queue,set_on_idle, and the headless event queue for tests.
Where to go next
- Deferred effects: the full effect catalogue and why each one is queued instead of applied inline.
- Cross-view brokering & ViewId: how the pump brokers reads and writes between sibling views during the drain.
- Modal execView → one loop + capture: the veteran's view of
how
execViewbecame a capture handler.