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
- Menus, status line & help: the views that emit commands and gray themselves out.
- Events → enum + match: the design behind
enum Eventand whyinfoPtrbecamesource, for Turbo Vision veterans. - The event loop in depth: how a command is routed through the tree.