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

Dialogs & data

A dialog is a modal window: it appears on top of everything, captures input until the user dismisses it, and returns a single answer: which button closed it. Dialog embeds a Window and delegates to it, with dialog-specific behaviour layered on: Esc cancels, Enter accepts the default button, and the frame carries only the move and close affordances, without grow or zoom (the tvision-rs equivalent of C++ TDialog).

Building a dialog

Construct the dialog with a rectangle and an optional title, then populate it with child views (buttons, input lines, checkboxes, labels) via insert_child:

#![allow(unused)]
fn main() {
use tvision_rs as tv;
use tv::{Command, Dialog, Rect};
use tv::widgets::{Button, ButtonFlags, InputLine};
let mut dialog = Dialog::new(Rect::new(0, 0, 40, 11), Some("Sign in".into()));

// insert_child returns the child's ViewId, so you can reach it later.
let name = dialog.insert_child(Box::new(InputLine::with_limit(
    Rect::new(3, 4, 34, 5),
    64, // byte limit (the convenience ctor uses LimitMode::MaxBytes)
)));
dialog.insert_child(Box::new(Button::new(
    Rect::new(15, 8, 25, 10),
    "~O~K",
    Command::OK,
    ButtonFlags { default: true, ..Default::default() },
)));
let _ = name;
}

InputLine::new takes a validator and a LimitMode too; with_limit is the no-validator, byte-limit shortcut. ButtonFlags is a struct of named bools, so the default button is ButtonFlags { default: true, .. }.

A button carries the Command it broadcasts when pressed. The conventional end commands are Command::OK and Command::CANCEL; a message box also uses Command::YES / Command::NO.

A dialog assembled this way, with a labelled input, check boxes, and the two buttons, looks like this:

  File  Edit  Window                                
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
░░╔═[■]════════════ Settings ════════════════╗░░░░░░
░░║                                          ║░░░░░░
░░║  Name:                                   ║░░░░░░
░░║                                          ║░░░░░░
░░║                                          ║░░░░░░
░░║  [X] Enable logging                      ║░░░░░░
░░║  [ ] Auto-save                           ║░░░░░░
░░║  [ ] Show hints                          ║░░░░░░
░░║                                          ║░░░░░░
░░║                                          ║░░░░░░
░░║         OK    ▄              Cancel   ▄  ║░░░░░░
░░║      ▀▀▀▀▀▀▀▀▀▀            ▀▀▀▀▀▀▀▀▀▀▀▀  ║░░░░░░
░░╚══════════════════════════════════════════╝░░░░░░
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
 F10 Menu  Alt-X Exit                               

The runnable source is the dialog entry in the widget gallery.

Running it modally

You do not insert a dialog into the view tree yourself. You hand it to Program::exec_view. It inserts the dialog at the top of the tree, marks it modal, gives it focus, and spins the same event loop until the dialog ends itself, then removes it and hands back the closing command:

#![allow(unused)]
fn main() {
use tvision_rs as tv;
use tv::{Command, Dialog};
fn _demo(program: &mut tv::Program, dialog: Dialog) {
match program.exec_view(Box::new(dialog)) {
    Command::OK     => { /* read the fields back, act on them */ }
    Command::CANCEL => { /* user backed out */ }
    _ => {}
}
}
}

There is no separate "modal loop." tvision-rs runs a single event loop plus a capture stack: exec_view pushes the dialog as the capture target, and the loop drives it until the dialog closes itself (see Modal execView → one loop + capture and the event loop in depth). exec_view is top-level only: a view holds only a &mut Context, never the Program, so it cannot re-enter the loop from inside handle_event. This keeps the single loop sound.

Turbo Vision heritage: in C++ each TGroup::execView spun a fresh nested getEvent loop. tvision-rs collapses all modal nesting into one loop + capture stack, which removes the reentrancy.

A modal must have a path to closing itself, or it hangs. Dialog provides one by default: Esc becomes a Cancel, the default button becomes an OK. If you build a bare modal with neither, nothing will end it.

The framework ships ready-made modals built on this path: message_box for a titled alert with Yes/No/OK/Cancel buttons, and input_box for a single labelled text field. Both build a Dialog, run it through exec_view, and return the user's answer.

Moving data in and out

