Struct Table 

pub struct Table<S: RowSource, Msg = ()> {
    pub page_size: usize,
    pub zebra_striping: bool,
    pub column_order: Vec<usize>,
    pub column_widths: Vec<f32>,
    pub column_filters: Vec<String>,
    pub pinned_columns: usize,
    pub row_background: Option<Box<dyn Fn(usize) -> Option<[u8; 4]> + Send + Sync>>,
    /* private fields */
}

A virtualized table widget backed by a RowSource.

The optional second type parameter Msg (default ()) is the application’s message type. When Msg is not (), use Table::on_message to attach a handler that is called whenever the table emits an application-level message.

Only rows visible within the current scroll viewport (plus a configurable overscan region) are materialized, keeping CPU and memory usage constant regardless of the total row count.

Column attributes that the frozen ColumnDef struct does not carry (per-column alignment, sortability, runtime width) are stored on the table itself, keyed by column index.

Fields

page_size: usize

Number of rows shown per pagination page. 0 means pagination is disabled.

zebra_striping: bool

Whether to render alternate rows with a slightly different background color.

column_order: Vec<usize>

Column render order: column_order[i] is the logical column index rendered in position i. Defaults to the identity permutation.

column_widths: Vec<f32>

Runtime column widths (logical pixels). Initialized from column_defs().width and updated by Table::resize_column. Renderers should prefer this over the source’s ColumnDef::width so that user resize drags are reflected.

column_filters: Vec<String>

Per-column filter text strings (empty = no filter). Indexed by logical column index. Update with Table::set_column_filter.

pinned_columns: usize

Number of leftmost columns to pin (freeze) during horizontal scrolling.

row_background: Option<Box<dyn Fn(usize) -> Option<[u8; 4]> + Send + Sync>>

Optional per-row background colour callback.

Called with the visible row index. Return Some([r, g, b, a]) to paint a custom row background, or None to fall back to the default (zebra striping or theme background).

Implementations

impl<S: RowSource> Table<S>

pub fn new(source: S) -> Self

Create a new Table wrapping source with default settings.

Default row_height is 24.0 pixels; default overscan is 3 rows. Pagination is disabled by default (page_size = 0), zebra striping is off, and the column order is the identity permutation.

The message type Msg defaults to (). To use a different message type, specify the Msg type parameter explicitly when constructing Table.

impl<S: RowSource, Msg> Table<S, Msg>

pub fn with_page_size(self, size: usize) -> Self

Set the number of rows per pagination page. 0 disables pagination.

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

Enable or disable zebra row striping.

pub fn with_column_order(self, order: Vec<usize>) -> Self

Override the column render order. Each element is a logical column index. If order is shorter than the number of columns, trailing columns are appended in their natural order.

pub fn with_row_height(self, h: f32) -> Self

Set a uniform height for all rows in logical pixels.

Also updates the CumulativeHeightCache so that Table::cache_visible_range and Table::cache_row_at_offset reflect the new height.

pub fn with_row_heights(self, heights: Vec<f32>) -> Self

Set per-row heights (variable-height rows) and update the cumulative height cache.

heights[i] is the height of row i in logical pixels. If heights is shorter than row_count, missing rows fall back to whatever height was previously configured.

pub fn cache_row_at_offset(&mut self, y: f32) -> usize

Return the row index whose vertical span contains scroll offset y, using the CumulativeHeightCache for O(log n) lookup.

pub fn cache_visible_range( &mut self, viewport_y: f32, viewport_h: f32, ) -> Range<usize>

Return the range of rows at least partially visible in the viewport [viewport_y, viewport_y + viewport_h), using the cumulative height cache.

pub fn get_or_fetch_row(&mut self, idx: usize) -> Vec<Cell>

Fetch row idx from the cache if present, or materialise it from the source, insert it into the cache, and return the cells.

pub fn invalidate_row_cache(&mut self)

Invalidate the row cache. Call after any mutation to the underlying source.

pub fn with_overscan(self, overscan: usize) -> Self

