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

Controls

Controls are the leaf views you put inside a dialog or window: buttons, check boxes, radio buttons, input fields, captions, list boxes, and scroll bars. You build them, insert them into a group (a Dialog or Window), and let the event loop drive them. The names follow the tv:: house style with no T prefix. Most map to the Turbo Vision T* class of the same name; the ones Turbo Vision lacks are marked tvision-rs extension and listed on Extensions beyond Turbo Vision.

Buttons

A Button is a clickable command button: a boxed, shadowed title with an optional ~-marked hotkey. Pressing it (mouse, Alt+hotkey, or focused Space) fires its command, either posted as a normal command event or, when the button is flagged broadcast, sent as a broadcast. The default button additionally responds to Enter. A keyboard press does not fire instantly: the button flashes its pressed look for a moment (a short one-shot timer) and then fires, so the click is visible.

#![allow(unused)]
fn main() {
use tvision_rs as tv;
use tv::Command;
let bounds = tv::Rect::new(0, 0, 10, 3);
use tv::widgets::{Button, ButtonFlags};
// bounds, title (~ marks the hotkey), command, flags — then insert into the dialog.
let ok = Button::new(bounds, "~O~K", Command::OK, ButtonFlags { default: true, ..Default::default() });
let _ = ok;
}
  File  Edit  Window                    
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
░░╔═[■]═══════ Buttons ════════════╗░░░░
░░║                                ║░░░░
░░║                                ║░░░░
░░║                                ║░░░░
░░║        OK    ▄      Cancel  ▄  ║░░░░
░░║     ▀▀▀▀▀▀▀▀▀▀     ▀▀▀▀▀▀▀▀▀▀  ║░░░░
░░║                                ║░░░░
░░╚════════════════════════════════╝░░░░
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
 F10 Menu  Alt-X Exit                   

A runnable, captured example of every control on this page (buttons, check boxes, radio buttons, input lines, and more) is in the widget gallery.

Check boxes & radio buttons

These share one engine, the Cluster: a single type that branches on a ClusterKind, wrapped by three named types:

  • CheckBoxes: independent on/off boxes ([X]); any combination may be set.
  • RadioButtons: mutually exclusive options ((•)); exactly one is selected.
  • MultiCheckBoxes: multi-state boxes that cycle through more than two values.

A cluster lays its items out top-to-bottom and wraps into a new column when the height is exceeded; the bounds height is the column-break period. The selected value is read and written through the data protocol like every other control, so a dialog gathers and scatters cluster state automatically.

Input lines

An InputLine is a single-line text field with selection, horizontal scrolling, clipboard cut/copy/paste, and an optional Validator. Its cursor and selection track byte offsets into a real Rust String, so multi-byte and wide text behave correctly.

Read-only fields

tvision-rs extension to TInputLine: not in Turbo Vision. See Extensions beyond Turbo Vision.

set_read_only(true) makes a field refuse every change to its text while leaving it fully navigable. Disabling a field is different: a disabled view is skipped by focus entirely, so a value too wide for its cell can never be scrolled into view, selected, or copied. A read-only field still takes focus, moves its caret, scrolls, select-alls and copies. Only typing, deleting, cutting and pasting are refused.

Each refusal consumes the event and broadcasts InputLine::READ_ONLY_REJECTED with the field's own ViewId as the source, so the owner can tell the user which field would not budge and why. The widget says nothing on its own, because only the owner knows the reason. Cut and paste are also grayed in the command set, so the menu route cannot do what the keyboard route refuses.

#![allow(unused)]
fn main() {
use tvision_rs as tv;
fn _demo() {
use tv::widgets::{InputLine, LimitMode};

let mut line = InputLine::new(tv::Rect::new(3, 3, 30, 4), 64, None, LimitMode::MaxBytes);
line.set_read_only(true); // reachable and copyable, but not editable
}
}

A read-only field is drawn exactly like an editable one. Signalling the distinction visually is left to the owner, which knows whether "read-only" means server-maintained, computed, or merely not-yet-unlocked.

Which end of a long value shows

tvision-rs extension to TInputLine: not in Turbo Vision. See Extensions beyond Turbo Vision.

A value wider than its field can only show one end of itself. set_value select-alls, so by default the view sits at the tail. This is Turbo Vision's behaviour, and it suits a field whose first keystroke should replace the value. For data whose front identifies it, the operator is left reading …,dc=example,dc=org.

#![allow(unused)]
fn main() {
use tvision_rs as tv;
fn _demo(line: &mut tv::widgets::InputLine) {
use tv::widgets::ValuePosition;

line.set_value_position(ValuePosition::Start); // show the head, caret homed
}
}

