Common app patterns
Short answers to questions that come up when a first real application is built on tvision-rs. Each section links to the page or API entry with the full story.
Is my view the one receiving keys?
A view receives keyboard input when it is focused:
State::focused
is true when the view is the current (selected) child of its owner and every
owner up to the root is focused too. Group::set_state sends the Focused flag
down the chain of current children only, so in a window with two list panes
exactly one of them has focused == true. While a modal dialog is open, the
dialog is the current child of the root, so every view on the desktop reads
focused == false.
To show which pane is active, read the flag in draw; there is nothing to track
yourself:
fn draw(&mut self, ctx: &mut DrawCtx) {
let active = self.state().state.focused;
let role = if active { Role::ListFocused } else { Role::ListNormal };
// ... draw the title / cursor row with `role`
}
A wrapper built with #[delegate(to = inner)] has exactly one ViewState, the
inner one. Read the flag through self.state(), never from a second copy; see
Wrapping an existing view.
Reacting to a terminal resize
There is no resize event and no resize command. On every pass of the loop the
pump compares the backend size with the root size; when they differ it calls
change_bounds on the root group. Group::change_bounds then calls
calc_bounds and change_bounds on each child, so the new size cascades down
the tree under each child's grow mode.
To lay out children by hand after any resize, override
View::change_bounds
(the C++ changeBounds override). Splitter does this:
#[delegate(to = group)]
impl View for TwoPanes {
fn change_bounds(&mut self, bounds: Rect) {
self.group.change_bounds(bounds); // grow-mode cascade to the children
self.place_panes(); // then move panes with group.child_mut(id)
}
}
View::on_bounds_changed
is the second half of a resize. Every resize path (a window drag or
Context::request_bounds, zoom, tile and cascade, a moved splitter divider, a
terminal resize) ends with this call on the view it re-bounded, and a Group
whose size changed forwards it to every child, so it reaches views at any
depth. It gets a Context, so use it for work that needs one, such as
publishing new scroll-bar limits; Scroller and the list viewers do this. Do
the layout itself in change_bounds, which runs first.
The cursor of an embedded terminal or custom view
The hardware cursor is shown for one view only: the focused view at the end of
the current chain, and only when its
State::cursor_vis
is set. View::cursor_request implements this test, and the pump places the
cursor from it on every pass before the redraw (the TView::resetCursor port).
A view that hosts a terminal emulator copies the emulator cursor into its own
ViewState each time the emulator state changes, in view-local coordinates:
let (x, y, visible) = self.emu.cursor();
let st = self.state_mut();
st.set_cursor(x, y);
if visible { st.show_cursor() } else { st.hide_cursor() }
When the view loses focus the cursor disappears, and it comes back when focus returns. This is intended: one cursor exists on the screen, and it belongs to the view that receives the keys. Keep the position inside the view's size: the pump hides a cursor that lies outside the view, outside an owner on the chain, past the screen edge, or under another window.
Modal dialogs, help context and key bindings
The status line follows the focused view. On each idle pass the pump reads the
help context and hands it to the status line, which then shows the first
StatusDef whose range matches.
An open menu supplies the context first; else, with a modal open, the context
comes from the modal; otherwise from the root.
In both cases Group::get_help_ctx returns the focused child's context and falls
back to the group's own when the child has HelpCtx::NO_CONTEXT. Give a dialog a
context by setting state_mut().help_ctx on the dialog or on one of its controls.
Status-line keys are routed before any view sees them, also while a modal is
open. When a key matches an item of the current def (including hidden
key_item bindings) and its command is enabled, the status line turns the key
event into that command. The focused view never receives the key.
While a modal runs, a command (from a status-line key, a button or
put_event) goes to the modal alone, as in C++ TGroup::execute. A command
the modal does not handle is dropped: the program-level command handler (for
example run_app's) does not see it. So ~F1~ Help, or the Help button of a
file dialog, does nothing under a modal unless the dialog handles
Command::HELP itself. To add that, embed the dialog in your own view type
(#[delegate(to = dialog)]) and handle the command in its handle_event.
let defs = StatusDef::list()
.def_one_of([HelpCtx::custom("app.containers")], |d| {
d.item("~Del~ Remove", KeyEvent::from(Key::Delete), CMD_REMOVE)
})
.def_all(|d| d.item("~Alt-X~ Exit", alt('x'), Command::QUIT))
.build();
An app-wide def must therefore not bind keys that dialogs and editors need, such as Enter, Esc, Tab or Del: an input line would never see Del. Put such bindings in a def that matches only the help context of the view that owns them, as above. The keymap is different: it is read only by the editor and the input line to map keys to editing commands, and does not route keys for the app. See Menus, status line & help.
Getting results out of a modal
From application code that holds &mut Program, use
Program::exec_view_with:
its closure reads the result from the modal before the modal is dropped.
From inside a view, which only has &mut Context, call
ctx.request_exec_view(dialog, my_id, Some(CMD_DONE)). When the modal closes,
the pump calls three things on the requesting view, in this order: it gives the
dialog's gathered record to set_modal_data (skipped when the close command is
Command::CANCEL), gives the close command to set_modal_answer, and posts
CMD_DONE. The two hooks have no Context, so store what they receive and act
when CMD_DONE arrives in handle_event:
fn set_modal_data(&mut self, data: FieldValue) {
if let FieldValue::List(fields) = data
&& let Some(FieldValue::Text(name)) = fields.into_iter().next()
{
self.pending_name = Some(name); // used when CMD_DONE arrives
}
}
Full details: Modal execView → one loop and The data-movement model.
Feeding async results into the UI
Two hooks exist. Both run only on idle passes, which are passes with no input event. With no input they come about every 20 ms, sooner when a timer is due.
Program::set_on_idleholds one callback with&mut Program. It also runs while a modal is open. The callback can update shared state (Rc<RefCell<_>>) that views read indraw; the next redraw shows the change. To make views react, it queues an event withProgram::broadcast(REFRESH, None)orProgram::put_event(ev). The event is delivered on the next pump pass, not inside the callback. Queue it only when new data arrived, not on every pass. Usebroadcastfor refreshes: a broadcast reaches the whole tree also under a modal, but a command or key queued withput_eventwhile a modal is open reaches only the modal and is dropped if the modal does not handle it.- A view-owned periodic timer:
Context::set_timerwith a period. Each expiry arrives asEvent::Timer(id)and is delivered to every view in the tree like a broadcast, also while a modal is open, a window or a column is dragged, or a menu is open. The view can drain a channel and callctx.broadcast(REFRESH, None)so other views update themselves. The timer is not tied to its view: callctx.kill_timer(id)when the work ends.
Use the idle hook when the program owns the data source; use the timer when a
view owns it. The external_state example shows the
timer pattern end to end; see also
Background work each idle pass.
Mouse double-click
The loop marks a mouse press as a double or triple click when the same buttons
are pressed on the same cell within the double-click interval. Read the flags in
the MouseDown handler:
Event::MouseDown(m) if m.flags.double_click => {
self.open_selected(ctx);
ev.clear();
}
MouseEventFlags also has
triple_click. The interval is 440 ms by default; change it with
Program::set_double_delay_ms.
The Program::new factories
Program::new takes three factories, each an
impl FnOnce(Rect) -> Option<Box<dyn View>>, for the desktop, the status line
and the menu bar. Each one runs once, inside Program::new, and receives the
full screen rectangle; it shrinks the rectangle to its own row or area. Return
None to leave out the status line or the menu bar. Because the factories are
FnOnce, they can move app handles in:
let program = Program::new(
backend,
Box::new(SystemClock::new()),
Theme::classic_blue(),
move |r| init_desktop(r, state.clone(), rx), // moves the Receiver in
init_status_line,
init_menu_bar,
);
After construction, Program::desktop, status_line and menu_bar return the
ViewId of each part. See The application skeleton
and examples/external_state.rs.