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 aListBox.
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_widthand toMAX_COLUMN_WIDTH; the column turnsfixed(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 postsTable::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
TableModeltrait, its row identityRowKey, the sort currencySortKey, and the ready-madeVecModel.
Structs§
- Column
State - The persistent state of one column, as
Table::column_layoutreports it andTable::set_column_layoutrestores it. - Table
- A multi-column table view. See the module docs.
Enums§
- Selection
Mode - How a
Tableselects rows.