The data-movement model
A tvision-rs application moves values across view boundaries constantly: a user
types text into an input line and the dialog gathers it; a scroller shifts its
position and two scrollbars have to follow; a color-picker modal closes and its
chosen color lands back in the caller. In C++ Turbo Vision all three of those
motions went through the same loose channel (getData/setData for records,
message()/infoPtr for signals, execView returning a bare ushort), and
the caller interpreted a raw pointer or cast an integer back to a useful type.
In Rust, every "move this value to there" needs a typed answer, and the answer differs by what is being moved. tvision-rs gives one typed currency and one mechanism per kind of movement.
The three kinds
| Kind | Currency / mechanism | Deep-dive |
|---|---|---|
| Field & record data (dialog ↔ controls) | FieldValue via value() / set_value(); groups gather/scatter an ordered List | Dialogs & data, Third-party components |
| Sync signals (sibling ↔ sibling) | Defaulted View trait methods brokered by the pump (apply_scroll_sync, set_indicator_value, apply_page_sync) | Cross-view brokering & ViewId |
| By-value modal results | Program::exec_view_with<R> (result by value) or Context::request_exec_view (record via set_modal_data, then close command via set_modal_answer) | Modal execView → one loop |
Field & record data
FieldValue is the single typed
currency for data that moves between a dialog and its controls. The well-known
shapes (Text, Int, Bool, Bits, List) interoperate with framework
widgets and generic consumers. Custom(Rc<dyn CustomValue>) is the open seam
for a payload your own component invents; the framework moves it opaquely and the
consumer downcasts at the edge (runtime-checked, fail-loud).
A control exposes its value via View::value() and absorbs a new one via
View::set_value(). A group gathers its children in insertion order into a
FieldValue::List (Group::gather_list) and scatters a list back the same way
(Group::scatter_list). This is the typed successor to C++ getData/setData:
the same positional, anonymous walk over children, now statically typed.
See Dialogs & data for the full recipe and Third-party
components for the Custom seam and the three open
extensibility paths.
Sync signals
A scroller cannot reach its scrollbars inline: during event dispatch it holds
only a downward &mut Context, and the borrow checker forbids a sideways reach
to a sibling. Instead the scroller queues a deferred effect
(Deferred::ScrollSync), and the pump, which owns the whole tree, resolves
the target by ViewId and calls the appropriate defaulted View method
(apply_scroll_sync, set_indicator_value, apply_page_sync) by virtual
dispatch. The pump is the broker; there is no downcast and no pointer-chasing.
This is the return-less, deferred successor to C++ message(target, …, infoPtr)
(deviation D3/D9). Sync signals are kept separate from field data because they
are behavioral pokes ("recompute from your scrollbar") with no value to
marshal and scatter, so they stay out of FieldValue.
See Cross-view brokering & ViewId for the broker pattern in depth.
By-value modal results
How a modal hands its result back depends on who opened it.
Turbo Vision heritage: C++
execViewreturned aushortend command; the caller read results from the still-live dialog withgetData. tvision-rs keeps that shape (run the modal, read the result before it is torn down), but the return type is now caller-named Rust instead of a bare integer.
Choosing how a modal returns its result
The decision rule:
Opened from a Program / Application method → use
Program::exec_view_with<R>.
At the pre-drop window, while the view is still in the tree, the extract
closure receives the modal's &mut dyn View and the end command; whatever it
returns comes back by value. Use this path when the result type is rich
and does not map to FieldValue (for example Color or a whole Theme).
let chosen: Option<Color> = program.exec_view_with(Box::new(dialog), |modal, cmd| {
(cmd == Command::OK)
.then(|| read_color_from(modal))
.flatten()
});
Opened from inside a view's handle_event → a view holds only
&mut Context, never &mut Program, so it cannot call exec_view_with inline.
Call ctx.request_exec_view(view, requester, then_command) instead; this queues
Deferred::OpenModal and returns immediately. The pump picks it up on the same
turn, runs the modal through the existing single-loop machinery, and on close
delivers, in this order, the modal's record (value(), for a Dialog its
gathered FieldValue::List) via View::set_modal_data (skipped when the close
command is Command::CANCEL) and the close command via
View::set_modal_answer(Command); the requester overrides the hooks it needs.
See Getting the data back.
What stays separate, on purpose
Not everything is forced into FieldValue or routed through the pump:
Event::Broadcast { source }carries aViewIdas a subject filter that addresses a view and carries no data. A scrollbar sets itself assourceso a scroller can tell which bar fired. This isinfoPtr-as-subject, unchanged from C++ (deviation D4).ColorandThemecross by value viaexec_view_with<R>instead of asFieldValue.Coloris a four-variant enum (Default/Bios/Indexed/Rgb) that does not pack into a scalar, andThemeis far larger than any field exchange warrants. Both are deliberate exceptions, documented at their sites.- Structural parent→child pushes (a frame being told it is zoomed, a window pushing display state into its known child frame) still resolve a known child directly. This is a parent orchestrating its own known composition, a category separate from data movement, and it stays where it is.
Where to go next
- Dialogs & data:
FieldValuein practice: building dialogs, gathering and scattering data, and reading results. - Third-party components & data interchange: the three open
extensibility paths,
Custom,value_as, and the TypeId caveat. - Modal execView → one loop: the launch paths in depth:
exec_view_with,request_exec_view, and the Info-box worked example. - Cross-view brokering & ViewId: the pump as broker: sync signals, scrollbar/scroller coordination, and broadcasts.
- Deviations D1–D15: D10 is the typed value
protocol that replaced the
getData/setDatarecord transfer.