Struct ListViewHandle 

pub struct ListViewHandle { /* private fields */ }

A handle on a mounted ListView, to scroll it to an item from outside the widget — a view-model reacting to a search hit, a “jump to” command.

Cheap to clone, valid before the view is mounted, and it survives the view’s rebuilds. Its methods never compute an offset when they are called: they record the request and ask for a layout pass, and the view applies it there, after row measurement and scroll anchoring have settled. So a model change made in the same turn (rows inserted above, say) is accounted for, a request made before mount is applied at the first layout, and a later request replaces an earlier pending one. A request on an empty list is dropped; an index past the end reveals the last item.

The handle also reads and moves the list’s keyboard cursor, the row the arrow keys step from 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.

let list = ListView::new(model, |_i, item, _selected| {
    Box::new(TextWidget::new(lit!(item)))
});
let handle = list.handle();
// … `ctx.add(list)`, then later, from any handler:
handle.scroll_to_index(120);

Implementations

impl ListViewHandle

pub fn scroll_to_index(&self, index: usize)

Scroll so the given model index is aligned to the top of the viewport, as far as the scroll range allows, at the next layout pass. Sections are honoured as in ListView::scroll_to_index.

pub fn ensure_index_visible(&self, index: usize)

Scroll the minimum distance that brings the given model index fully into view, at the next layout pass; no scroll when it already is. Sections are honoured as in ListView::ensure_index_visible.

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

The model index the keyboard cursor is on, or None while the list 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 row, and from the first or last row when nothing is selected.

In a single selection the cursor follows the selection: the keys move them together, and a selection written from outside takes the cursor off any other row (it reads None then, and the keys start from the selection). 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 model index index, or remove it with None.

An index past the last row is clamped to the last row; on an empty list the cursor is removed. While the list holds keyboard focus it names the row as its active descendant at the next accessibility update, when the row is realized; the next arrow key steps from it.

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

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 row, actions enabled for it. It changes with every write of the cursor, by the keys, a click, the data shifting it or set_cursor.

Trait Implementations

impl Clone for ListViewHandle

fn clone(&self) -> ListViewHandle

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ListViewHandle

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

Formats the value using the given formatter.