Struct ListState 

pub struct ListState(/* private fields */);

The list state that views must hold on behalf of the list element.

Implementations

impl ListState

pub fn new( item_count: usize, alignment: ListAlignment, overdraw: Pixels, ) -> Self

Construct a new list state, for storage on a view.

The overdraw parameter controls how much extra space is rendered above and below the visible area. Elements within this area will be measured even though they are not visible. This can help ensure that the list doesn’t flicker or pop in when scrolling.

pub fn measure_all(self) -> Self

Set the list to measure all items in the list in the first layout phase.

This is useful for ensuring that the scrollbar size is correct instead of based on only rendered elements.

pub fn reset(&self, element_count: usize)

Reset this instantiation of the list state.

Note that this will cause scroll events to be dropped until the next paint.

pub fn remeasure(&self)

Remeasure all items while preserving proportional scroll position.

Use this when item heights may have changed (e.g., font size changes) but the number and identity of items remains the same.

pub fn remeasure_items(&self, range: Range<usize>)

Mark items in range as needing remeasurement while preserving the current scroll position. Unlike Self::splice, this does not change the number of items or blow away logical_scroll_top.

Use this when an item’s content has changed and its rendered height may be different (e.g., streaming text, tool results loading), but the item itself still exists at the same index.

pub fn item_count(&self) -> usize

The number of items in this list.

pub fn is_scrolled_to_end(&self) -> Option<bool>

Whether the list is scrolled to the end, or None if the list is not scrollable or the total content height is not yet known.

pub fn splice(&self, old_range: Range<usize>, count: usize)

Inform the list state that the items in old_range have been replaced by count new items that must be recalculated.

pub fn splice_focusable( &self, old_range: Range<usize>, focus_handles: impl IntoIterator<Item = Option<FocusHandle>>, )

Register with the list state that the items in old_range have been replaced by new items. As opposed to Self::splice, this method allows an iterator of optional focus handles to be supplied to properly integrate with items in the list that can be focused. If a focused item is scrolled out of view, the list will continue to render it to allow keyboard interaction.

pub fn set_scroll_handler( &self, handler: impl FnMut(&ListScrollEvent, &mut Window, &mut App) + 'static, )

Set a handler that will be called when the list is scrolled.

pub fn logical_scroll_top(&self) -> ListOffset

Get the current scroll offset, in terms of the list’s items.

pub fn scroll_by(&self, distance: Pixels)

Scroll the list by the given offset

pub fn scroll_to_end(&self)

Scroll the list to the very end (past the last item).

Unlike [scroll_to_reveal_item], this uses the total item count as the anchor, so the list’s layout pass will walk backwards from the end and always show the bottom of the last item — even when that item is still growing (e.g. during streaming).

pub fn set_follow_mode(&self, mode: FollowMode)

Set the follow mode for the list. In Tail mode, the list will auto-scroll to the end and re-engage after the user scrolls back to the bottom. In Normal mode, no automatic following occurs.

pub fn is_following_tail(&self) -> bool

Returns whether the list is currently actively following the tail (snapping to the end on each layout).

pub fn scroll_to(&self, scroll_top: ListOffset)

Scroll the list to the given offset

pub fn scroll_to_reveal_item(&self, ix: usize)

Scroll the list to the given item, such that the item is fully visible.

pub fn bounds_for_item(&self, ix: usize) -> Option<Bounds<Pixels>>

Get the bounds for the given item in window coordinates, if it’s been rendered.

pub fn scrollbar_drag_started(&self)

Call this method when the user starts dragging the scrollbar.

This will prevent the height reported to the scrollbar from changing during the drag as items in the overdraw get measured, and help offset scroll position changes accordingly.

pub fn scrollbar_drag_ended(&self)

Called when the user stops dragging the scrollbar.

See scrollbar_drag_started.

pub fn set_offset_from_scrollbar(&self, point: Point<Pixels>)

Set the offset from the scrollbar

pub fn max_offset_for_scrollbar(&self) -> Point<Pixels>

Returns the maximum scroll offset according to the items we have measured. This value remains constant while dragging to prevent the scrollbar from moving away unexpectedly.

pub fn scroll_px_offset_for_scrollbar(&self) -> Point<Pixels>

Returns the current scroll offset adjusted for the scrollbar

pub fn viewport_bounds(&self) -> Bounds<Pixels>

Return the bounds of the viewport in pixels.

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.