Set the overscan — extra rows to render beyond the visible viewport on each edge to avoid flash-of-empty-row when scrolling quickly.

pub fn with_sticky_headers(self, sticky: bool) -> Self

Enable or disable sticky column headers.

When sticky is true, the header row is always rendered at the top of the visible viewport (y = 0), regardless of the current vertical scroll offset. Data rows are offset by Table::header_height so they begin below the pinned header. Table::visible_range also subtracts the header height from the effective viewport height to virtualize the correct number of data rows.

pub fn with_header_height(self, h: f32) -> Self

Set the height of the header row in logical pixels.

Defaults to 32.0. Only used when Table::sticky_headers is true.

pub fn header_height(&self) -> f32

Return the configured header row height in logical pixels.

pub fn sticky_headers(&self) -> bool

Return whether sticky column headers are enabled.

pub fn header_origin_y(&self, v_scroll: f32) -> f32

Compute the Y position at which the header row should be rendered.

When sticky headers are enabled, this always returns 0.0 so that the header stays pinned to the top of the viewport. When disabled, the header scrolls with the content: its position is -v_scroll (i.e. the header is above the viewport when the user has scrolled down).

pub fn data_row_origin_y(&self, row: usize, v_scroll: f32) -> f32

Compute the Y position at which the top of data row should be rendered.

When sticky headers are enabled, data rows are pushed down by Table::header_height so they start below the pinned header. The scroll offset is subtracted so that rows outside the viewport scroll out of view.

Formula: header_offset + row * row_height - v_scroll, where header_offset is header_height when sticky and 0.0 otherwise.

pub fn render_header(&self, origin_y: f32) -> Vec<RenderedCell>

Produce a Vec of RenderedCell values representing the column header row positioned at origin_y.

Columns are laid out left-to-right according to column_order, using per-column widths from Table::effective_width. The text field of each RenderedCell is the crate::ColumnDef::name of the column.

Pass origin_y = 0.0 for a sticky header that is always pinned to the top of the viewport, or origin_y = self.header_origin_y(v_scroll) to let the header scroll with the content.

pub fn with_column_align(self, column: usize, align: CellAlign) -> Self

Set the alignment for column. Columns without an explicit alignment use the per-cell default (CellAlign::default_for).

pub fn with_column_sortable(self, column: usize, sortable: bool) -> Self

Mark whether column may be sorted by clicking its header.

pub fn with_pinned_columns(self, n: usize) -> Self

Set the number of leftmost columns to pin (freeze) during horizontal scrolling.

pub fn with_row_background<F>(self, f: F) -> Self

where F: Fn(usize) -> Option<[u8; 4]> + Send + Sync + 'static,

Attach a per-row background colour callback.

f(vis_row) should return Some([r, g, b, a]) for rows that need a custom background, or None to fall back to the default (zebra / theme) colour.

pub fn column_align(&self, column: usize, cell: &Cell) -> CellAlign

Resolve the alignment for a cell in column: the explicit override if set, otherwise the cell’s natural default.

pub fn is_column_sortable(&self, column: usize) -> bool

Returns true if column is sortable (default true).

pub fn sort_state(&self) -> Option<SortState>

The current sort state, if any.

pub fn toggle_sort(&mut self, column: usize) -> Option<SortState>

Toggle sorting on column, cycling None→Asc→Desc→None. Sorting a different column resets to ascending. No-op if the column is not sortable. Returns the resulting SortState (or None when cleared).

pub fn sorted_indices(&self) -> Vec<usize>

Compute the current row-index ordering, applying the active sort if any. Returns the identity order when unsorted.

pub fn filtered_sorted_indices(&self) -> Vec<usize>

Apply the per-column filters to sorted_indices and return the matching subset. An empty column_filters entry is treated as “no filter” (matches all rows).

Returns the full sorted index when no filter is active.

pub fn set_column_filter(&mut self, col: usize, text: String)

Update the per-column filter text for col.

An empty string clears the filter for that column. No-op if col is out of range.

pub fn resize_column(&mut self, col: usize, delta_px: f32) -> Option<f32>

