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

Commands & events

The things that happen in your app (clicking OK, choosing a menu item, a scrollbar moving) travel through the view tree as commands and events. A button does not call a function directly. It emits a command, and some view up the tree decides what to do with it. Because of this indirection the same Command::OK can come from a button, a menu, or a keystroke and be handled in exactly one place.

Commands

A Command is an opaque token naming an intent. The framework ships a standard vocabulary as associated constants: Command::OK, Command::CANCEL, Command::QUIT, Command::CLOSE, and so on. A command's identity is a namespaced &'static str (so Command::OK is "tv.ok"), which keeps app- and view-defined commands from colliding (the standard names map one-to-one onto the C++ cm* constants). Mint your own with Command::custom, under a dotted prefix of your own:

#![allow(unused)]
fn main() {
use tvision_rs as tv;
const REFRESH: tv::Command = tv::Command::custom("myapp.refresh");
}

Commands reach the tree as events. A view emits one through its Context:

#![allow(unused)]
fn main() {
use tvision_rs as tv;
const REFRESH: tv::Command = tv::Command::custom("myapp.refresh");
fn _demo(ctx: &mut tv::Context) {
// a targeted command, like cmXxx — handled by one view up the tree
ctx.post(REFRESH);
}
}

The command then rides the event loop as an Event::Command, is offered to views in turn, and the first one to recognise it consumes it. (How the loop walks the tree is the subject of The event loop in depth.)

Enabling & graying out

Every command is enabled by default. To make a command unavailable, which grays out the menu items and buttons that emit it, disable it. When you hold the top-level handle (an app main, startup, a test), call Program::disable_command / enable_command. From inside a view, where you only have a downward-borrowed Context, request it deferred via ctx.disable_command(cmd) / ctx.enable_command(cmd). A view can ask whether a command is currently live with ctx.command_enabled(cmd), which answers from a per-pump snapshot.

#![allow(unused)]
fn main() {
use tvision_rs as tv;
fn _demo(app: &mut tv::Program) {
app.disable_command(tv::Command::SAVE);   // Save menu item / button grays out
// ...later, once there is something to save:
app.enable_command(tv::Command::SAVE);
}
}

Internally Program stores the disabled set (a denylist), so a brand-new custom command is enabled the moment it exists, with no registration step. Five window commands (ZOOM, CLOSE, RESIZE, NEXT, PREV) start disabled and are granted only while a window is selected. The disabled command set is a CommandSet, a set of commands with += / -= / union / intersection operators (the successor to C++ TCommandSet).

When the enabled set changes, the framework broadcasts Command::COMMAND_SET_CHANGED once on the next idle so menus, buttons and the status line re-evaluate which of their commands are live and redraw themselves grayed or active.

Broadcasts

A targeted command goes to whoever handles it; a broadcast is offered to every interested view. Sibling views coordinate through broadcasts: a scrollbar tells its scroller it moved, a list tells its dialog an item was chosen. Emit one through the context:

#![allow(unused)]
fn main() {
use tvision_rs as tv;
fn _demo(ctx: &mut tv::Context, my_id: tv::ViewId) {
ctx.broadcast(tv::Command::SCROLL_BAR_CHANGED, Some(my_id));
}
}

A broadcast is an Event::Broadcast { command, source }. The source is an optional ViewId naming which view the broadcast is about. It is the resolvable successor to C++'s infoPtr void-pointer, and a receiver uses it as a filter: it checks "is this broadcast from the scrollbar I care about?" and ignores the rest. It carries no payload. None means the broadcast concerns no particular view. List find-mode uses the same pattern: a list box broadcasts Command::LIST_FIND_CHANGED with its own ViewId as source whenever the typed query changes, so a host can mirror the query or kick off an async search. Because a leaf view cannot reach across the tree to its sibling, the event loop itself brokers the read/write between the two views when it applies the broadcast; see Cross-view brokering & ViewId.

Where to go next