Struct LiveGridState 

pub struct LiveGridState<D: LiveGridDelegate> { /* private fields */ }

The state and view of a live grid.

Implementations

impl<D: LiveGridDelegate> LiveGridState<D>

pub fn with_change_paint(self, paint: ChangePaint) -> Self

Sets how highlighted changes paint cells (default ChangePaint::Uniform).

pub fn set_change_paint( &mut self, paint: ChangePaint, cx: &mut Context<'_, Self>, )

Replaces how highlighted changes paint cells, as a “Show direction” switch does. The next frame paints with it; nothing is rebuilt.

pub fn change_paint(&self) -> &ChangePaint

How highlighted changes paint cells.

impl<D: LiveGridDelegate> LiveGridState<D>

pub fn with_column_move_policy(self, policy: impl ColumnMovePolicy) -> Self

Sets how columns and bands move (default BandedMove; see also FreeMove). The schema’s order is normalized by the new policy.

pub fn with_autofit_policy(self, policy: impl AutofitPolicy) -> Self

Sets how autofit measures a column (default VisibleRowsAutofit).

pub fn columns( &self, ) -> impl Iterator<Item = <<D as LiveGridDelegate>::Row as GridRow>::Column> + '_

Every schema column in display order (left, scrolling, right zone), hidden ones included at their place.

pub fn visible_columns( &self, ) -> impl Iterator<Item = <<D as LiveGridDelegate>::Row as GridRow>::Column> + '_

Visible columns in display order; the n-th has ViewColumnIx::new(n).

pub fn column_width( &self, column: <<D as LiveGridDelegate>::Row as GridRow>::Column, ) -> Pixels

The width of column (zero if it is not in the schema).

pub fn is_column_visible( &self, column: <<D as LiveGridDelegate>::Row as GridRow>::Column, ) -> bool

Returns true if column is shown.

pub fn column_zone( &self, column: <<D as LiveGridDelegate>::Row as GridRow>::Column, ) -> ColumnZone

The zone of column.

pub fn view_column_ix( &self, column: <<D as LiveGridDelegate>::Row as GridRow>::Column, ) -> Option<ViewColumnIx>

The on-screen position of column; None if it is hidden.

pub fn column_at( &self, ix: ViewColumnIx, ) -> Option<<<D as LiveGridDelegate>::Row as GridRow>::Column>

The visible column at an on-screen position.

pub fn current_column( &self, ) -> Option<<<D as LiveGridDelegate>::Row as GridRow>::Column>

The column that column commands (the column Actions) act on: the last header cell or band pressed, or the column the focus moved to, whichever came last. None if there is none or it is hidden.

pub fn set_column_width( &mut self, column: <<D as LiveGridDelegate>::Row as GridRow>::Column, width: Pixels, cx: &mut Context<'_, Self>, )

Sets the width of column, kept within its limits. Emits one LayoutChange if it changed.

pub fn set_column_visible( &mut self, column: <<D as LiveGridDelegate>::Row as GridRow>::Column, visible: bool, cx: &mut Context<'_, Self>, ) -> bool

Shows or hides column; a shown column returns to its place. Returns false if refused: the last visible column cannot be hidden.

pub fn show_all_columns(&mut self, cx: &mut Context<'_, Self>)

Shows every column, with one LayoutChange.

pub fn set_column_zone( &mut self, column: <<D as LiveGridDelegate>::Row as GridRow>::Column, zone: ColumnZone, cx: &mut Context<'_, Self>, )

Moves column to zone, at the new zone’s edge nearest to its old place. The ColumnMovePolicy decides what moves along (with BandedMove, its whole top-level band).

pub fn move_column( &mut self, column: <<D as LiveGridDelegate>::Row as GridRow>::Column, before: Option<<<D as LiveGridDelegate>::Row as GridRow>::Column>, cx: &mut Context<'_, Self>, ) -> bool

Moves column before before (None: to the end of its zone). Returns false if the zones differ or the move policy refuses.

pub fn move_band( &mut self, band: &'static str, before: Option<<<D as LiveGridDelegate>::Row as GridRow>::Column>, cx: &mut Context<'_, Self>, ) -> bool

Moves every column of band in its zone before before (None: to the end of the zone). Returns false if the band is unknown, the zones differ or the move policy refuses.

pub fn autofit_column( &mut self, column: <<D as LiveGridDelegate>::Row as GridRow>::Column, cx: &mut Context<'_, Self>, )

Fits the width of column to its header and the rows painted in the next painted frame; the LayoutChange comes with that frame.

pub fn autofit_columns(&mut self, cx: &mut Context<'_, Self>)

Fits every visible column the same way, with one LayoutChange.

impl<D: LiveGridDelegate> LiveGridState<D>

pub fn with_column_chooser(self, factory: impl ColumnChooserFactory) -> Self

Sets what “Choose columns…” shows (default PopoverColumnChooser).

pub fn show_column_chooser( &mut self, window: &mut Window, cx: &mut Context<'_, Self>, )

Opens the column chooser below the right end of the header, its right edge at the header’s (ShowColumnChooser). The view is built after the current event. An open context menu closes.

pub fn show_column_chooser_at( &mut self, position: Point<Pixels>, window: &mut Window, cx: &mut Context<'_, Self>, )

Opens the column chooser with its top left at position (window coordinates), after the current event.

pub fn close_column_chooser( &mut self, window: &mut Window, cx: &mut Context<'_, Self>, )

Closes the column chooser the grid shows, and gives the grid the focus. Does nothing if none is open.

pub fn is_column_chooser_open(&self) -> bool

Returns true while the grid shows its column chooser.

impl<D: LiveGridDelegate> LiveGridState<D>

pub fn with_cell_export(self, export: CellExport<D::Row>) -> Self

Sets how one cell becomes text when copied, and when exported unless the export asks otherwise (ExportRequest::with_cell_export). The default is CellExport::Raw(RawCells::new()): raw numbers with a ., TRUE and FALSE; see also RawCells::with_decimal_separator and CellExport::Displayed.

pub fn with_exporter(self, exporter: impl Exporter<D::Row>) -> Self

Sets the clipboard format of a copy (default TsvExporter).

pub fn copy(&mut self, cx: &mut Context<'_, Self>) -> bool

Copies the command scope of the focused line in the shown order, without a header line (Copy, Cmd/Ctrl+C): on a group caption every row of its group that passes the view, those of collapsed subgroups included; otherwise Self::scoped_selection, which holds a row of a collapsed group only if it is selected. Summary rows are never in it. The visible columns are copied in screen order; in the cell modes only the columns that hold a selected cell, and the cells of that rectangle that are not selected are empty. Returns false, leaving the clipboard alone, if there is nothing to copy.

The same as copy_scope(ExportScope::Selection). A large copy is written by the task runner, and its text reaches the clipboard when the job is done.

pub fn copy_all(&mut self, cx: &mut Context<'_, Self>) -> bool

Copies every shown line in the shown order (a held order as it is on screen), every visible column in screen order, under a line of column titles (CopyAll): group captions, the rows of expanded groups and tree rows, group footers. The top band comes first, the totals row before its pinned rows, and the bottom band last, the totals row after its pinned rows. Returns false, leaving the clipboard alone, if there is no line, no pinned row and no totals row to copy.

The same as copy_scope(ExportScope::Visible). A large copy is written by the task runner, and its text reaches the clipboard when the job is done.

pub fn copy_scope( &mut self, scope: ExportScope, cx: &mut Context<'_, Self>, ) -> bool

Copies scope to the clipboard: Selection as Self::copy, Visible as Self::copy_all, Expanded as copy_all with every group and tree row expanded (the rows of collapsed groups under their captions, the footers of collapsed groups, every descendant of a collapsed tree row). Returns false, leaving the clipboard alone, if there is nothing to copy.

A group caption is written as its group’s key value under the level’s column, or under the first copied column when that column is hidden or the level groups by a GroupKey, and its aggregates under theirs; a footer and the totals row as their aggregates, the totals label in the first copied column when it has no aggregate. A totals row is copied when the grid shows one and the view has aggregates.

A large copy is written by the task runner, and its text reaches the clipboard when the job is done.

impl<D: LiveGridDelegate> LiveGridState<D>

pub fn export<W: Write + Send + 'static>( &mut self, request: ExportRequest<D::Row>, format: impl ExportFormat<D::Row>, sink: W, cx: &mut Context<'_, Self>, ) -> Result<ExportJob<W>, ExportError>

Writes request with format to sink, in a task runner job, and gives the sink back when it is done. The snapshot, the shown order (a held one included) with its expansion, the columns, the totals label and the optimistic values of waiting edits are taken now.

Returns Err(ExportError::Nothing) at once, without touching the sink, if the scope is empty (Self::is_export_empty), unless the request asks for the header line alone (EmptyExport::HeaderOnly). The job writes on the web too: a Vec<u8> sink there holds the bytes of the file the application lets the user save.

use gpui_kit::{Context, Task};
use gpui_kit_grid::{
    CsvFormat, ExportError, ExportRequest, ExportScope, LiveGridDelegate, LiveGridState,
};

/// The CSV text of the visible lines, once it is written.
fn csv_text<D: LiveGridDelegate>(
    grid: &mut LiveGridState<D>,
    cx: &mut Context<LiveGridState<D>>,
) -> Result<Task<Result<Vec<u8>, ExportError>>, ExportError> {
    let job = grid.export(
        ExportRequest::new(ExportScope::Visible),
        CsvFormat::new(),
        Vec::new(),
        cx,
    )?;
    Ok(cx.spawn(async move |_, _| Ok(job.await?.into_output())))
}

pub fn export_to_path( &mut self, request: ExportRequest<D::Row>, format: impl ExportFormat<D::Row>, path: impl Into<PathBuf>, cx: &mut Context<'_, Self>, ) -> Result<ExportJob<PathBuf>, ExportError>

As Self::export, to a file at path: written to <path>.part beside it, then renamed over path. A cancelled or failed export removes the part file and leaves path as it was; on Windows a file another program holds open fails the rename with ExportError::Io. Not on the web, which has no file system: export to a Vec<u8> there.

The application asks for the path first (App::prompt_for_new_path with the format’s extension) and may open the file once the job is done (App::open_with_system).

pub fn export_with<T: Send + 'static>( &mut self, request: ExportRequest<D::Row>, write: impl FnOnce(&ExportTable<'_, D::Row>, &CellExport<D::Row>, &ExportControl) -> Result<T, ExportError> + Send + 'static, cx: &mut Context<'_, Self>, ) -> Result<ExportJob<T>, ExportError>

Hands the export table to write in a task runner job: an application builds its own file there, such as an xlsx workbook with its own library, and returns what it made. write calls ExportControl::advance as an ExportFormat does. What is taken now and when nothing is exported: as Self::export.

pub fn is_export_empty(&self, scope: ExportScope) -> bool

Returns true if an export of scope would have nothing to write (ExportError::Nothing): no line, pinned row or totals row with aggregates for Visible and Expanded, an empty command scope for Selection. Check it before asking for a file name.

impl<D: LiveGridDelegate> LiveGridState<D>

pub fn with_expand_gesture(self, gesture: impl ExpandGesture) -> Self

Sets how a press expands or collapses a group caption or a tree row (default StandardExpandGesture: the chevron toggles, with Alt/Option everything below it too, and a double click on a caption toggles it).

impl<D: LiveGridDelegate> LiveGridState<D>

pub fn with_row_drag_gesture(self, gesture: impl RowDragGesture<D::Row>) -> Self

Sets which presses drag rows (default NoRowDrag: none; SelectedRowsDrag is LiveGrid’s gesture).

pub fn with_row_drop_policy(self, policy: impl RowDropPolicy<D::Row>) -> Self

Sets where drops on the rows land (default NoRowDrop: the grid takes none; DropOnRows and DropBetweenRows are built in).

pub fn with_drop_payload<T: Clone + 'static>(self) -> Self

Takes drops of T, a drag payload of the application’s own, besides the rows of grids with this key type: an element with on_drag(T) dropped on the rows arrives as DropSource::Payload, the value cloned as its data. The drop policy places it, reading the value with RowDropContext::payload.

pub fn is_dragging_rows(&self) -> bool

Returns true while a row drag from this grid is in progress: from the gesture’s threshold to the release.

impl<D: LiveGridDelegate> LiveGridState<D>

pub fn with_editor( self, column: <<D as LiveGridDelegate>::Row as GridRow>::Column, editor: impl CellEditor<D::Row>, ) -> Self

Gives column’s cells an editor; a column without one is read-only. The delegate’s is_editable can still refuse a cell.

pub fn set_editor( &mut self, column: <<D as LiveGridDelegate>::Row as GridRow>::Column, editor: Option<Rc<dyn CellEditor<D::Row>>>, cx: &mut Context<'_, Self>, )

Sets or removes the editor of column’s cells.

pub fn has_editor( &self, column: <<D as LiveGridDelegate>::Row as GridRow>::Column, ) -> bool

Returns true if column’s cells have an editor.

pub fn with_edit_gesture(self, gesture: impl EditGesture) -> Self

Sets which input opens an editor and where the focus goes after a commit (default StandardEditGesture, Excel’s).

pub fn with_edit_policy(self, policy: impl EditPolicy) -> Self

Sets how an edit behaves around its commit and under live data (default StandardEditPolicy).

pub fn start_edit( &mut self, key: &<<D as LiveGridDelegate>::Row as GridRow>::Key, column: <<D as LiveGridDelegate>::Row as GridRow>::Column, window: &mut Window, cx: &mut Context<'_, Self>, ) -> bool

Opens the editor of a cell (EditInput::Programmatic, EditOrigin::Programmatic): the cell takes the focus and scrolls into view. An open editor elsewhere ends first, as a press outside it would end it. Returns false, doing nothing, if the cell is not shown, has no editor, or is_editable refuses it.

pub fn commit_edit( &mut self, window: &mut Window, cx: &mut Context<'_, Self>, ) -> bool

Commits the open editor as Enter would, without moving the focus. Returns false if no editor is open or its draft is refused: it stays open with the message.

pub fn cancel_edit( &mut self, window: &mut Window, cx: &mut Context<'_, Self>, ) -> bool

Closes the open editor without a commit (EditCancelReason::Programmatic). Returns false if none is open.

pub fn editing_cell( &self, ) -> Option<(&<<D as LiveGridDelegate>::Row as GridRow>::Key, <<D as LiveGridDelegate>::Row as GridRow>::Column)>

The cell being edited: its key and column.

pub fn is_editing(&self) -> bool

Returns true while an editor is open.

pub fn edit_message(&self) -> Option<(EditorMark, &SharedString)>

The open editor’s message and its mark: a refused draft (EditorMark::Invalid), for an application that shows it itself (LiveGridDelegate::render_edit_message returning None).

impl<D: LiveGridDelegate> LiveGridState<D>

pub fn handle(&self, cx: &Context<'_, Self>) -> LiveGridHandle

A handle of this grid without its delegate type: for a toolbar, a status bar or a column chooser.

impl<D: LiveGridDelegate> LiveGridState<D>

pub fn with_link_opener(self, opener: impl LinkOpener) -> Self

Sets what opening a link does (default OpenInBrowser): an application may open it in a view of its own, or ask first.

pub fn is_link_hovered(&self) -> bool

Returns true if the pointer is over a link’s text, as of the last frame: the body shows the pointer cursor.

impl<D: LiveGridDelegate> LiveGridState<D>

pub fn group_by(&self) -> &[GroupBy<D::Row>]

The grouping levels, the top level first; empty when not grouped.

pub fn set_group_by( &mut self, levels: impl IntoIterator<Item = GroupBy<D::Row>>, cx: &mut Context<'_, Self>, )

Replaces the grouping and rebuilds at once (GroupChange with GroupOrigin::Programmatic). The new order is shown from the top, unless the focused line (a row or a group caption) is on screen and still shown: it keeps its screen line. Repeated levels are dropped, the first one stays; the same grouping again (the same level ids and directions) does nothing. Works for columns the group panel does not accept. A grouping replaces a tree; no levels turn grouping off and leave a tree alone.

The expansion stays: toggles are kept by group path, so those of another grouping come back with it.

pub fn tree(&self) -> Option<&TreeSpec<D::Row>>

The tree of the view, if it builds one; None when flat or grouped.

pub fn aggregates( &self, ) -> &[(<<D as LiveGridDelegate>::Row as GridRow>::Column, Aggregate<D::Row>)]

The aggregates of group captions, group footers and the totals, by column.

pub fn set_aggregates( &mut self, aggregates: impl IntoIterator<Item = (<<D as LiveGridDelegate>::Row as GridRow>::Column, Aggregate<D::Row>)>, cx: &mut Context<'_, Self>, )

Replaces the aggregates of group captions, group footers and the totals; a repeated column keeps its last aggregate. The same aggregates again (custom ones by identity, in any order) do nothing; otherwise the view rebuilds at once, as a user action, keeping the scroll position (an aggregate order may move groups), and a held order is dropped (OrderHeldChange { held: false }). No event of its own: the application sets the aggregates, and a layout does not keep them.

pub fn with_expand_depth(self, depth: ExpandDepth) -> Self

Sets how deep groups and tree rows are expanded by default (ExpandDepth::All unless set), with nothing toggled. For a grid being built; Self::set_expand_depth changes it later. The expansion of a layout given to Self::with_layout, before or after, replaces it.

pub fn expand_depth(&self) -> ExpandDepth

How deep groups and tree rows are expanded by default.

pub fn set_expand_depth( &mut self, depth: ExpandDepth, cx: &mut Context<'_, Self>, )

Sets the default depth and clears every toggle: expand all (ExpandDepth::All), collapse all (Levels(0)), captions only (Captions). Emits ExpansionChange { target: None } with GroupOrigin::Programmatic, unless the depth is the same and nothing is toggled.

pub fn is_expanded( &self, target: &ExpandTarget<<<D as LiveGridDelegate>::Row as GridRow>::Key>, ) -> bool

Whether a group or a tree row is expanded now: the view’s expansion, not the projection shown, which may lag one job behind. The root path is expanded. A tree row’s depth comes from the shown projection: a row it does not hold, or one of a projection that is not a tree, is not expanded.

pub fn set_expanded( &mut self, target: ExpandTarget<<<D as LiveGridDelegate>::Row as GridRow>::Key>, expanded: bool, cx: &mut Context<'_, Self>, ) -> bool

Expands or collapses one group or tree row. Returns false, doing nothing, if it was so already, for the root path, and for a tree row the shown projection does not hold as a tree. Otherwise emits ExpansionChange with GroupOrigin::Programmatic at once; the lines are laid out again in the background, without the throttle and the reorder hold, and a ProjectionChange follows.

A group of another grouping may be toggled too: the toggle shows when that grouping comes back. A new row never expands its group: it arrives in the group’s state.

impl<D: LiveGridDelegate> LiveGridState<D>

pub fn with_image_source(self, source: impl Into<CellImages>) -> Self

Sets where the images of CellValue::Image cells come from (default AssetImageSource: GPUI’s image loader, every image kept).

impl<D: LiveGridDelegate> LiveGridState<D>

pub fn with_view_id(self, view_id: impl Into<SharedString>) -> Self

Names the kind of grid (“trades”) for saved layouts and the layout library. Every grid of a view shares the view id; a layout saved for another view is refused (LayoutError::ViewMismatch).

pub fn with_layout(self, layout: GridLayout) -> Self

Applies a saved layout at construction, without events: its columns, its sort in place of the sort of with_view (an empty sort too; the filter stays), its grouping in place of the grouping of with_view (no grouping too; a tree of with_view stays when the layout has no grouping), and its expansion in place of the depth of with_expand_depth (a tree keeps that depth). A layout this build does not read, or one saved for another view, is ignored; call Self::set_layout to see why. Called again, the new layout replaces the old one.

The builders it depends on (with_view, with_view_id, with_expand_depth, with_column_move_policy and with_layout_merge) may come before or after it: each applies the layout again after its own change.

pub fn with_layout_codec(self, codec: impl LayoutCodec) -> Self

Sets the text format of Self::export_layout and Self::import_layout (default JsonLayoutCodec).

pub fn with_layout_merge(self, merge: impl LayoutMerge) -> Self

Sets how a saved layout meets the current schema (default AppendNewColumns). The grid validates what the merge returns.

pub fn view_id(&self) -> Option<&SharedString>

The view id given to Self::with_view_id.

pub fn layout(&self) -> GridLayout

The current layout: every schema column in display order (hidden ones at their place) with its width in logical pixels, visibility and zone, the sort, the grouping levels, and the expansion of groups: the default depth (Self::expand_depth) and the groups of the current grouping toggled against it. The quick filter, scrolling, selection and focus are not part of it.

A grouping with a level by a function of the row (GroupKey) is not saved, nor the expansion: a function cannot be read back from a file. A tree is not saved either, nor its expansion: the application sets its tree, and row keys are the application’s own type. Toggled groups of another grouping are kept by the grid until it is dropped, not saved.

Reads state only, so it works for a grid that was never painted, such as one in a hidden dock tab.

pub fn default_layout(&self) -> GridLayout

The layout of the schema: its order normalized by the column move policy, its widths, visibility and zones, the sort and the grouping of the view given to with_view, and the depth given to with_expand_depth with no group toggled. Saved as Self::layout saves: without a grouping by a function, or a tree. Self::reset_layout restores it.

pub fn export_layout(&self) -> Result<String, LayoutError>

The current layout as text, through the layout codec.

pub fn set_layout( &mut self, layout: &GridLayout, cx: &mut Context<'_, Self>, ) -> Result<LayoutReport, LayoutError>

Restores a saved layout: the columns, then the sort, the grouping and the expansion. Saved columns the schema no longer has are ignored and new schema columns are added (by the layout merge, default AppendNewColumns); the report lists both. Widths are kept within the columns’ limits.

Grouping levels on columns the schema no longer has, cannot group or repeat are dropped, and the levels below move up; toggled groups deeper than the levels left are dropped (the report lists both). A layout without grouping turns grouping off and leaves a tree alone; a layout with grouping replaces a tree. The expansion of a tree is not restored: a layout does not hold it. The toggles of other groupings stay while the depth is the same.

Rebuilds the order once if the sort or the grouping changed, or the visible columns that a quick filter searches; a new expansion alone only lays the lines out again. Emits, when everything has changed: OrderHeldChange { held: false } if that rebuild drops a held order, SortChange if the sort changed, GroupChange if the grouping did, ExpansionChange { target: None } if the expansion did, LayoutChange if the columns changed (all Programmatic), then FocusChange if the focused column is now hidden. A layout equal to the current one emits nothing. Fails, changing nothing, for a version this build does not read or a layout of another view.

pub fn import_layout( &mut self, text: &str, cx: &mut Context<'_, Self>, ) -> Result<LayoutReport, LayoutError>

Reads a layout through the layout codec and restores it with Self::set_layout.

pub fn reset_layout(&mut self, cx: &mut Context<'_, Self>)

Restores Self::default_layout as Self::set_layout does, with the grouping or tree of the view given to with_view as it was given: a level by a function too. The ResetLayout Action does the same with the User origin.

impl<D: LiveGridDelegate> LiveGridState<D>

pub fn is_menu_open(&self) -> bool

Returns true while the context menu is open.

pub fn show_context_menu( &mut self, window: &mut Window, cx: &mut Context<'_, Self>, )

Opens the context menu for the focused cell, below it, scrolled into view (ShowContextMenu); with no focused cell, at the top left of the rows, for the whole grid. The menu is built after the current event.

impl<D: LiveGridDelegate> LiveGridState<D>

pub fn resolve_edit( &mut self, edit: EditId, result: Result<(), EditError>, cx: &mut Context<'_, Self>, ) -> bool

Answers a commit (LiveGridEvent::EditCommit::edit). Ok: the value was applied; the cell shows it until the store has it too, the store says its own, or EditPolicy::settle_timeout passes. Err: the cell goes back to the store’s value and shows the error until the cell is edited again, clear_edit_error, or EditPolicy::error_mark_timeout. Returns false for an unknown id, one answered already, or one settled: a removed row’s commits are dropped.

pub fn edit_state( &self, key: &<<D as LiveGridDelegate>::Row as GridRow>::Key, column: <<D as LiveGridDelegate>::Row as GridRow>::Column, ) -> Option<&EditState>

What a cell’s edits look like now: waiting for an answer, accepted and waiting for the store, or failed. None when the cell shows the store’s value with no error.

pub fn pending_edit_count(&self) -> usize

Commits not answered yet, or accepted and waiting for the store.

pub fn clear_edit_error( &mut self, key: &<<D as LiveGridDelegate>::Row as GridRow>::Key, column: <<D as LiveGridDelegate>::Row as GridRow>::Column, cx: &mut Context<'_, Self>, ) -> bool

Takes the error mark off a cell (EditState::Failed); the next edit of the cell does it too. Returns false if the cell had none.

impl<D: LiveGridDelegate> LiveGridState<D>

pub fn pinned_keys( &self, edge: PinnedEdge, ) -> Vec<<<D as LiveGridDelegate>::Row as GridRow>::Key>

Keys of the rows pinned at edge that the last frame painted, top to bottom. A band taller than the body is cut next to the data rows, so the last rows of the top band, or the first rows of the bottom band, may be missing.

impl<D: LiveGridDelegate> LiveGridState<D>

pub fn set_progress( &mut self, progress: Option<GridProgress>, cx: &mut Context<'_, Self>, )

Shows the view’s own progress over the store’s; None shows the store’s again. For work the view waits for itself; a producer writes GridWriter::set_progress instead, in order with its data.

pub fn progress(&self) -> Option<&GridProgress>

The progress shown now: the view’s (Self::set_progress), else the store’s. Progress the store cleared stays shown until the order on screen reflects every write before the clearing, so the bar does not leave before the new rows show.

impl<D: LiveGridDelegate> LiveGridState<D>

pub fn is_order_held(&self) -> bool

Returns true if a newer order is ready but held by the reorder policy.

pub fn apply_held_order(&mut self, cx: &mut Context<'_, Self>)

Shows the held order now (for a “refresh order” control).

pub fn set_reorder_policy( &mut self, policy: impl ReorderPolicy, cx: &mut Context<'_, Self>, )

Replaces the reorder policy at run time, as a “Live / Hold / Manual” switch does; Self::with_reorder_policy sets it when the grid is built. A held order is offered to the new policy at once, as when the pointer leaves the grid, with the hold’s start kept: switching to LiveReorder shows it and emits OrderHeldChange { held: false }. While the context menu is open the built-in policies keep holding. With no order held only the policy changes.

use gpui_kit::{App, Entity};
use gpui_kit_grid::{LiveGridDelegate, LiveGridState, LiveReorder, ManualReorder};

/// A "Live / Manual" switch in a toolbar.
fn set_live<D: LiveGridDelegate>(grid: &Entity<LiveGridState<D>>, live: bool, cx: &mut App) {
    grid.update(cx, |grid, cx| {
        if live {
            grid.set_reorder_policy(LiveReorder, cx);
        } else {
            grid.set_reorder_policy(ManualReorder, cx);
        }
    });
}

pub fn flush( &mut self, cx: &mut Context<'_, Self>, ) -> Task<Option<FlushOutcome>>

Resolves once the order shown, or held by the reorder policy, reflects every operation written to the store before the call: with what it waited for, or None if the grid or the store is gone.

For tests and for “select the first row after loading”:

writer.replace_all(rows);
let flushed = grid.update(cx, |grid, cx| grid.flush(cx));
cx.spawn(async move |_, cx| {
    if flushed.await.is_some() {
        grid.update(cx, |grid, cx| {
            let first = grid
                .projection()
                .rows()
                .first()
                .and_then(|id| grid.snapshot().row(*id))
                .map(|row| row.key().clone());
            grid.select_key(first, cx);
        })
        .ok();
    }
})
.detach();

Call it after the writes it should wait for: a producer on another thread awaits GridWriter::flush itself or tells the UI thread it wrote. Operations buffered by an unfinished reload are not waited for (GridWriter::flush). An order held by the reorder policy resolves the flush with FlushOutcome::is_order_held; a new data set (replace_all, a finished reload) is shown under any policy. ProjectionChange of the order comes before the flush resolves.

The work the flush waits for starts at once: without the min_rebuild_interval throttle, and from the flush itself when the grid is not painted (a hidden tab, a grid not in a window). So a flush is not something to call on every tick: each call lifts the throttle for the rebuild it waits for.

pub fn set_view(&mut self, view: ViewSpec<D::Row>, cx: &mut Context<'_, Self>)

Replaces the view (sort, filter, grouping or tree, aggregates) and rebuilds at once. The new order is shown from the top, unless the focused line (a row or a group caption) is on screen and still shown: it keeps its screen line. The grid owns the quick filter and the expansion: they stay, and those of view are replaced by them (Self::set_quick_filter, Self::set_expanded). Emits SortChange (SortOrigin::Programmatic) if the sort differs, then GroupChange (GroupOrigin::Programmatic) if the grouping or the tree does.

pub fn sort( &self, ) -> &[(<<D as LiveGridDelegate>::Row as GridRow>::Column, SortDirection)]

The sort, most significant column first; empty for the insertion order.

pub fn set_sort( &mut self, sort: impl IntoIterator<Item = (<<D as LiveGridDelegate>::Row as GridRow>::Column, SortDirection)>, cx: &mut Context<'_, Self>, )

Replaces the sort and rebuilds at once (SortChange with SortOrigin::Programmatic), shown as by Self::set_view: from the top, or with the focused line on its screen line. Repeated columns are dropped, the first one stays; the same sort again does nothing. Works for columns that a header click does not sort.

pub fn quick_filter(&self) -> &SharedString

The quick filter text, trimmed; empty when the filter is off.

pub fn set_quick_filter( &mut self, text: impl Into<SharedString>, cx: &mut Context<'_, Self>, )

Shows only rows whose display text contains the text, as the QuickFilterMatcher decides (default ContainsAllTerms: every whitespace-separated term, ignoring case, in some quick filter column). Rebuilds at once, like any user action, and shows the new order as Self::set_view does. The text is trimmed; empty or blank text turns the filter off, and the same trimmed text again does nothing.

impl<D: LiveGridDelegate> LiveGridState<D>

pub fn visible_rows(&self) -> Range<usize>

The display rows currently in the viewport: the data rows’ area, between the pinned bands.

pub fn scroll_to_key( &mut self, key: &<<D as LiveGridDelegate>::Row as GridRow>::Key, cx: &mut Context<'_, Self>, ) -> bool

Scrolls the row with key into view, between the pinned bands. O(1): key index of the snapshot, then the display index of the projection. Returns false if the row is not displayed (unknown key, filtered out, or not yet projected). Pinned rows are always in view.

pub fn scroll_to_row(&mut self, display_ix: usize, cx: &mut Context<'_, Self>)

Scrolls so display_ix is the first visible row.

pub fn scroll_by(&mut self, delta: Point<Pixels>, cx: &mut Context<'_, Self>)

Scrolls by a pixel delta (positive moves content up and left).

pub fn scroll_x(&self) -> Pixels

The horizontal scroll offset of the scrolling zone: 0 at its start.

pub fn set_scroll_x(&mut self, scroll_x: Pixels, cx: &mut Context<'_, Self>)

Sets the horizontal scroll offset.

impl<D: LiveGridDelegate> LiveGridState<D>

pub fn with_selection_mode(self, mode: SelectionMode) -> Self

Sets what a click or a key press selects (default SelectionMode::RowSingle).

pub fn with_selection_scope(self, scope: impl SelectionScope<D::Row>) -> Self

Sets which rows and cells commands act on (default ProjectionScope; see also StoreScope).

pub fn with_selection_gesture(self, gesture: impl SelectionGesture) -> Self

Sets how a press or a navigation command edits the selection (default StandardSelectionGesture).

pub fn with_context_menu_gesture(self, gesture: impl ContextMenuGesture) -> Self

Sets which press opens the context menu (default StandardContextMenuGesture). On the body that press edits the selection as GestureInput::ContextPointer.

pub fn with_selection_policy(self, policy: impl SelectionPolicy<D::Row>) -> Self

Sets which lines take the selection and what a command over a line acts on (default FocusCaptions: group captions take the focus, not the selection, and a command over one acts on its group’s rows).

pub fn selection_mode(&self) -> SelectionMode

What a click or a key press selects.

pub fn selection( &self, ) -> &GridSelection<<<D as LiveGridDelegate>::Row as GridRow>::Key>

The whole selection, by key. It may hold rows hidden by a filter: commands use Self::scoped_selection.

pub fn scoped_selection( &self, ) -> ScopedSelection<<<D as LiveGridDelegate>::Row as GridRow>::Key>

The selection within the selection scope, in display order: what a command acts on. O(selected rows).

pub fn focused_cell( &self, ) -> Option<&FocusedCell<<<D as LiveGridDelegate>::Row as GridRow>::Key, <<D as LiveGridDelegate>::Row as GridRow>::Column>>

The focused cell: the keyboard target.

pub fn is_cell_selected( &self, key: &<<D as LiveGridDelegate>::Row as GridRow>::Key, column: <<D as LiveGridDelegate>::Row as GridRow>::Column, ) -> bool

Returns true if the cell is selected; in the row modes, if its row is.

pub fn visible_keys( &self, ) -> Vec<<<D as LiveGridDelegate>::Row as GridRow>::Key>

The keys of the data rows painted in the last frame, top to bottom; group captions are left out.

pub fn set_selection_mode( &mut self, mode: SelectionMode, cx: &mut Context<'_, Self>, )

Changes the selection mode (SelectionOrigin::Programmatic). Rows ↔ cells clears the selection; a set mode → a single one keeps only the focused row or cell.

pub fn select_key( &mut self, key: Option<<<D as LiveGridDelegate>::Row as GridRow>::Key>, cx: &mut Context<'_, Self>, )

Selects one row, or clears the selection with None; in the cell modes, its cell in the focused column. A row on screen also takes the focus. A key missing from the current snapshot selects nothing (SelectionOrigin::Programmatic).

pub fn set_selected_keys( &mut self, keys: impl IntoIterator<Item = <<D as LiveGridDelegate>::Row as GridRow>::Key>, cx: &mut Context<'_, Self>, )

Selects these rows (the first one in the single modes; their visible cells in CellSet). Keys missing from the current snapshot are dropped: a row that does not exist yet is not selected in advance.

pub fn set_selected_cells( &mut self, cells: impl IntoIterator<Item = (<<D as LiveGridDelegate>::Row as GridRow>::Key, <<D as LiveGridDelegate>::Row as GridRow>::Column)>, cx: &mut Context<'_, Self>, )

Selects these cells (the first one in the single modes; their rows in the row modes). Keys missing from the current snapshot are dropped.

pub fn select_all(&mut self, cx: &mut Context<'_, Self>)

Selects every row on screen, as Cmd/Ctrl+A: the keys now, so rows that arrive later are not selected. Does nothing in the single modes.

pub fn clear_selection(&mut self, cx: &mut Context<'_, Self>)

Clears the selection; the focus stays.

pub fn set_focused_cell( &mut self, key: &<<D as LiveGridDelegate>::Row as GridRow>::Key, column: Option<<<D as LiveGridDelegate>::Row as GridRow>::Column>, cx: &mut Context<'_, Self>, ) -> bool

Focuses a cell and scrolls it into view (SelectionOrigin:: Programmatic); the anchor follows. None keeps the focused column. Returns false if the row is not on screen.

pub fn set_focused_group( &mut self, path: &GroupPath, cx: &mut Context<'_, Self>, ) -> bool

Focuses the caption of the group at path if the shown order paints it, and scrolls it into view (SelectionOrigin::Programmatic); the focused column stays. The selection and the anchor stay: a caption takes no selection. Returns false if the projection on screen shows no such caption, under a collapsed group for one.

impl<D: LiveGridDelegate> LiveGridState<D>

pub fn with_totals(self, edge: PinnedEdge) -> Self

Shows the totals row at edge: the aggregates of every row the view passes (rows of collapsed groups included), as the outermost row of that pinned band. Without aggregates (ViewSpec::with_aggregates) the row shows only its label.

pub fn set_totals( &mut self, edge: Option<PinnedEdge>, cx: &mut Context<'_, Self>, )

Shows the totals row at edge, or hides it (None). Takes effect with the next frame; no event, no rebuild.

pub fn totals(&self) -> Option<PinnedEdge>

Where the totals row is shown, if it is.

impl<D: LiveGridDelegate> LiveGridState<D>

pub fn set_tree( &mut self, tree: Option<TreeSpec<D::Row>>, cx: &mut Context<'_, Self>, )

Shows the rows as a tree by GridRow::parent_key (Some) or flat (None), and rebuilds at once. The new order is shown from the top, unless the focused line (a row or a group caption) is on screen and still shown: it keeps its screen line. A tree replaces the grouping, as Self::set_group_by replaces a tree. Emits GroupChange with GroupOrigin::Programmatic, after OrderHeldChange { held: false } if a held order was dropped; a ProjectionChange follows.

A TreeSpec has no equality (its rules are closures), so a tree always rebuilds and emits; None on a view that is no tree does nothing. The expansion of tree rows is kept by key: turning the tree off and on again brings it back.

impl<D: LiveGridDelegate> LiveGridState<D>

pub fn new( schema: GridSchema<<<D as LiveGridDelegate>::Row as GridRow>::Column>, delegate: D, store: GridStore<D::Row>, cx: &mut Context<'_, Self>, ) -> Self

A grid over store. Several grids may share one store.

pub fn new_standalone( schema: GridSchema<<<D as LiveGridDelegate>::Row as GridRow>::Column>, delegate: D, options: StoreOptions, cx: &mut Context<'_, Self>, ) -> Self

A grid with its own store.

pub fn with_view(self, view: ViewSpec<D::Row>) -> Self

Sets the view (filter, sort, grouping or tree, aggregates). The grid owns the quick filter and the expansion: those of view are replaced by the grid’s own (Self::set_quick_filter, Self::with_expand_depth). The sort and the grouping of a layout given to Self::with_layout, before or after, replace those of view.

pub fn with_engine(self, engine: impl ProjectionEngine<D::Row>) -> Self

Sets the projection engine (default Rebuild).

pub fn with_tuning(self, tuning: GridTuning) -> Self

Sets the timing knobs.

pub fn with_reorder_policy(self, policy: impl ReorderPolicy) -> Self

Sets when a new display order replaces the shown one (default LiveReorder; see also HoldReorder and ManualReorder).

pub fn with_task_runner(self, runner: impl TaskRunner) -> Self

Sets where background jobs run (default BackgroundRunner).

pub fn with_sort_cycle(self, cycle: impl SortCycle) -> Self

Sets how a header click changes the sort (default StandardSortCycle).

pub fn with_quick_filter_matcher(self, matcher: impl QuickFilterMatcher) -> Self

Sets how quick filter text matches rows (default ContainsAllTerms).

pub fn with_quick_filter_columns( self, columns: impl IntoIterator<Item = <<D as LiveGridDelegate>::Row as GridRow>::Column>, ) -> Self

Sets the columns the quick filter searches (default: the visible columns, frozen and scrolled out of view included). Hiding a column does not change an explicit set.

pub fn store(&self) -> &GridStore<D::Row>

The store.

pub fn writer(&self) -> GridWriter<D::Row>

A writer for producers on any thread.

pub fn snapshot(&self) -> &Arc<StoreSnapshot<D::Row>>

The snapshot currently shown.

pub fn projection(&self) -> &Arc<Projection>

The display order currently shown.

pub fn stats(&self) -> GridStats

Profiling counters.

pub fn text_stats(&self) -> TextStats

Text cache counters.

Trait Implementations

impl<D: LiveGridDelegate> Focusable for LiveGridState<D>

fn focus_handle(&self, _: &App) -> FocusHandle

Returns the focus handle associated with this view.

impl<D: LiveGridDelegate> Render for LiveGridState<D>

fn render( &mut self, window: &mut Window, cx: &mut Context<'_, Self>, ) -> impl IntoElement

Render this view into an element tree.

impl<D: LiveGridDelegate> EventEmitter<LiveGridEvent<<<D as LiveGridDelegate>::Row as GridRow>::Key, <<D as LiveGridDelegate>::Row as GridRow>::Column>> for LiveGridState<D>