Struct ListState 

pub struct ListState { /* private fields */ }

Selection index and scroll offset for a selectable, scrollable list.

Holds no reference to the list’s actual items: len is passed in to each selection-movement method, so select_next/select_previous/select_first/select_last and the scroll offset stay valid across lists that change size (menus, reward pools, deck views, …). A selection set directly with select is the exception: it is stored unchecked and can outlive a shrunk list. See that method.

Selection movement clamps at len’s ends by default; see SelectionWrap (set via ListState::set_wrap) to switch to wraparound instead. Scrolling is a separate, unbounded-above counter (clamped only at zero) since only the caller knows the content length and viewport height needed to clamp it from above.

offset is always a whole row: there’s no momentum, velocity, or sub-row position here. For continuous/pixel-ish scrolling with momentum and rubber-banding (a smoothly-scrolled log or panel, not a discrete item list), reach for crate::ScrollState instead, and drive this type’s offset from crate::ScrollState::integer_offset if a list needs both a selection cursor and smooth scrolling together.

Implementations

impl ListState

pub const fn new() -> Self

An empty state: nothing selected, no scroll.

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

The currently selected index, if any.

pub const fn offset(&self) -> usize

The current scroll offset (index of the first visible item/line).

pub const fn wrap(&self) -> SelectionWrap

How select_next/select_previous behave at the ends of the list. Defaults to SelectionWrap::Clamp.

pub const fn set_wrap(&mut self, wrap: SelectionWrap)

Sets how select_next/select_previous behave at the ends of the list.

pub const fn select(&mut self, index: Option<usize>)

Select an explicit index, or clear the selection with None.

The index is stored verbatim and is not bounds-checked against any list length: unlike select_next/select_previous, this does not clamp. If the list later shrinks below a stored index, selected() keeps returning that now-out-of-range index (ensure_visible will not fix it, since it never sees len). Callers indexing their items by selected() must bound-check it against the current length first, or re-anchor with select_first/select_last after the list changes size.

pub const fn set_offset(&mut self, offset: usize)

Set the scroll offset directly.

pub const fn reset(&mut self)

Clear both the selection and the scroll offset, e.g. after the underlying list has been replaced with different content.

pub const fn ensure_visible(&mut self, visible_height: usize)

Nudge the scroll offset by the minimum amount needed to bring selected into the visible_height-row window starting at offset.

A no-op if nothing is selected, visible_height is zero, or the selection is already visible. Call this once per frame before rendering (with the actual, current viewport height, since that can change on terminal resize) rather than only after moving the selection: it’s cheap and idempotent, so redoing it every frame costs nothing and needs no special-casing for resize.

pub fn scroll_by(&mut self, delta: i32)

Move the scroll offset by delta, clamped at zero. There is no upper clamp here: only the caller knows the content length and viewport height needed to bound it from above.

pub fn select_next(&mut self, len: usize)

Select the next item. Past the last item, clamps (stays on the last item) or wraps to the first, per wrap(). Selects index 0 if nothing was selected yet. No-op (clears the selection) if len is zero.

pub fn select_previous(&mut self, len: usize)

Select the previous item. Before the first item, clamps (stays on the first item) or wraps to the last, per wrap(). Selects the last item if nothing was selected yet. No-op (clears the selection) if len is zero.

pub fn select_first(&mut self, len: usize)

Select the first item, or clear the selection if len is zero.

pub fn select_last(&mut self, len: usize)

Select the last item, or clear the selection if len is zero.

Trait Implementations

impl Clone for ListState

fn clone(&self) -> ListState

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ListState

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

Formats the value using the given formatter.

impl Default for ListState

fn default() -> ListState

Returns the “default value” for a type.

impl PartialEq for ListState

fn eq(&self, other: &ListState) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for ListState

impl Eq for ListState

impl StructuralPartialEq for ListState