Struct TableView 

pub struct TableView<T: 'static> { /* private fields */ }

Generic, virtualized, accessible table with sortable / filterable / resizable columns.

Construct with TableView::new (from a ListModel<T>) or TableView::from_source (any ListDataSource), then chain builder methods to configure columns, row heights, selection, and so on. See module docs for the full feature list and row-height modes.

Implementations

impl<T: 'static> TableView<T>

pub fn new(model: ListModel<T>) -> Self

Wrap a ListModel<T>.

pub fn from_source<S: ListDataSource<Item = T>>(source: S) -> Self

Wrap any ListDataSource<Item = T> (e.g. a SortFilterListModel<T>).

The source owns DnD validation (can_accept / accept_drop) and lazy windowing (row_state / request_window / fetch_more); a read-only source leaves the defaults inert.

pub fn from_source_keyed<S: ListDataSource<Item = T>>( source: S, keyed: KeyedSelectionModel<S::Key>, ) -> Self

where S::Key: ItemKey,

Wrap any ListDataSource<Item = T> with keyed row selection. The KeyedSelectionModel<S::Key> tracks selection by source identity, so it survives reorders / filters / lazy window-slides and stays consistent across two views of the same source. The view stays TableView<T> — the index↔key mapping is captured from the concrete source here. Equivalent to from_source(..) plus an identity-based replacement for selection.

pub fn enabled(self, enabled: impl Into<Prop<bool>>) -> Self

Enable or disable the whole view. A disabled view greys out and stops accepting focus / selection / keyboard input (arena-gated).

pub fn overscroll_behavior(self, behavior: OverscrollBehavior) -> Self

Set the scroll-chaining behavior at the boundary (default OverscrollBehavior::Chain; Contain disables chaining to an ancestor scrollable).

pub fn smooth_scrolling(self, enabled: bool) -> Self

Enable or disable animated wheel scrolling (enabled by default). When disabled, wheel events snap immediately to the new offset.

