Menus, status line & help
The top menu bar, the bottom status line, and the context-sensitive
help that ties them together are the chrome of every Turbo Vision program. In
tvision-rs all three are data trees you describe with fluent builders, then hand
to a view. The data lives in tv::menu and
tv::status; the help context is
HelpCtx.
The menu bar
A menu is a Menu: an ordered list of
entries plus a default selection. You rarely build one by hand; instead you chain
a MenuBuilder, a fluent
builder where each call appends one
MenuItem and returns self
(the idiomatic successor to C++'s operator+ chains):
let menu = Menu::builder()
.submenu("~F~ile", alt('f'), |m| {
m.command_key("~O~pen…", CMD_OPEN, KeyEvent::from(Key::F(3)), "F3")
.command_key("~N~ew", CMD_NEW, KeyEvent::from(Key::F(4)), "F4")
.separator()
.command_key("E~x~it", Command::QUIT, alt('x'), "Alt-X")
})
.submenu("~W~indow", alt('w'), |m| {
m.command("~T~ile", Command::TILE)
.command("C~a~scade", Command::CASCADE)
})
.build();
Notes on the example:
~-marked labels. The tildes bracket the hot-letter ("~F~ile"highlights theF). Submenus take analt()accelerator, a convenience that builds anAlt+<char>key.- Three entry kinds.
command/command_keyappend aMenuItem::Command(the latter adds an accelerator key plus the shortcut text shown at the right, like"F3");submenuappends a nested menu;separatorappends a divider. - A menu is data. Choosing an item emits its
Commandas an event; the menu never does anything itself. See Commands & events for how that command reaches a handler, and for how a greyed-out (disabled) item is driven by command enable/disable state.
Turbo Vision heritage:
command/command_key,submenu, andseparatormap one-to-one onto C++TMenuItem,TSubMenu, andnewLine(); the~-marked hot-letters andalt()accelerators mirror the C++"~F~ile"label convention andkbAltFliterals.
Wrap the finished Menu in a
MenuBar and return it from
your init_menu_bar factory. F10 enters the bar; the Alt accelerators open
submenus directly. When a window is in Fullscreen::Screen mode the framework
calls MenuBar::set_collapsed(true), which replaces the full bar with a [⋮]
kebab at the top-right corner; pressing F10 (or clicking the kebab) opens the
full menu as a corner popup. With the File menu pulled down it looks like this:
File Edit Window ┌─────────────┐ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │ Open… F3 │ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │ New F4 │ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │ Recent ► │ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ├ ┌────────────┐ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │ │ report.txt │ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ └ │ budget.csv │ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ░░ │ notes.md │ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ░░ └────────────┘ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ F10 Menu Alt-X Exit
The complete factory is in
examples/hello.rs
(see Your first app); the runnable menu/status
sources are the menubar and statusline entries in the
widget gallery.
The status line
A status line is a Vec<StatusDef>:
a list of definitions, each owning a list of
StatusItems, built with
StatusDef::list():
let defs = StatusDef::list()
.def_all(|d| {
d.item("~F3~ Open", KeyEvent::from(Key::F(3)), CMD_OPEN)
.item("~F10~ Menu", KeyEvent::from(Key::F(10)), Command::MENU)
.item("~Alt-X~ Exit", alt('x'), Command::QUIT)
})
.build();
Each item carries display text, an optional accelerator key, and a command;
clicking the label or pressing the key fires that command. Hand the defs to a
StatusLine and
return it from your init_status_line factory.
A hidden hotkey binding is an item with no text, built with the key_item builder
method. It draws nothing and consumes no width, but its accelerator still fires
globally. This is the standard trick for app-wide shortcuts like Shift-Del ⇒ Cut
(the C++ equivalent was TStatusItem(0, key, cmd)).
Context-sensitive help
This is what a multiple-StatusDef list is for. Each def carries a
HelpCtxRange; the status line
shows the items of the first def whose range matches the current help
context. Most apps need only one universal def, which is what def_all
(HelpCtxRange::All) builds, but
you can register a def_one_of(...) whose items appear only while a particular
context is active, so the bottom line changes as focus moves between an editor, a
browser, and so on.
The current context is a HelpCtx.
A help context is a namespaced &'static str
(HelpCtx::custom("myapp.editor")), so app- and view-defined contexts can never
collide. Because string identity carries no ordering, context ranges are expressed
as the two-variant HelpCtxRange above: All, or an explicit OneOf membership
set. Menu items also carry a help_ctx, so the same identity threads through the
whole UI.
Turbo Vision heritage: the C++
HelpCtxwas a hand-assignedint, and ranges were[min, max]numeric intervals. tvision-rs replaces the integer with a&'static strkey and the numeric range withHelpCtxRange.
Context-sensitive hints
Beyond switching which status-line items appear, the status line can show a
free-form hint string to the right of the items: a short message that
changes as the focused view changes context. This is the hint provider.
By default no hint is shown (None). Install one with
StatusLine::with_hint
(builder) or
StatusLine::set_hint
(post-construction). The provider is a closure Fn(HelpCtx) -> Option<String>;
it receives the current help context and returns the text to show (or None
to show nothing):
#![allow(unused)]
fn main() {
use tvision_rs as tv;
use tv::help::HelpCtx;
use tv::status::{StatusDef, StatusLine};
use tv::Rect;
#[allow(unused_variables)]
fn _demo() {
let defs = StatusDef::list()
.def_all(|d| d)
.build();
let line = StatusLine::new(Rect::new(0, 23, 80, 24), defs)
.with_hint(|ctx| match ctx {
c if c == HelpCtx::custom("myapp.editor") =>
Some("F2 Save F3 Open Ctrl-F Find".to_string()),
c if c == HelpCtx::custom("myapp.browser") =>
Some("Enter Select Esc Back F5 Refresh".to_string()),
_ => None,
});
let _ = line;
}
}
The Program idle loop reads the focused view's help_ctx from its ViewState
and calls StatusLine::set_help_ctx at the start of each pump, so the hint
updates as the user moves focus. The status line re-draws itself
when the context changes (it skips the redraw if the context has not changed,
making it idempotent).
Combining defs with hints: the two mechanisms are independent. Defs swap the
entire item list; the hint overlays a text string at the right end of the line.
Use def_one_of when you want different command buttons per context; use
with_hint for a short advisory string that supplements a shared button set.
Source: src/status/status_line.rs (StatusLine::set_hint, StatusLine::with_hint,
StatusLine::set_help_ctx), src/status/mod.rs (HelpCtxRange, StatusDef).
See also
- Your first app: the menu bar and status line wired into a running program.
- Commands & events: how a chosen item's command is dispatched, and how disabled items track command state.
- Keyboard & key mapping: accelerators and the global key model.