This governs set_value only: both the plain text path and the validator-transfer path. Focus behaviour is separate: see set_select_all_on_focus.

Labels & static text

  • StaticText: a read-only, word-wrapped block of text. It is not selectable and only paints.
  • ParamText: a StaticText variant whose content you set at runtime.
  • Label: a single-line caption linked to another control. Clicking the label, or pressing its ~-marked hotkey, focuses the linked control, and the label highlights while that control holds focus. The link is a view handle, not a pointer.

List boxes, scrollers & scroll bars

  • ListBox: a scrollable list of string items. Populate it after inserting it into a group (a Context is needed to publish the scroll range to its bars), then it handles selection and navigation for you. SortedListBox keeps the items ordered.

    tvision-rs extension to TListViewer: incremental find is not in Turbo Vision. See Extensions beyond Turbo Vision.

    Both support an opt-in incremental find via with_find(FindMode): FindMode::Highlight owns the query and highlights the matched substring in every visible row; FindMode::Filter additionally self-filters the list to rows that contain the query (showing No match: <query> when nothing survives). FindMode::Off is the default; the classic type-to-jump lookup is unchanged for existing consumers. While find is active, printable keys (including Space) append to the query, Backspace deletes, and Esc clears (an empty-query Esc still propagates so a host dialog can close). The current query is readable via find_query() and clearable externally via clear_find(). Every query change broadcasts Command::LIST_FIND_CHANGED with the list's own ViewId as source, the same notify-by-broadcast pattern ScrollBar uses, so a host can mirror the query or drive an async search.

  • ScrollBar: a vertical or horizontal bar (orientation inferred from its 1×N or N×1 bounds). It broadcasts a changed message when its value moves, naming itself as the source so a two-bar owner can tell which bar fired.

  • Scroller: the base for scrollable content. It references two sibling scroll bars on the window frame, mirrors their value into its own scroll offset, and pushes range changes back to them. The wiring between a scroller and its bars is brokered by the event loop; see Cross-view brokering.

  • Table: a multi-column list under a click-to-sort header.

    tvision-rs extension: not in Turbo Vision. See Extensions beyond Turbo Vision.

    Rows come from a TableModel and keep a stable RowKey, so focus and the marked rows follow the record through a re-sort or reload. Columns can be resized, moved and hidden with the mouse (column_layout / set_column_layout save the arrangement), and cells of editable columns are edited in place with Enter, F2 or a double-click. See the gallery for the full behaviour.

Validators

