Struct DataGrid 

pub struct DataGrid<M> { /* private fields */ }

A grid of rows from a GridModel: the user scrolls it (wheel, touchpad, scroll bar, keys), selects a row (click, arrow keys, Page Up and Down, Home, End) or a range of rows (the same with Shift; Ctrl+A, or Cmd+A on macOS, for all), copies them (Ctrl+C or Ctrl+Insert, Cmd+C: tab-separated, see selected_text), sorts it by clicking a column’s title (again to reverse), and resizes columns by dragging the edges between titles. Leading columns can stay in place while the rest scroll sideways (with_frozen_columns).

Only the rows on screen are asked of the model, each frame, and painting allocates nothing once their characters are cached, however many rows there are. Change the data through model_mut from an Ui::update on the grid, which repaints it. The grid follows the model’s GridModel::columns_revision and GridModel::generation each frame.

The selected row (and a range’s other end) is kept on its record while rows move if the model gives rows keys (GridModel::row_key) and cleared when its record is removed or filtered out (as in Qt’s proxy models); without keys, sorting clears it. Sorting makes a range one row again, and a range covers the rows between its ends as they stand. It reports ActionKind::Selected with the row when the user selects one, ActionKind::Submitted when they activate it (Enter, a double click), and ActionKind::Changed when a click sorted the rows. Give it DataGrid::style.

Implementations

impl<M: GridModel> DataGrid<M>

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

The selected rows: one, the range from where a Shift selection started to the selected row, or all of them; empty for none.

pub fn select_rows(&mut self, cx: &mut EventCx<'_>, anchor: usize, row: usize)

Selects the rows from anchor to row (either way round), row being the selected one, and scrolls it into view. Rows past the last are taken as the last.

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

Selects every row, and those added later, until the selection changes. The selected row stays as it was, and nothing scrolls.

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

Puts the selected rows on the clipboard, as selected_text writes them; false if no row is selected or the clipboard would not take them.

The text of every selected row is built at once, on the calling thread: a million rows take a noticeable time and as much memory as their text.

pub fn selected_text(&mut self, palette: &Palette) -> String

The selected rows’ cells as the grid shows them (with palette’s formatting, where the model’s text depends on it), a tab between cells and a line break between rows: the shape spreadsheets paste into cells. Tabs and line breaks within a cell become spaces.

impl<M: GridModel> DataGrid<M>

pub fn new(model: M) -> Self

A grid showing model.

pub fn with_frozen_columns(self, columns: usize) -> Self

The grid with its first columns columns kept in place while the others scroll sideways (all of them, if there are fewer).

pub fn style() -> Style

A grid filling its parent’s free space, allowed to be smaller than its rows, and clipping them.

pub fn model(&self) -> &M

The data.

pub fn model_mut(&mut self, cx: &mut EventCx<'_>) -> &mut M

The data, to change (from an Ui::update on the grid): the grid repaints, and keeps its selection and scroll within the rows there are.

pub fn reset_columns(&mut self, cx: &mut EventCx<'_>)

Reads the model’s columns again (after it changed them), dropping the user’s widths, and a sort or a drag on a column that is gone.

pub fn selected(&self) -> Option<usize>

The selected row.

pub fn select(&mut self, cx: &mut EventCx<'_>, row: Option<usize>)

Selects row alone (none for None) and scrolls it into view. For the row already selected, the rows selected with it stay selected (an application echoing ActionKind::Selected back does not end a range); select_rows with the row twice selects it alone.

pub fn first_row(&self) -> usize

The first row on screen.

pub fn scroll_to_row(&mut self, cx: &mut EventCx<'_>, row: usize)

Scrolls so that row is the first on screen, or as near as the rows allow.

pub fn sort_order(&self) -> Option<(usize, SortOrder)>

The column and order the rows are sorted by: the model’s own, if it reports it, else the last one a click asked for.

pub fn columns(&self) -> &[Column]

The columns as shown, with the user’s widths.

pub fn visible_rows(&self) -> usize

How many rows are painted, the last one possibly cut off (0 before the first layout).

pub fn whole_rows(&self) -> usize

How many rows fit whole: what a page is, and how many the last screen shows.

Trait Implementations

impl<M: Debug> Debug for DataGrid<M>

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

Formats the value using the given formatter.

impl<M: GridModel + 'static> Widget for DataGrid<M>

fn layout(&mut self, cx: &mut LayoutCx<'_>, size: Size)

Layout decided the widget’s size: re-wrap text or recompute anything that depends on it. Called after every layout pass that changed the size.

fn paint(&mut self, cx: &PaintCx<'_>, canvas: &mut Canvas<'_>)

Paints the widget below its children.

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

Handles event. An event the widget does not handle goes on to its parent.

fn accepts_focus(&self) -> bool

Whether the widget takes keyboard focus, by click or by Tab.

fn accessibility(&self, cx: &PaintCx<'_>, node: &mut AccessNode)

Describes the widget to assistive technology: fills node, which starts as a Role::Group with the widget’s rectangle. Called only while assistive technology is listening; it may allocate.

fn access_action( &mut self, cx: &mut EventCx<'_>, request: &AccessRequest<'_>, ) -> Handled

Does what assistive technology asks (only actions the widget’s node lists are asked of it). Focus and scrolling into view are done for every widget; a request the widget does not handle goes on to its parent if it is a scroll.

fn measure(&mut self, cx: &mut LayoutCx<'_>, constraints: Constraints) -> Size

The size the widget wants within constraints, for a widget without children (one with children is sized by its style and its children). Physical pixels.

fn paint_over(&mut self, cx: &PaintCx<'_>, canvas: &mut Canvas<'_>)

Paints the widget over its children: scroll bars, focus rings, overlays.

fn focus_on_press(&self) -> bool

Whether a press on the widget, or on a widget inside it that takes no focus, focuses it (if it accepts focus). A container reachable by Tab, such as a dock’s tab list, says no, so clicks on its contents do not focus it; it can still ask for focus itself.