Dialog data flows through a typed value currency, FieldValue, passed through the value / set_value pair on the View trait. A text field reads and writes FieldValue::Text; an integer control uses FieldValue::Int. The enum grows as controls need it (this replaces the C++ getData/setData pair, which moved data through an untyped memcpy record).

Two operations bracket a dialog:

Turbo Visiontvision-rsDirection
setDatascatter: set_value on each fieldseed the dialog before showing it
getDatagather: value() on each fieldread results after OK

For a single-field dialog you call set_value/value on that one field directly; input_box does this internally to seed and read its lone input line. For a multi-field dialog, the Group behind the dialog walks its children in order: gather_data collects a Vec<Option<FieldValue>> (one slot per child, None where a child has no transferable value), and scatter_data distributes a matching vector back in the same child order. Seed before exec_view, gather after it returns Command::OK.

The full FieldValue currency

FieldValue is the single typed currency for all data exchange in tvision-rs. The well-known shapes are:

VariantProduced by
Text(String)InputLine, Editor
Int(i64)numeric inputs
Bool(bool)single-item toggle controls
Bits(u32)CheckBoxes / RadioButtons cluster
List(Vec<FieldValue>)Group::gather_list / scatter_list
Custom(Rc<dyn CustomValue>)your own controls

Bool carries a simple toggle; Bits carries a bitmask from a cluster (each CheckBoxes or RadioButtons bit maps to one check or radio item in order).

Ordered-record gather and scatter

When you want the whole dialog's data as one value instead of one field at a time, use the ordered-record pair on Group:

// Seed before exec_view — positional, same child order as insert_child.
// scatter_list takes a &mut Context (available inside a handle_event / the pump):
let initial = FieldValue::List(vec![
    FieldValue::Text("Alice".into()),
    FieldValue::Bits(0b01),  // first checkbox ticked
]);
dialog.scatter_list(&initial, ctx);

// Read after exec_view returns Command::OK:
let record = dialog.gather_list();
// record == FieldValue::List([FieldValue::Text(...), FieldValue::Bits(...)])

gather_list walks the group's children in insertion order and collects each child's value() into a FieldValue::List, the positional equivalent of C++ getData's memcpy record. scatter_list distributes the list back in the same order via set_value. Children with no transferable value (labels, decorative views) are skipped in both directions; the list contains only the slots that produce a value, so the index order matches the sequence of data-bearing children.

Dialog::value() returns the same record (gather_list()), so a dialog nested in another group, or a view that delegates value to a dialog, hands over its whole record through the ordinary value() call.

The Custom seam and third-party controls

For richer payloads, such as a date range, a colour swatch or a structured selection, a control can return FieldValue::Custom(...). See Third-party components & data interchange for the details: the three exchange paths, value_as::<T>() / as_custom::<T>(), the TypeId caveat, and when to skip FieldValue entirely.

Delivering a modal's result back to its launcher

How a modal's result reaches the view that opened it depends on who opened it.

Program-launched modals, opened from outside the view tree (for example the color picker or theme editor), return their result directly: the pump runs exec_view_with<R>, the closure reads the modal's state while it is still in the tree, and the result comes back as a plain Rust value. Use this path when the result type is rich and does not map naturally to FieldValue (such as Color or Theme).

View-launched modals, opened from inside handle_event via the Deferred channel, cannot return inline (a view holds only &mut Context, never the Program). Instead, after the modal closes, the pump reads each dialog field by id via View::value() and delivers the assembled result to the launcher by id via View::set_modal_data(FieldValue) (virtual dispatch, no downcast). The launcher overrides set_modal_data to interpret the ordered FieldValue::List and update its own state. The editor's Find/Replace modals follow this pattern: the pump reads the text field as FieldValue::Text and the options cluster as FieldValue::Bits, then calls editor.set_modal_data(List([Text, Bits])).

A modal you launch yourself with Context::request_exec_view gets the same delivery without a custom completion: on a non-cancel close the pump reads the modal's value() (for a Dialog, its gathered FieldValue::List) and calls requester.set_modal_data(record) before set_modal_answer(command) (see Getting the data back).

Note that set_modal_data is distinct from set_value: set_value carries a view's own document or field data (the D10 scatter path); set_modal_data carries a modal's result collected by the pump on the launcher's behalf.

Tab order and data transfer

