Struct ListState

Source

pub struct ListState {
    pub selected: usize,
    /* 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§

§selected: usize

Index of the currently selected item.

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 items(&self) -> &[String]

Return all items in their underlying, unfiltered order.

Source

pub fn len(&self) -> usize

Return the number of underlying items.

Source

pub fn is_empty(&self) -> bool

Return whether the underlying list is empty.

Source

pub fn item(&self, index: usize) -> Option<&str>

Return an item by underlying data index.

Source

pub fn push_item(&mut self, item: impl Into<String>)

Append an item and rebuild cache-coupled view state.

Source

pub fn insert_item(&mut self, index: usize, item: impl Into<String>) -> bool

Insert an item at a data index. Returns false when out of bounds.

Source

pub fn remove_item(&mut self, index: usize) -> Option<String>

Remove and return an item by data index.

Source

pub fn clear_items(&mut self)

Remove all items and reset cache-coupled selection and viewport state.

Source

pub fn filter(&self) -> &str

Return the active filter text.

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"));