Struct Table 

pub struct Table<Msg> { /* private fields */ }

Rows of cells under a header row. Only the rows on screen are drawn, so a table stays fast with any number of rows; pass the rows as an Arc<[TableRow]> kept in your state to avoid copying them every frame.

The header sits on a raised surface with faint titles. Columns are separated by space; their widths follow ColumnWidth and Column::min, and when the minimums do not fit, the columns scroll sideways: arrows at the ends of the header show which side hides columns. The application owns the selection, the checked rows and the sort order and is told about changes through messages. A hovered or selected row raises its surface and shows the pillar; only its first cell slides one cell right. The check mark of a multi-select table never moves.

Keys while focused: ↑/↓ or k/j, PgUp/PgDn, Home/End move; Enter activates; Space toggles in multi-select tables and activates otherwise; ←/→ scroll columns that overflow; with Table::on_sort, s sorts by the next sortable column and shift+s reverses the order.

The mouse does the same: a click on a row selects and activates it, a click on its check mark (or the cell after it) only toggles, a click on a sortable title sorts by it and a second click reverses it, and a click on a header arrow scrolls the columns one step.

Four capabilities make the rows work the way a file explorer’s do, each off until asked for:

• activate_on(Click::Double): a click only selects a row and a double click activates it, so a click can start a drag or a selection without opening anything.
• multi_select: several rows are selected at once with Ctrl+click, Shift+click and Space; they share the selection tone while only the cursor’s row carries the pillar and slides.
• box_select: a drag from the free space below the rows draws a box, and the rows it covers become the selection.
• droppable: the selection is dragged onto a row that takes it, such as a folder, which takes the accent tone while the drag is over it.

Style keys: rows use list-item (hover, selected, focus, pressed) and list-item.faint like List; table-header (bg, fg) with hover over a sortable title and selected on the sorted one; table-sort for the sort arrow; table-scroll (fg, bg) with hover for the header arrows; list-header for the empty text; tree-drop for the row a drag would drop on; text-selection (bg) for the selection box; scrollbar.

Implementations

impl<Msg: 'static> Table<Msg>

pub fn new( columns: impl IntoIterator<Item = Column>, rows: impl Into<Arc<[TableRow]>>, ) -> Self

A table with columns showing rows.

pub fn selected(self, index: Option<usize>) -> Self

The selected row index.

pub fn checked(self, checked: Vec<bool>) -> Self

Turns on multiple selection; checked[i] tells whether row i is checked.

pub fn sort(self, column: usize, direction: SortDirection) -> Self

Shows the sort arrow on column pointing in direction. The rows must already be in that order; the table does not reorder them.

pub fn empty_text(self, text: impl Into<String>) -> Self

Text shown under the header when there are no rows.

pub fn on_select(self, message: impl Fn(usize) -> Msg + 'static) -> Self

Message for moving the selection to a row.

pub fn on_activate(self, message: impl Fn(usize) -> Msg + 'static) -> Self

Message for opening a row (Enter, click).

pub fn on_toggle(self, message: impl Fn(usize) -> Msg + 'static) -> Self

Message for checking or unchecking a row of a multi-select table (Space, click on the mark).

pub fn on_sort( self, message: impl Fn(usize, SortDirection) -> Msg + 'static, ) -> Self

Message asking to sort by a column in a direction; turns on sorting by clicking titles of Column::sortable columns and with s / shift+s.

pub fn context_menu( self, items: impl Fn(usize) -> Vec<ContextItem<Msg>> + 'static, ) -> Self

Gives every row a context menu: items(index) builds the entries for the row of that index, and the menu acts on the row it was opened on rather than on the selected one.

A right press on a row opens the menu at the pointer; the menu key or Shift+F10 opens the menu of the selected row below it, scrolling it into view first. The row the menu belongs to stays raised while it is open, so it is clear what the entries act on. A right press on a row that is not checked makes it the selection first, so a menu never acts on rows the person did not mean.

pub fn menu_on_activate(self, on: bool) -> Self

Makes a row’s context menu its action: Enter opens the menu of the selected row below it and a click opens the menu of the clicked row where it was clicked, instead of sending on_activate.

For a table whose rows are acted on only through a few choices: a right click is not what most people try in a terminal and many keyboards have no menu key, so the menu is also reached the way any row is opened. A row whose menu has no entries opens nothing. Off by default; without a context menu it does nothing.

pub fn activate_on(self, click: Click) -> Self

How many clicks activate a row: Click::Single, the default, selects and activates at once; Click::Double only selects on a click and activates on a second press on the same row within Click::INTERVAL. Enter activates either way.

pub fn multi_select( self, selected: &[usize], message: impl Fn(Vec<usize>) -> Msg + 'static, ) -> Self

Lets several rows be selected at once: selected holds their indexes and message(rows) asks the application to make rows the whole new selection.

The row given to selected stays the cursor: the row the keys move from and the only one with the pillar, while every selected row takes the selection tone. Ctrl+click adds a row or takes it out, Shift+click selects the rows from the last plain or Ctrl click to this one, Space adds or takes out the cursor’s row and a plain click selects that one row. A right click on a selected row keeps the selection for its menu; on another row it makes that row the selection first.

pub fn box_select(self, on: bool) -> Self

Lets a drag from the free space below the rows draw a box: the rows it covers become the selection while it is drawn, or join it when Ctrl was held at the press, and a click there without a drag clears the selection. The box is a tone laid over the cells it covers, never a frame. It needs multi_select and does nothing without it.

pub fn droppable( self, message: impl Fn(RowDrop) -> Msg + 'static, accepts: impl Fn(usize) -> bool + 'static, ) -> Self

Lets rows be dragged onto other rows, such as files onto a folder: accepts(index) tells whether a row takes drops and message(RowDrop) asks the application to move the rows.

A drag carries the pressed row, or the whole selection when it is pressed on one of its rows; a click on a selected row without a drag makes it the one selected row on release. The row under the pointer takes the accent tone while it can take the drag. A release anywhere else, or on one of the dragged rows, does nothing. With Click::Single a row activates on release rather than on press, so pressing a row to drag it does not activate it.

pub fn on_copy_drop(self, message: impl Fn(RowDrop) -> Msg + 'static) -> Self

A drop released with Ctrl held asks for a copy with message instead of the move of droppable, the way a file explorer copies. A terminal that does not report Ctrl with the pointer always moves. It does nothing without droppable.

Trait Implementations

impl<Msg: 'static> Widget<Msg> for Table<Msg>

fn measure(&self, _cx: &mut MeasureCx<'_>, available: Size) -> Size

The size the widget wants when it may use up to available.

fn paint(&self, cx: &mut PaintCx<'_>, area: Rect)

Draws the widget into area.

fn paint_overlay(&self, cx: &mut PaintCx<'_>, anchor: Rect)

Draws the widget’s overlay after the whole view was painted, when it asked for one with PaintCx::request_overlay. anchor is the area the widget was painted in.

fn event(&self, cx: &mut EventCx<'_, Msg>, event: &Event) -> bool

Handles input. Returns true when the event was used; unused key and scroll events bubble to the parent widget.

fn focusable(&self) -> bool

Whether the widget can take keyboard focus.

fn children(&self) -> &[Node<Msg>]

Child nodes, for widgets that contain other widgets.

fn children_mut(&mut self) -> &mut [Node<Msg>]

Mutable child nodes, used to assign ids.