pub fn type_ahead_label(self, label: impl Fn(&T) -> String + 'static) -> Self

Enable type-ahead (“type to jump”): typing a printable character while the table has keyboard focus jumps the focused row to the next row whose label starts with the accumulated search term, wrapping around (Qt keyboardSearch / macOS & Windows type-select). label(&item) yields the searchable text for a row; matching is ASCII-case-insensitive. A pause longer than the type_ahead_timeout starts a fresh term.

On an editable column whose EditTriggers is type-to-edit, typing starts an edit instead — type-ahead applies on non-editable columns (or when no type-to-edit trigger is configured).

pub fn type_ahead_timeout(self, timeout: Duration) -> Self

Reset window between keystrokes before the type-ahead search term clears (default 500 ms). A zero duration disables type-ahead.

pub fn smooth_scroll_duration(self, duration: Duration) -> Self

Duration of the smooth scroll animation (default 150 ms).

pub fn scroll_bar_style(self, style: ScrollBarMode) -> Self

How the scroll bar is displayed (default Permanent). Overlay and Thin float the bar over the content instead of reserving a layout column for it, mirroring ScrollArea::scroll_bar_style.

pub fn add_column(self, col: Column<T>) -> Self

Append a single Column<T> definition to the table.

pub fn columns(self, cols: impl IntoIterator<Item = Column<T>>) -> Self

Append multiple Column<T> definitions from an iterator.

pub fn row_height(self, height: f32) -> Self

Fixed row height (default: the table style’s 28 px) — the uniform fast path. Mutually exclusive with row_height_fn and auto_row_height; the last mode setter wins.

pub fn row_height_fn(self, f: impl Fn(usize) -> f32 + 'static) -> Self

Per-row heights from a callback over the visible row index. The callback must be pure (same index + same data → same height); it is re-swept from the first changed index on every model change (a SortFilterListModel source reports that index through first_changed_index, so sort/filter/append keep the valid prefix). No measurement pass runs.

pub fn auto_row_height(self, estimated: f32) -> Self

Auto-measured row heights: each realized row reports the height of its tallest cell measured at the cell’s column width (height-for-width), unrealized rows assume estimated. Scroll anchoring keeps content above the viewport stationary as estimates are corrected; the scrollbar settles one frame after a measurement change.

pub fn header_height(self, height: f32) -> Self

Override the column header row height in logical pixels. Default: the table style’s HEADER_HEIGHT.

pub fn show_header(self, visible: bool) -> Self

Show or hide the column header row. Default: visible.

pub fn column_resize_policy(self, policy: ColumnResizePolicy) -> Self

Set how column widths are redistributed when columns are added, resized, or the table’s own width changes. See ColumnResizePolicy.

pub fn tab_traversal(self, mode: TabTraversal) -> Self

Control how Tab / Shift+Tab navigate between cells. See TabTraversal.

pub fn edit_triggers(self, trigger: EditTriggers) -> Self

Set which user action opens a cell editor. See EditTriggers.

pub fn on_cell_edit_request( self, f: impl Fn(usize, &str, &mut EventContext<'_>) + 'static, ) -> Self

Hook fired by the keyboard handler when an edit trigger fires on the focused cell. Receives (row_index, col_id, ctx).

pub fn on_cell_edit_dismissed( self, f: impl Fn(usize, &str, &mut EventContext<'_>) + 'static, ) -> Self

Callback invoked when an open cell editor should end because the pointer went somewhere else: a press that lands on any cell other than the one being edited. Receives the editing cell’s flat row index and column id, so the owner can commit (or discard) whatever is in its buffer, then clear its own editing state.

The counterpart of on_cell_edit_request, and the view cannot do it alone: the framework owns which cell is being edited, but only the owner knows what an ended edit means — commit, discard, or refuse a value that will not parse.

Why a press and not a focus change. “The editor lost focus” is the obvious signal and it cannot be used: a body pane rebuilds constantly — selection, filtering, scroll, a reload from elsewhere — and every rebuild destroys and re-creates the open editor, so focus leaves it many times during an edit the writer never interrupted. A press on another cell is unambiguous and happens exactly once.

pub fn on_row_activate( self, f: impl Fn(usize, &mut EventContext<'_>) + 'static, ) -> Self

Hook fired when the user presses Enter on the focused row.

pub fn reorderable(self, enabled: bool) -> Self

Enable drag-to-reorder of rows (pointer drag + keyboard Alt+ArrowUp/Down). Distinct from Column::reorderable, which reorders columns and defaults to true; this defaults to false.

The move is routed through the backing source’s accept_drop: a ListModel reorders in place, an external source routes the move to its store. Per-hover the source’s can_accept decides whether the drop is allowed — a forbidden position shows no insertion line and the drop is refused. A row may also be forbidden from dragging at all (the source’s drag gate). Cross-table / external drops arrive at accept_drop as DragSource::Foreign; a bare ListModel rejects them, an external source decides.

pub fn reorderable_rows(self, enabled: bool) -> Self

👎Deprecated since 0.6.3:

renamed to reorderable

Renamed to reorderable, matching ListView, GridView, TreeView and TreeTableView — this was the only view in the family spelling it differently.

pub fn exportable(self, mode: DragTransferMode) -> Self

where T: Clone,

Make rows droppable outside this view — on a DropTarget, another data view, or the OS.

A dragged row (or the whole selection, when the pressed row is part of a multi-selection) carries clones of its items in a public RowDragData<T>, so a foreign receiver can pull them out with payload.get_typed::<RowDragData<T>>() / DropTarget::on_drop_typed::<RowDragData<T>>() — no serialization. This also makes rows a drag source even without reorderable.

mode chooses what happens to the origin rows once a foreign target accepts them: DragTransferMode::Move removes them (via the source’s on_drag_out, or on_rows_transferred_out), DragTransferMode::Copy leaves them. A same-view reorder is never a transfer, so mode never affects it. Requires T: Clone.

pub fn export_external( self, f: impl Fn(&[T]) -> Vec<(String, Vec<u8>)> + 'static, ) -> Self

where T: Clone,

Additionally advertise the dragged rows as MIME data so they can be dropped on a DropZone or exported to another application / window via the OS. f maps the dragged items to (mime_type, bytes) pairs (e.g. text/plain, text/uri-list, an app-specific application/x-…). Implies exportable (defaulting to DragTransferMode::Move if not already set). Requires T: Clone.

pub fn on_rows_transferred_out( self, f: impl Fn(&[usize], &mut EventContext<'_>) + 'static, ) -> Self

Override how rows moved out to a foreign target are removed from this view. Receives the dragged rows’ indices (descending-safe) and the live context. Without this, an exportable Move drag removes them through the source’s on_drag_out (works out of the box for a ListModel).

pub fn accept_foreign_rows(self, accept: bool) -> Self

Accept exported rows dropped from a different view or source without writing a custom ListDataSource. Pair with on_rows_received, which is handed the dropped items and the insertion index. (Same-view reorder is reorderable; a custom ListDataSource can still accept foreign drops through its can_accept/accept_drop instead.)

pub fn on_rows_received( self, f: impl Fn(Vec<T>, usize, &mut EventContext<'_>) + 'static, ) -> Self

Handler for rows accepted via accept_foreign_rows: (items, insertion_index, ctx). Insert them into your model at the index.

pub fn activate_on(self, mode: ActivateOn) -> Self

Choose single- vs double-click activation for on_row_activate (default ActivateOn::DoubleClick). Enter/Space activates in either mode.

pub fn selection_mode(self, mode: TableSelectionMode) -> Self

Choose the row-selection granularity (None / Single / Multi). See TableSelectionMode.

pub fn selection(self, sel: SelectionModel) -> Self

Set the index-based row selection model (positions). For identity-based selection that survives reorder / filter / window-slide, build the view with from_source_keyed instead.

pub fn cell_selection(self, sel: CellSelectionModel) -> Self

Install an independent cell-selection model on top of row selection. See CellSelectionModel.

pub fn alternating_rows(self, enabled: bool) -> Self

Paint every other row with a tinted background. Default: off.

pub fn grid_lines(self, kind: GridLines) -> Self

Draw horizontal and/or vertical grid lines between cells. See GridLines.

pub fn a11y_label(self, label: impl Into<LocalizedString>) -> Self

Provide an accessible label for the table (aria-label). Required when the page hosts more than one table so screen readers can distinguish them.

pub fn show_internal_scrollbars(self, show: bool) -> Self

Show or hide the built-in vertical scroll bar. Default: visible. Set to false when an external scroll bar is wired to scroll_y_signal.

pub fn empty_view(self, f: impl Fn() -> Box<dyn Widget> + 'static) -> Self

Widget shown when the source is empty.

pub fn scroll_y_signal(&self) -> &Signal<f32>

Current vertical scroll offset in logical pixels.

pub fn max_scroll_y_signal(&self) -> &Signal<f32>

Maximum vertical scroll offset — total_content_height − viewport_height.

pub fn viewport_ratio_y_signal(&self) -> &Signal<f32>

Viewport-to-content height ratio, used by external scroll bar thumbs.

pub fn scroll_x_signal(&self) -> &Signal<f32>

Current horizontal scroll offset of the Middle (unpinned) pane, in logical pixels. Leading/Trailing-pinned columns are unaffected — see Column::pinned.

pub fn max_scroll_x_signal(&self) -> &Signal<f32>

Maximum horizontal scroll offset — middle_content_width − middle_viewport_width.

pub fn viewport_ratio_x_signal(&self) -> &Signal<f32>

Middle-pane viewport-to-content width ratio, used by external horizontal scroll bar thumbs.

pub fn sort_signal(&self) -> &Signal<Option<(String, SortDirection)>>

Active sort: Some((col_id, dir)) or None when unsorted. Mutated by header clicks (cycle: None → Asc → Desc → None) and by set_sort / clear_sort. Bind a SortFilterListModel to drive a re-sort of the underlying data:

let proxy = SortFilterListModel::new(model)
    .with_comparator("name", |a, b| a.name.cmp(&b.name));
proxy.sort_signal(table.sort_signal().clone());

pub fn column_widths_signal(&self) -> &Signal<HashMap<String, f32>>

Map of column id → user-overridden width. A column id appears in this map only after the user resizes that column; missing keys mean “use the declared width policy”.

pub fn column_order_signal(&self) -> &Signal<Vec<String>>

Column ids in display order. Updated when the user drags a header to reorder, or imperatively via set_column_order. When empty, the declared order applies. Pinned-side groups (Leading / None / Trailing) are always honored — the entries inside this signal only re-sort within each group.

pub fn column_pinning_signal(&self) -> &Signal<HashMap<String, PinnedSide>>

Per-id pinning override map. A key here pins the column to that side; missing keys fall back to the declared Column::pinned. Updated when the user drags a column across a pane boundary.

pub fn focused_cell_signal(&self) -> &Signal<Option<(usize, usize)>>

Currently keyboard-focused cell, as (row_index, display_col), or None when no cell is focused. Mutated by the keyboard handler (Arrow keys / Tab / Home / End / PgUp / PgDn / Ctrl-Home / Ctrl-End / Escape) and by direct set_focused_cell / clear_focused_cell calls.

pub fn set_focused_cell(&self, row: usize, col: usize)

Move the focused cell. Out-of-range values are silently clamped when the next layout runs.

pub fn clear_focused_cell(&self)

Remove keyboard focus from any cell (equivalent to pressing Escape).

pub fn editing_cell_signal(&self) -> &Signal<Option<(usize, usize)>>

Cell currently in edit mode, or None when no editor is open. Cell delegates inspect this via CellContext::is_editing and swap in an editor widget when matched.

pub fn begin_edit(&self, row: usize, col_id: &str)

Begin editing the cell (row, col_id). Silently no-ops if col_id isn’t a currently-displayed column, or if row is outside the visible range — an out-of-range target would otherwise strand editing_cell on a row nothing can match.

Callable before the view is mounted, which is the only point at which a consumer can seed a freshly constructed view with an edit target it already holds. display_indices is a cache build() fills, so a pre-mount call finds it empty; the order is recomputed on demand in that case rather than resolving against nothing and no-opping for a third, undocumented reason.

pub fn end_edit(&self)

Close the active cell editor without committing (the field’s on_blur still fires).

pub fn filters_signal(&self) -> &Signal<HashMap<String, String>>

Per-column filter text. Updated by filter affordances in header cells and by set_filter / clear_filters. Bind a SortFilterListModel<T> to drive the upstream data:

let proxy = SortFilterListModel::new(model)
    .with_predicate("name", |t| {
        let needle = t.to_string();
        Box::new(move |r: &Row| r.name.contains(&needle))
    });
proxy.filters_signal(table.filters_signal().clone());

pub fn set_filter(&self, col_id: &str, text: &str)

Set or clear the filter text for a single column. An empty text removes the entry for col_id (same as clearing the filter for that column).

pub fn clear_filters(&self)

Remove all active column filters.

pub fn scroll_to_row(&self, row: usize)

Scroll so that row is aligned to the top of the viewport. A no-op before the first layout pass.

pub fn set_sort(&self, col_id: Option<&str>, dir: SortDirection)

Set the active sort imperatively. Equivalent to writing to sort_signal directly, except that an unchanged value neither writes nor notifies — see set_column_widths.

pub fn clear_sort(&self)

Clear the active sort.

pub fn set_column_width(&self, col_id: &str, width: f32)

Set or remove a single column’s user-resized width override. A non-positive width removes the entry (the column reverts to its declared width policy).

pub fn set_column_widths(&self, widths: HashMap<String, f32>)

Replace the full width-override map (typically used to restore a persisted layout).

A no-op when the map is unchanged, so the documented settings-round-trip wiring (see docs/table-view.md, “Persistence”) terminates instead of recursing: Signal::set has no equality check of its own, and a live resize writes a width on every pointer move.

pub fn set_column_order(&self, order: Vec<String>)

Replace the column-order list. Ids not declared on this table are silently dropped on the next layout pass.

pub fn set_column_pinning(&self, col_id: &str, side: PinnedSide)

Pin or unpin a single column.

pub fn ensure_row_visible(&self, row: usize)

Scroll the minimum distance needed to make row visible. A no-op before the first layout pass, when the viewport height is not yet known.

Trait Implementations

impl<T: 'static> Debug for TableView<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: 'static> Widget for TableView<T>

fn build(&mut self, ctx: &mut BuildContext<'_>) -> Vec<WidgetId>

Compose child widgets. Called once after the widget is placed in the arena, and again on environment change (theme switch, locale switch). Takes &mut self — store child IDs, signal handles, any state needed later. Returns the list of root child IDs (empty for leaf widgets).

fn layout_response( &self, proposal: SizeProposal, _ctx: &LayoutContext<'_>, ) -> LayoutResponse

Respond to the parent’s size proposal with this widget’s wanted size, grow/shrink weights, and compression floor (see [LayoutResponse]).

fn place_children( &self, bounds: Rect, _proposal: SizeProposal, children: &mut [WidgetPlacement], ctx: &LayoutContext<'_>, )

Position children within the allocated bounds.

fn paint(&self, bounds: Rect, canvas: &mut Canvas, ctx: &PaintContext<'_>)

Draw the widget’s visual representation.

fn accessibility(&self, builder: &mut AccessNodeBuilder)

Declare this widget’s accessibility identity.

fn as_any(&self) -> Option<&dyn Any>

Downcast hook. Default implementation returns None; concrete widgets override with Some(self) when they want to expose their concrete type to test-level introspection or reflection. The trait already bounds on std::any::Any so concrete types satisfy the 'static requirement.

fn children(&self) -> Vec<WidgetId>

Return the child widget IDs that this widget manages.

fn accessibility_children(&self) -> Option<Vec<WidgetId>>

Optional override for the child ORDER presented to assistive technology, when it must differ from the paint / z-order child order returned by children.

fn clips_children(&self) -> bool

Whether this widget clips its children to its bounds.

fn type_name(&self) -> &'static str

Concrete type name of this widget (e.g. "teksilo_widgets::button::Button"). The default implementation resolves at the impl site via std::any::type_name::<Self>(), so calls through &dyn Widget correctly dispatch to the monomorphized fn for the concrete type — getting the concrete name through the vtable without per-impl boilerplate.

fn cacheable_layout(&self) -> bool

Whether this widget’s layout_response may be memoized by the per-pass layout cache. Defaults to true.

fn wants_after_paint(&self) -> bool

Whether this widget wants its after_paint hook to fire each frame. Returning false (the default) saves a virtual call per widget per frame for the vast majority of widgets that don’t aggregate descendant geometry.

fn after_paint(&self, _view: &WidgetTreeView<'_>, _ctx: &PaintContext<'_>)

Called once per frame after this widget’s subtree has finished painting. Receives a read-only view of the layout-resolved arena so a parent can read its descendants’ final bounds — e.g. TitleBar aggregates its drag region and control-button rects into a single HitRegions payload for the Windows backend’s WM_NCHITTEST.

fn wants_post_paint(&self) -> bool

Whether this widget wants its post_paint hook to fire each frame. Returning false (the default) saves a virtual call per widget per frame for the vast majority of widgets that don’t draw a foreground over their children.

fn post_paint( &self, _bounds: Rect, _canvas: &mut Canvas, _ctx: &PaintContext<'_>, )

Draw a foreground layer over this widget’s children.

fn wants_descendant_redirects(&self) -> bool

Whether this widget wants the AT walker to consult its a11y_redirect_descendant hook for every descendant during AT tree emission, not just its direct arena children.

fn a11y_redirect_descendant( &self, _self_id: WidgetId, _descendant: WidgetId, ) -> Option<NodeId>

Optional redirection hook for AT-tree placement of a child.

fn accessible_title_hint(&self) -> Option<String>

Suggest an accessible title to an enclosing container that wraps this widget as content — typically a modal / dialog shell that wants to propagate the inner content’s visible title as the shell’s own accessible name.

fn initial_focus_hint(&self) -> Option<WidgetId>

Optional hint that directs initial focus to a specific descendant when this widget is the root of a deferred-built modal surface.

fn as_any_mut(&mut self) -> Option<&mut (dyn Any + 'static)>

Mutable counterpart of as_any. Default returns None; widgets that want to expose mutable state to tests (e.g. so a test can mutate a Scene inside a SceneView post-layout) override with Some(self). Should follow the same opt-in pattern as as_any: only widgets that opt into & introspection should opt into &mut.

fn focus_reveal_rect(&self, _bounds: Rect) -> Option<Rect>

The rectangle (in absolute tree coordinates) that best represents this widget when the framework reveals it into an ancestor scroll area on focus gain. Returning None (the default) reveals the widget’s whole bounds — correct for most controls.

fn hit_shape(&self, _local_point: Point, _bounds: Rect) -> bool

Whether the point lies inside this widget’s actual shape, not just its rectangular bounds. Consulted by hit-testing right after the bounds check: returning false for a point that is inside the bounding box makes the widget transparent to the click there, so it falls through to whatever sibling is painted underneath (the same machinery as a fully pass-through node, but shape-aware).

fn preserves_children_on_rebuild(&self) -> bool

How rebuild_single_widget treats this widget’s existing children when re-running its build().

fn tooltip_has_content(&self) -> bool

Whether this widget, used as tooltip content, currently has anything worth showing.

fn declare_shortcuts(&self) -> Vec<Shortcut>

Declare the rebindable keyboard shortcuts this widget exposes, without installing handlers. The framework calls this at arena insertion time (before build()) and at certain lazy boundaries (e.g. Switcher walks declarations on its not-yet-mounted Pending slots), so settings UIs and the ShortcutRegistry see the keystrokes the moment the owning container mounts — even if build() hasn’t run.

fn take_handler_set(&mut self) -> Option<HandlerSet>

Extract attached handler set from a WidgetWithHandlers wrapper. Called during arena insertion to transfer handlers to the WidgetNode. Default: returns None (no attached handlers).