Struct GridViewHandle 

pub struct GridViewHandle { /* private fields */ }

A handle on a GridView’s scroll position, for a caller outside the widget: a toolbar, a “show current” command, a search result, an observer of the application’s own state.

Taken with GridView::handle, cheap to clone, and usable at once: a request made before the grid is mounted is kept and applied at its first layout, and the handle keeps working through every rebuild of the grid. Each method records a request and asks for a relayout; the layout applies it after it has measured the detail band and settled the scroll anchoring, so a request made in the same turn as a change of layout lands where the new layout puts the tile:

// Open the band of tile 0 and put tile 30 at the top, in one turn.
expanded.set(Some(0));
handle.scroll_to_index(30, ScrollAnchor::Start);

Only the latest request is applied: a later one replaces one still pending. A request for a tile the grid does not have when it is applied does nothing.

The handle also reads and moves the grid’s keyboard cursor, the tile the arrow keys step from, the focus ring marks and assistive technology is told is current: cursor, set_cursor and cursor_signal. In a multiple selection the cursor and the selection are separate: the accelerator with an arrow moves the cursor alone, and a selection written from outside leaves the cursor where it was.

Implementations

impl GridViewHandle

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

The tile the keyboard cursor is on, or None while the grid has no cursor: it has not been navigated, clicked or given one by set_cursor. With no cursor the keys start from the first selected tile, and from the first or last tile when nothing is selected.

In a single selection the cursor follows the selection: the keys move them together, and a selection written from outside moves the cursor onto it. In a multiple selection they are separate: the accelerator with an arrow (Ctrl+Arrow) moves the cursor alone, and a selection written from outside leaves the cursor where it was.

pub fn set_cursor(&self, index: Option<usize>)

Move the keyboard cursor to tile index, or remove it with None.

An index past the last tile is clamped to the last tile; on an empty grid the cursor is removed. The focus ring moves at the next paint, while the grid holds keyboard focus, and the grid names the tile as its active descendant at the next accessibility update when the tile is realized. The next arrow key steps from it.

Keyboard focus and the selection are left alone, and the grid does not scroll: pair it with ensure_index_visible to bring the tile into view. Usable before the grid is mounted (the first build finds the cursor there) and across its rebuilds. In a single selection the next change of selection puts the cursor back on the selected tile.

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

A read-only signal of the cursor, as cursor reports it, for an application to observe or bind: a status line naming the current tile, actions enabled for it. It changes with every write of the cursor, by the keys, a click, the data shifting it or set_cursor.

pub fn scroll_to_index(&self, index: usize, anchor: ScrollAnchor)

Scroll to tile index, forcing its position in the viewport per anchor: ScrollAnchor::Start puts its top at the viewport’s top, Center centres it, End puts its bottom at the viewport’s bottom, and Auto scrolls the least that shows it. Clamped to the scroll range. Applied at the next layout.

pub fn ensure_index_visible(&self, index: usize, anchor: ScrollAnchor)

Bring tile index into view: nothing when it is already fully visible, otherwise a scroll per anchor, as scroll_to_index. Applied at the next layout, against the layout it will be shown in.

pub fn reveal_band(&self, index: usize)

Scroll so tile index and its open detail band are both visible: the least scroll that shows the span from the top of the tile’s row to the bottom of its band, and the row first when the two do not fit together, so the band reads as the tile’s. This is what the grid does itself when a user opens a band.

When index’s band is not open at the layout that applies it (no detail_row, another tile disclosed, or a tile with nothing to disclose), the tile alone is brought into view, as ensure_index_visible with ScrollAnchor::Auto. Open the band and call this in the same turn: the band is measured before the request is applied.

Trait Implementations

impl Clone for GridViewHandle

fn clone(&self) -> GridViewHandle

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for GridViewHandle

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

Formats the value using the given formatter.