Guide API
Skip to main content

Module table

Module table 

Source
Expand description

A multi-column table: a column header with click-to-sort over a scrolling row list, with single or multi selection that follows a stable row key across sorting and reloads.

§Structure

Table is a Group-based composite with two children, each with its own ViewState:

  • a one-row header that draws the column labels and the sort marker (▲/▼); a click on a label sorts by that column, a second click flips the direction (see Columns for the drags and the popup);
  • a row body that is a ListViewer (one column, item text = the formatted row), so keys, mouse, focus colours, type-to-search and the vertical scroll bar behave exactly like a ListBox.

The body is the selectable child: focusing the table focuses the body, and the focused state reaches it through the group. The header stretches horizontally and the body in both directions when the table is resized. The vertical scroll bar is an external sibling passed by id, the ListBox convention.

§Layout

Column widths follow the view width on every draw. Columns that do not fit shrink widest first, never below their min_width; spare width goes to the flex columns by weight (the cells the rounding leaves over go one each to the leftmost flex columns), or stays empty without one. When the columns still do not fit at their min_widths, they scroll horizontally by display cells: the header scrolls with the rows, the multi-select check column stays put, ←/→ scroll one cell (past the cell cursor’s stops, see Editing), and an optional horizontal bar (Table::with_h_bar) shows and drives the offset (Table::h_offset / Table::set_h_offset); while the columns fit, the bar’s range is 0. A resize changes the bars’ page steps and the horizontal range; the table re-publishes them at once (every framework resize path calls on_bounds_changed), or on its next event after app code called change_bounds directly.

§Columns

The user arranges the columns from the header:

  • Resize: drag the separator cell right of a label (the cell after the last column too, or the last column’s own last cell when it ends at the view’s right edge). The width follows the pointer, clamped to the column’s min_width and to MAX_COLUMN_WIDTH; the column turns fixed (a flex column stops stretching), so the layout keeps that width and scrolls instead of shrinking it.
  • Move: press a label and drag off it; a marker shows the gap the column lands in, the release moves it there. A press and release without leaving the label sorts instead. Sort, width and hidden state belong to the column, so they move with it.
  • Show/hide: a right-click on the header (or Command::TABLE_COLUMNS) opens a popup listing every column with a check mark; choosing one shows or hides it. The last visible column stays: the popup cannot grey it out, so choosing it does nothing. Each item posts Table::toggle_column_command.

ColumnSpec::resizable and ColumnSpec::movable turn the drags off per column. Table::column_layout / Table::set_column_layout read and restore the arrangement for persisting it.

§Editing

A column built with ColumnSpec::editable can be edited in place. While at least one visible column is editable the focused row shows a cell cursor (Role::TableCellCursor): ←/→ move it between the editable columns in display order, scrolling it into view; at the first or last one the keys scroll the columns as usual. A click on an editable cell puts the cursor there.

Enter or F2 on the cell cursor, or a double-click on an editable cell, opens an InputLine over the cell, pre-filled with its text, all selected, with the column’s validator if it has one. Enter stores the text through TableModel::set_cell; a validator or a set_cell that refuses it shows its message in an error box and the editor stays open. After a store the cell cursor stays on the cell, so the next Enter edits it again; the Enter that stores does nothing else (it does not press the dialog’s default button). Esc cancels; so does losing the focus or a click outside the editor. Tab and Shift-Tab store and open the next/previous editable cell of the row; past the last (first) one the edit ends and the Tab goes on, moving the focus as usual. An unchanged text stores nothing. A dialog’s OK (any end command but Cancel, through View::valid) stores an open edit first, and a refusal keeps the dialog open; Cancel cancels it. Without a cell cursor (no visible editable column) or without rows, the table does not use Enter, so it reaches the dialog’s default button; with a cursor and a row it is always the table’s, like F2, even when the cell has no room to show an editor. With modifiers (Ctrl, Alt, Shift) Enter never edits. A double-click on a cell that is not editable still chooses (single mode) or toggles (multi mode) the row, and Space still marks it in multi mode.

The status line sees every key first. An app that binds F2 app-wide (the Turbo Vision ~F2~ Save convention) turns F2 into its command before the table gets it; Enter and a double-click still open the editor there. Bind such keys only in a status def for the help context of the view that owns them.

After a store the sort is re-applied and the focus follows the row’s key. The editor stays over its cell through a re-sort, a horizontal scroll, a column resize or move, a Table::set_model reload (with the typed text) and a table resize (a resize scrolls the cell back into view). A cell scrolled off screen hides the editor without ending the edit: the next key scrolls it back and goes to the editor. When the cell is gone (its row left the model in a Table::set_model reload, its column was hidden) the edit ends without storing anything or showing a box — at once for a reload, at the table’s next event for a hidden column — and the next key after that is used up, so an Enter meant for the editor cannot press the dialog’s default button. A press on the header cancels the edit, and so does moving the focus to another row (Table::set_focused_key, View::set_value).

§Data

The rows come from a TableModel (VecModel for plain strings). The table never reorders the model; it keeps a row permutation for the current sort. Every row has a RowKey: focus and the multi-selection follow the key through a re-sort and through Table::set_model.

§Wiring

Build with Table::new and Table::with_model (plus Table::with_h_bar for a horizontal bar), insert, done: the table publishes its ranges and scroll steps to the bars on activation or on its first event. Reload later with Table::set_model.

ⓘ
let vsb_id = dlg.insert_child(Box::new(ScrollBar::new(Rect::new(41, 2, 42, 12))));
let table = Table::new(
    Rect::new(2, 2, 41, 12),
    vec![ColumnSpec::new("Name", 16), ColumnSpec::new("Size", 8).right()],
    Some(vsb_id),
)
.with_model(Box::new(VecModel::new(rows).with_keys(keys)));
let table_id = dlg.insert_child(Box::new(table));

§Notifications

User actions broadcast with the table’s id as source: Command::TABLE_SORT_CHANGED (header click, Command::TABLE_SORT_NEXT, Command::TABLE_SORT_FLIP), Command::TABLE_SELECTION_CHANGED (multi mode: a click on a row’s [ ] box, Space or a double-click toggled a row) and Command::LIST_ITEM_SELECTED (single mode: Space or a double-click chose the focused row) and Command::TABLE_COLUMNS_CHANGED (a column resized, moved, shown or hidden) and Command::TABLE_CELL_EDITED (a cell editor stored a new text). Programmatic setters do not broadcast — the caller already knows what it changed.

§Turbo Vision heritage

tvision-rs extension: no Turbo Vision counterpart. Like Splitter and TabBar, it is listed on the guide’s “Extensions beyond Turbo Vision” page. Its feature set and the pure helpers in layout are adapted from the Table of tvdocker (https://github.com/supertorpe/tvdocker, MIT, by supertorpe), rebuilt on the list viewer.

Re-exports§

pub use layout::Align;
pub use layout::ColumnSpec;
pub use layout::Separators;
pub use layout::SortDir;
pub use layout::ValidatorFactory;
pub use model::RowKey;
pub use model::SortKey;
pub use model::TableModel;
pub use model::VecModel;

Modules§

layout
Column specs and the pure layout/format/sort helpers behind the table’s header and body. Nothing here touches a view; everything is unit-tested.
model
The table’s data source: the TableModel trait, its row identity RowKey, the sort currency SortKey, and the ready-made VecModel.

Structs§

ColumnState
The persistent state of one column, as Table::column_layout reports it and Table::set_column_layout restores it.
Table
A multi-column table view. See the module docs.

Enums§

SelectionMode
How a Table selects rows.