Both Tab navigation and gather/scatter data order follow the single children Vec in the group, specifically the insertion order (oldest first, as stored in children[0], children[1], …). The children are stored back-to-front for painting, and forward for data transfer: gather_data walks them oldest-first and returns one Option<FieldValue> per child.

inserted 1st → children[0]  (Tab: first stop; gather: slot 0)
inserted 2nd → children[1]  (Tab: second stop; gather: slot 1)
…
inserted last → children[n] (Tab: last stop; gather: slot n)

Tab calls Group::focus_next(forwards: true, ctx), which iterates children in forward order and wraps around. Shift-Tab iterates in reverse. Disabled or invisible children are skipped: they remain in the children slice but focus_next steps over them.

When you assemble a dialog, insert controls in the order you want the Tab key to visit them, typically top-to-bottom, then left-to-right. Buttons are usually inserted last so they receive focus after all the data fields.

Gather (the dialog walking its children to collect values) follows the same forward order. Scatter distributes values in the same order. The index in the Vec<Option<FieldValue>> that gather_data returns corresponds 1:1 to the insertion slot: index 0 is the first-inserted child, index 1 is the second, and so on.

#![allow(unused)]
fn main() {
use tvision_rs as tv;
use tv::{Command, Dialog, Rect};
use tv::widgets::{Button, ButtonFlags, InputLine, LimitMode};
#[allow(unused_variables)]
fn _demo() {
let mut dialog = Dialog::new(Rect::new(0, 0, 40, 10), Some("Login".into()));

// Insert in Tab order: name first, password second, button last.
let name_id   = dialog.insert_child(Box::new(InputLine::new(Rect::new(3, 3, 34, 4), 64, None, LimitMode::MaxBytes)));
let pass_id   = dialog.insert_child(Box::new(InputLine::new(Rect::new(3, 5, 34, 6), 64, None, LimitMode::MaxBytes)));
let _btn_id   = dialog.insert_child(Box::new(Button::new(Rect::new(15, 7, 25, 9), "~O~K", Command::OK, ButtonFlags { default: true, ..Default::default() })));

// After exec_view returns Command::OK, gather in the same order:
// gathered[0] = name, gathered[1] = password, gathered[2] = None (button has no value).
}
}

Source: src/view/group.rs (Group::gather_data, Group::scatter_data, Group::focus_next).

Turbo Vision heritage: in C++ TGroup::getData/setData walked the same circular sibling ring in forward order; the ring order was insertion order (newest at the front, so a full walk from last->next gives oldest first). The tvision-rs Vec stores oldest at index 0, preserving the same forward walk.

The change-directory dialog

ChDirDialog is a ready-made directory chooser: a path input line with a history recall icon, a collapsible directory tree (DirListBox), and action buttons. Build it with ChDirDialog::new:

#![allow(unused)]
fn main() {
use tvision_rs as tv;
fn _demo(program: &mut tv::Program) {
use tv::dialog::{ChDirDialog, CD_NORMAL};

let mut cd = ChDirDialog::new(CD_NORMAL, 0);
let result = program.exec_view(Box::new(cd));
let _ = result;
}
}

The opts parameter is a bitmask:

ConstantEffect
CD_NORMALStandard dialog, loads the current directory tree on open
CD_NO_LOAD_DIRSkip the initial directory scan (faster first open)
CD_HELP_BUTTONAdd a Help button at the right

The second argument is the history_id (u8) for the path input's recall dropdown. Use a non-zero id to enable history recall, or 0 to skip it (the gallery example uses 0).

When the user navigates the tree and double-clicks a directory (or types a path and presses Chdir), the dialog writes the chosen path into its input field and dismisses with Command::OK. Read the result from the dialog's input:

use tv::dialog::{ChDirDialog, CD_NORMAL};
use tv::data::FieldValue;

let mut cd = ChDirDialog::new(CD_NORMAL, 0);
if program.exec_view(Box::new(cd)) == tv::Command::OK {
    // The path is available after exec_view returns — gather from the child
    // or std::env::current_dir() if ChDirDialog has already changed directories.
    if let Ok(path) = std::env::current_dir() {
        println!("Changed to {}", path.display());
    }
}

The dialog is growable (the WindowFlags::grow flag is set internally) so the user can resize it, and the tree grows with the dialog bounds via GrowMode.

Source: src/dialog/filedlg.rs (ChDirDialog::new, DirListBox, DirCollection).

See also