Struct ScrollState 

pub struct ScrollState { /* private fields */ }

Tracks scroll position for virtual scrolling in TUI components.

ScrollState is a composable building block that any component can embed in its state to gain scroll offset tracking, visible range calculation, and scrollbar rendering support.

It supports two usage patterns:

• Offset mode: The scroll offset is controlled directly via scroll_up, scroll_down, etc. Used by LogViewer, ChatView, ScrollableText.
• Selection mode: The scroll offset follows a selected index via ensure_visible, keeping it within the viewport. Used by SelectableList, Table, DataGrid, etc.

Example

use envision::scroll::ScrollState;

let mut scroll = ScrollState::new(500);
scroll.set_viewport_height(20);

assert_eq!(scroll.offset(), 0);
assert!(scroll.can_scroll());
assert!(scroll.at_start());

scroll.scroll_down();
assert_eq!(scroll.offset(), 1);

scroll.scroll_to_end();
assert_eq!(scroll.offset(), 480); // 500 - 20

Implementations

impl ScrollState

pub fn new(content_length: usize) -> Self

Creates a new ScrollState with the given content length.

The scroll offset starts at 0 and viewport height defaults to 0 (set it in view() once the render area is known).

Example

use envision::scroll::ScrollState;

let scroll = ScrollState::new(100);
assert_eq!(scroll.content_length(), 100);
assert_eq!(scroll.offset(), 0);

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

Sets the total number of scrollable items or lines.

If the current offset exceeds the new maximum, it is clamped.

pub fn set_viewport_height(&mut self, height: usize)

Sets the viewport height (number of visible items).

Typically called in view() after computing the inner render area. If the current offset exceeds the new maximum, it is clamped.

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

Sets the scroll offset directly, clamped to the valid range.

pub fn scroll_up(&mut self) -> bool

Scrolls up by one item. Returns true if the offset changed.

pub fn scroll_down(&mut self) -> bool

Scrolls down by one item. Returns true if the offset changed.

pub fn scroll_up_by(&mut self, n: usize) -> bool

Scrolls up by n items. Returns true if the offset changed.

pub fn scroll_down_by(&mut self, n: usize) -> bool

Scrolls down by n items. Returns true if the offset changed.

pub fn page_up(&mut self, page_size: usize) -> bool

Scrolls up by one page (viewport height). Returns true if the offset changed.

pub fn page_down(&mut self, page_size: usize) -> bool

Scrolls down by one page (viewport height). Returns true if the offset changed.

pub fn scroll_to_start(&mut self) -> bool

Scrolls to the first item. Returns true if the offset changed.

pub fn scroll_to_end(&mut self) -> bool

Scrolls to the last page. Returns true if the offset changed.

pub fn ensure_visible(&mut self, index: usize) -> bool

Adjusts the scroll offset to ensure the given index is visible.

If the index is above the viewport, scrolls up. If below, scrolls down. If already visible, does nothing. Returns true if the offset changed.

This is the key method for selection-based components: after changing the selected index, call this to keep the selection in view.

Example

use envision::scroll::ScrollState;

let mut scroll = ScrollState::new(100);
scroll.set_viewport_height(10);

// Selection at item 25 — scrolls viewport to show it
assert!(scroll.ensure_visible(25));
assert_eq!(scroll.offset(), 16); // 25 - 10 + 1

// Selection at item 20 — already visible, no change
assert!(!scroll.ensure_visible(20));

pub fn offset(&self) -> usize

Returns the current scroll offset (index of the first visible item).

pub fn content_length(&self) -> usize

Returns the total content length.

pub fn viewport_height(&self) -> usize

Returns the viewport height.

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

Returns the range of visible item indices.

The range is offset..min(offset + viewport_height, content_length).

Example

use envision::scroll::ScrollState;

let mut scroll = ScrollState::new(50);
scroll.set_viewport_height(10);
assert_eq!(scroll.visible_range(), 0..10);

scroll.scroll_to_end();
assert_eq!(scroll.visible_range(), 40..50);

pub fn max_offset(&self) -> usize

Returns the maximum valid scroll offset.

This is content_length.saturating_sub(viewport_height).

pub fn can_scroll(&self) -> bool

Returns true if scrolling is possible (content exceeds viewport).

pub fn at_start(&self) -> bool

Returns true if at the top (offset is 0).

pub fn at_end(&self) -> bool

Returns true if at the bottom (offset is at max).

pub fn scrollbar_state(&self) -> ScrollbarState

Creates a ratatui ScrollbarState configured for this scroll state.

Use this with ratatui’s Scrollbar widget for visual scroll indicators.

Trait Implementations

impl Clone for ScrollState

fn clone(&self) -> ScrollState

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ScrollState

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

Formats the value using the given formatter.

impl Default for ScrollState

fn default() -> ScrollState

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ScrollState

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for ScrollState

fn eq(&self, other: &ScrollState) -> 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 Serialize for ScrollState

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for ScrollState

impl StructuralPartialEq for ScrollState