Struct ListState

Source

pub struct ListState {
    pub items: Vec<String>,
    pub selected: usize,
    pub filter: String,
    /* private fields */
}

Expand description

State for a selectable list widget.

Pass a mutable reference to Context::list each frame. Up/Down arrow keys (and k/j) move the selection when the widget is focused.

Fields§

§items: Vec<String>

The list items as display strings.

§selected: usize

Index of the currently selected item.

§filter: String

Case-insensitive substring filter applied to list items.

Implementations§

Source §

impl ListState

Source

pub fn new(items: Vec<impl Into<String>>) -> Self

Create a list with the given items. The first item is selected initially.

Source

pub fn set_items(&mut self, items: Vec<impl Into<String>>)

Replace the list items and rebuild the view index.

Use this instead of assigning items directly to ensure the internal filter/view state stays consistent.

Source

pub fn with_item_heights(self, heights: Vec<u32>) -> Self

Provide a per-item row height (each clamped to >= 1) and return self.

Enables variable-height virtualization via Context::virtual_list_variable, the chat/feed bubble use case where each item occupies a different number of rows. Each entry corresponds to the item at the same index; missing entries fall back to a height of 1.

§Example

use slt::widgets::ListState;

let state = ListState::new(vec!["short", "a\nthree\nline bubble", "ok"])
    .with_item_heights(vec![1, 3, 1]);

Available since 0.21.0.

Source

pub fn set_item_heights(&mut self, heights: Vec<u32>)

Set per-item row heights (each clamped to >= 1).

Marks the cached prefix sum dirty so it is rebuilt on the next render. Length should match items; missing entries fall back to a height of 1 and extra entries are ignored.

§Example

use slt::widgets::ListState;

let mut state = ListState::new(vec!["a", "b", "c"]);
state.set_item_heights(vec![2, 1, 4]);

Available since 0.21.0.

Source

pub fn clear_item_heights(&mut self)

Clear per-item heights, reverting to the uniform one-row-per-item model.

After this call Context::virtual_list_variable behaves identically to Context::virtual_list.

§Example

use slt::widgets::ListState;

let mut state = ListState::new(vec!["a", "b"]).with_item_heights(vec![3, 2]);
state.clear_item_heights();

Available since 0.21.0.

Source

pub fn set_filter(&mut self, filter: impl Into<String>)

Set the filter string. Multiple space-separated tokens are AND’d together — all tokens must match across any cell in the same row. Empty string disables filtering.

Source

pub fn visible_indices(&self) -> &[usize]

Returns indices of items visible after filtering.

Source

pub fn selected_item(&self) -> Option<&str>

Get the currently selected item text, or None if the list is empty.

Source

pub fn move_item(&mut self, from: usize, to: usize) -> bool

Move the item at data index from to data index to, preserving selection on the moved item.

Indices address the underlying items vector (the unfiltered order), not the filtered view. Out-of-range indices and a no-op from == to move leave the list untouched and return false. The parallel search cache and any per-item heights are kept in sync, and the filtered view is rebuilt so selected continues to point at the item that was moved when it remains visible.

§Example

use slt::widgets::ListState;

let mut state = ListState::new(vec!["a", "b", "c"]);
assert!(state.move_item(0, 2));
assert_eq!(state.selected_item(), Some("a"));