A validator gates what an input line accepts. Validator is a trait; an input line holds one as a boxed trait object (the Rust-idiomatic successor to C++ TValidator's abstract base class). With no validator, every keystroke is accepted. The trait has two checkpoints: is_valid_input runs as each character is typed (and may auto-fill or modify the buffer), while is_valid runs the final-form check when the field must be fully valid: on focus-release or when a modal dialog's OK button is pressed.

The concrete validators port the Turbo Vision set, plus RegexValidator:

ValidatorAccepts
FilterValidatoronly characters from a given set
RangeValidatoran integer within [min, max]
PXPictureValidatortext matching a Paradox picture mask
LookupValidator / StringLookupValidatora value from a fixed list
RegexValidatortext matching a regular expression (tvision-rs extension, see Extensions beyond Turbo Vision)

When a final-form check fails, the validator can pop an informational error message box explaining what is wrong, then return focus to the field.

Validating a field

Setting Options::validate (ofValidate) on a control tells the owning group to ask the control whether it is ready to give up focus before moving focus away. The check runs through View::valid with the command Command::RELEASED_FOCUS.

For an InputLine with a validator, this is wired automatically: the input line sets ofValidate for you, and its valid override calls the validator's validate method. If the field is not yet valid, valid returns false, and Group::focus_child refuses the focus transfer and keeps the cursor in the current field.

#![allow(unused)]
fn main() {
use tvision_rs as tv;
fn _demo() {
use tv::widgets::{InputLine, LimitMode};
use tv::RangeValidator;

// An input line that only accepts integers in [1, 100].
// ofValidate is set automatically because a validator is attached.
let line = InputLine::new(
    tv::Rect::new(3, 3, 20, 4),
    64,
    Some(Box::new(RangeValidator::new(1, 100))),
    LimitMode::MaxBytes,
);
let _ = line;
}
}

The user cannot Tab away or dismiss the dialog with OK until every validated field reports is_valid. Source: src/view/group.rs (Group::focus_child validate gate).

Validating without closing

Validation runs at two moments:

  1. Focus release: valid(Command::RELEASED_FOCUS): only the current (focused) control is asked. The group's valid override for this command delegates to the current child exclusively (src/view/group.rs).
  2. Modal close: valid(cmd) for any other command (for example Command::OK): the group walks all children, calling valid on each and stopping at the first that returns false (a firstThat walk).

You can also call group.valid(Command::OK, ctx) programmatically, from a button handler for instance, to force a full validation pass without closing the dialog. The dialog's own handle_event for Command::OK runs exactly this check before it calls ctx.end_modal(Command::OK).

Source: src/view/group.rs (Group::valid), src/dialog/dialog.rs (Dialog::handle_event OK branch).

Turbo Vision heritage: TGroup::valid had the same two arms: one for cmReleasedFocus (current only) and one for all other commands (all children). tvision-rs ports both behaviors verbatim.

When validation fails

When Validator::is_valid returns false, the validator's error method is called. This is where the user sees an informational message box explaining what is wrong.

A leaf view cannot run a modal dialog inline: it holds only &mut Context, never the Program. Instead, error requests the message box through the async-modal seam: Context::request_message_box queues a Deferred::RequestMessageBox entry; the event loop builds and runs the dialog at the end of the current pump tick. The call parameters include an optional answer_to: Option<ViewId> and then_command: Option<Command>. When these are None (the validator error case), the message box is informational only: the user clicks OK, the box closes, and focus returns to the invalid field. No round-trip answer is needed.

Here is how a concrete validator implements error (from src/validate.rs, FilterValidator::error):

fn error(&self, ctx: &mut Context) {
    ctx.request_message_box(
        "Invalid character in input".to_string(),
        tvision_rs::dialog::MessageBoxKind::Error,
        tvision_rs::dialog::MessageBoxButtons::ok(),
        None,  // answer_to — no round-trip needed
        None,  // then_command
    );
}

When you write a custom validator, override both is_valid and error:

#![allow(unused)]
fn main() {
use tvision_rs as tv;
use tv::validate::Validator;
use tv::view::Context;

struct NoSpaceValidator;

impl Validator for NoSpaceValidator {
    fn is_valid(&self, s: &str) -> bool {
        !s.contains(' ')
    }

    fn error(&self, ctx: &mut Context) {
        ctx.request_message_box(
            "Spaces are not allowed.".to_string(),
            tv::dialog::MessageBoxKind::Error,
            tv::dialog::MessageBoxButtons::ok(),
            None,
            None,
        );
    }
}
}

The provided validate method calls is_valid and then error for you; override is_valid and error instead of validate itself.

Source: src/validate.rs (Validator::error, FilterValidator::error), src/view/context.rs (Context::request_message_box).

History lists

A THistory dropdown icon lets users recall previous entries for an input field. It pairs with a u8 channel id (the history_id) that identifies which history list the icon reads and writes.

Place the icon immediately to the right of the input line (it is 3 cells wide: ▐↓▌) and pass the input's ViewId and the channel id:

#![allow(unused)]
fn main() {
use tvision_rs as tv;
fn _demo(dialog: &mut tv::Dialog) {
use tv::widgets::{InputLine, THistory, LimitMode};

// Insert the input line first to get its ViewId.
let input_id = dialog.insert_child(Box::new(
    InputLine::new(tv::Rect::new(3, 3, 30, 4), 64, None, LimitMode::MaxBytes)
));

// Place the recall icon immediately to the right.
let _hist_id = dialog.insert_child(Box::new(
    THistory::new(tv::Rect::new(30, 3, 33, 4), input_id, 42)
));
}
}

The channel id 42 (any u8) is the key for the global history store. When the user confirms an entry in the field (the input's value is saved on dialog OK), call history_add(id, text) to push the string into the store. On the next open, the ↓ button pops a scrollable recall list sorted newest-first; picking an entry writes it back into the linked input.

The store is process-global and byte-budgeted (default 1024 bytes across all channels). The oldest entries across all channels are evicted when the budget is exceeded. Access the store directly with history_str(id, index) and history_count(id) when you need to pre-populate or audit entries.

The icon is not selectable (clicking it does not steal focus from the linked input), and it opts into post-processing so it sees key events after the focused input, leaving the ↓ arrow key available as a keyboard trigger.

Source: src/widgets/history.rs (THistory, HistoryViewer, HistoryWindow, history_add, history_str, history_count).

Turbo Vision heritage: THistory / THistoryViewer / THistoryWindow port one-to-one. The global byte store (histlist.cpp) is reimplemented as a thread-local Vec<HistRec>, dropping the original front-sentinel bookkeeping for a simpler read contract.

Where to go next