Struct LazyListState

Source

pub struct LazyListState { /* private fields */ }

Expand description

State object for lazy list scroll position tracking.

Holds the current scroll position and provides methods to programmatically control scrolling. Create with remember_lazy_list_state() in composition.

This type is Copy, so it can be passed to multiple closures without explicit .clone() calls.

§Reactive Properties (read during composition triggers recomposition)

first_visible_item_index() - index of first visible item
first_visible_item_scroll_offset() - scroll offset within first item
can_scroll_forward() - whether more items exist below/right
can_scroll_backward() - whether more items exist above/left
stats() - lifecycle statistics (items_in_use, items_in_pool)

§Non-Reactive Properties

stats().total_composed - total items composed (diagnostic)
stats().reuse_count - items reused from pool (diagnostic)
layout_info() - detailed layout information

§Example

let state = remember_lazy_list_state();

// Scroll to item 50
state.scroll_to_item(50, 0.0);

// Get current visible item (reactive read)
println!("First visible: {}", state.first_visible_item_index());

Implementations§

Source §

impl LazyListState

Source

pub fn inner_ptr(&self) -> *const ()

Returns a pointer to the inner state for unique identification. Used by scroll gesture detection to create unique keys.

Source

pub fn first_visible_item_index(&self) -> usize

Returns the index of the first visible item.

When called during composition, this creates a reactive subscription so that changes to the index will trigger recomposition.

Source

pub fn first_visible_item_scroll_offset(&self) -> f32

Returns the scroll offset of the first visible item.

This is the amount the first item is scrolled off-screen (positive = scrolled up/left). When called during composition, this creates a reactive subscription so that changes to the offset will trigger recomposition.

Source

pub fn layout_info(&self) -> LazyListLayoutInfo

Returns the layout info from the last measure pass.

Source

pub fn stats(&self) -> LazyLayoutStats

Returns the current item lifecycle statistics.

When called during composition, this creates a reactive subscription so that changes to items_in_use or items_in_pool will trigger recomposition. The total_composed and reuse_count fields are diagnostic and non-reactive.

Source

pub fn update_stats(&self, items_in_use: usize, items_in_pool: usize)

Updates the item lifecycle statistics.

Called by the layout measurement after updating slot pools. Triggers recomposition if items_in_use or items_in_pool changed.

Source

pub fn record_composition(&self, was_reused: bool)

Records that an item was composed (either new or reused).

This updates diagnostic counters in non-reactive state. Does NOT trigger recomposition.

Source

pub fn record_scroll_direction(&self, delta: f32)

Records the scroll direction for prefetch calculations. Positive = scrolling forward (content moving up), negative = backward.

Source

pub fn update_prefetch_queue( &self, first_visible_index: usize, last_visible_index: usize, total_items: usize, )

Updates the prefetch queue based on current visible items. Should be called after measurement to queue items for pre-composition.

Source

pub fn take_prefetch_indices(&self) -> Vec<usize>

Returns the indices that should be prefetched. Consumes the prefetch queue.

Source

pub fn scroll_to_item(&self, index: usize, scroll_offset: f32)

Scrolls to the specified item index.

§Arguments

index - The index of the item to scroll to
scroll_offset - Additional offset within the item (default 0)

Source

pub fn dispatch_scroll_delta(&self, delta: f32) -> f32

Dispatches a raw scroll delta.

Returns the amount of scroll actually consumed.

This triggers layout invalidation via registered callbacks. The callbacks are registered by LazyColumnImpl/LazyRowImpl with schedule_layout_repass(node_id), which provides O(subtree) performance instead of O(entire app).

Source

pub fn peek_scroll_delta(&self) -> f32

Peeks at the pending scroll delta without consuming it.

Used for direction inference before measurement consumes the delta. This is more accurate than comparing first visible index, especially for:

Scrolling within the same item (partial scroll)
Variable height items where scroll offset changes without index change

Source

pub fn cache_item_size(&self, index: usize, size: f32)

Caches the measured size of an item for scroll estimation.

Uses a HashMap + VecDeque LRU pattern with O(1) insertion and eviction. Re-measurement of existing items (uncommon during normal scrolling) requires O(n) VecDeque position lookup, but the cache is small (100 items).

§Performance Note

If profiling shows this as a bottleneck, consider using the lru crate for O(1) update-in-place operations, or a linked hash map.

Source

pub fn get_cached_size(&self, index: usize) -> Option<f32>

Gets a cached item size if available.

Source

pub fn average_item_size(&self) -> f32

Returns the running average of measured item sizes.

Source

pub fn nearest_range(&self) -> Range<usize>

Returns the current nearest range for optimized key lookup.

Source

pub fn update_scroll_position_if_item_moved<F>( &self, new_item_count: usize, get_index_by_key: F, ) -> usize
where F: Fn(u64) -> Option<usize>,

Adjusts scroll position if the first visible item was moved due to data changes.

Matches JC’s updateScrollPositionIfTheFirstItemWasMoved. If items were inserted/removed before the current scroll position, this finds the item by its key and updates the index accordingly.

Returns the adjusted first visible item index.

Source