Apply a resize delta delta_px to col, clamping to the column’s min_width / max_width / resizable constraints.

Returns the new effective width, or None if:

• col is out of range for column_widths, or
• the column’s ColumnDef marks it non-resizable.

pub fn effective_width(&self, col: usize) -> f32

Return the effective runtime width for col (logical pixels).

Falls back to the source’s ColumnDef::width if col is outside column_widths.

pub fn row_bg(&self, vis_row: usize) -> Option<[u8; 4]>

Return the background colour for vis_row, or None for the default.

Consults row_background if set; otherwise returns None. Renderers apply zebra striping independently from this callback.

pub fn row_count(&self) -> usize

Return the total number of rows from the source.

pub fn source(&self) -> &S

Return a reference to the underlying RowSource.

pub fn row_height(&self) -> f32

Return the configured row height in logical pixels.

pub fn visible_range( &self, viewport_height: f32, scroll_offset: f32, ) -> Range<usize>

Calculate which rows are visible for a viewport of height viewport_height starting at scroll_offset pixels from the top.

The returned range is clamped to 0..row_count().

When Table::sticky_headers is true, the effective viewport height for data rows is reduced by Table::header_height (the header occupies the top portion of the viewport). The scroll offset is not adjusted — it still refers to the position within the data content.

pub fn materialize_visible( &self, viewport_height: f32, scroll_offset: f32, ) -> Vec<Vec<Cell>>

Materialize only the visible rows for the given viewport parameters.

Each returned inner Vec<Cell> corresponds to one row. Rows outside the visible range are never fetched from the source.

pub fn to_csv_all(&self, filters: &[ColumnFilter]) -> String

Export all rows (after optional filter+sort, ignoring pagination) to CSV.

Pass a non-empty filters slice to restrict to matching rows; pass an empty slice to export every row. The output uses ',' as the delimiter and follows RFC-4180 quoting.

pub fn to_csv_visible( &self, page: &PaginationState, filters: &[ColumnFilter], ) -> String

Export visible rows (after filter+sort+pagination) to CSV.

page is the PaginationState governing which page is visible. filters may be empty (no filtering).

impl<S: RowSource, Msg> Table<S, Msg>

pub fn visible_column_range( &self, h_scroll: f32, viewport_width: f32, ) -> Range<usize>

Compute the range of column indices that are at least partially visible within a horizontal viewport.

h_scroll is the current horizontal scroll offset (logical pixels from the left edge of the first column). viewport_width is the visible width in logical pixels.

The returned range is suitable for slicing column_order or iterating directly: range.start..range.end gives the first and one-past-last column render position whose pixel span overlaps [h_scroll, h_scroll + viewport_width).

Columns widths are read from column_widths via effective_width, so user resize deltas are reflected correctly.

Returns an empty range (n..n) when:

• There are no columns.
• h_scroll is beyond the total column extent.

impl<S: RowSource, Msg> Table<S, Msg>

pub fn on_message<F: FnMut(Msg) + Send + 'static>(self, f: F) -> Self

Attach an application-message handler.

f is called (via Table::dispatch_message) whenever the table produces a Msg value. This is the escape hatch for integrating the table into an Elm-style message-passing architecture without wrapping every table event in a manual .map() call.

Example

table.on_message(|msg: MyAppMsg| sender.send(msg).ok());

pub fn dispatch_message(&mut self, msg: Msg)

Dispatch a Msg value to the registered handler, if any.

No-op when no handler has been attached via Table::on_message.

Trait Implementations

impl<S: RowSource, Msg> Widget for Table<S, Msg>

fn render(&mut self, ui: &mut dyn UiCtx)

Render a simplified text representation of the table via a UiCtx.

Each visible row (up to 100) is rendered as a single label whose cells are joined by " | ". This makes Table embeddable in any UI backend that implements UiCtx without requiring the egui or iced feature flags.

fn a11y_role(&self) -> A11yRole

Return the accessibility role for this widget.

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

Return a human-readable accessibility label for this widget.

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

Return an accessibility description (longer hint text) for this widget.