Struct ScrollState 

pub struct ScrollState {
    pub offset: usize,
    pub offset_x: usize,
    pub dragging: bool,
    /* private fields */
}

State for a scrollable container.

Pass a mutable reference to Context::scrollable each frame. The context updates offset and the internal bounds automatically based on mouse wheel and drag events.

Both axes are tracked (#247): the vertical axis (offset, scroll_up / scroll_down) drives Context::scroll_col, and the horizontal axis (offset_x, scroll_left / scroll_right) drives Context::scroll_row. A single ScrollState scrolls one axis per container — nest a scroll_row inside a scroll_col for both. The vertical API is unchanged from earlier versions.

Fields

offset: usize

Current vertical scroll offset in rows.

offset_x: usize

Current horizontal scroll offset in columns (#247).

dragging: bool

Whether the scrollbar thumb is currently being dragged.

Set to true by Context::scrollbar on a mouse-down inside the thumb and back to false on mouse-up, mirroring SplitPaneState::dragging. Persists across frames so cursor motion outside the thumb (or even outside the track on the x-axis) keeps scrolling while the button is held.

Implementations

impl ScrollState

pub fn new() -> Self

Create scroll state starting at offset 0.

pub fn can_scroll_up(&self) -> bool

Check if scrolling upward is possible (offset is greater than 0).

pub fn can_scroll_down(&self) -> bool

Check if scrolling downward is possible (content extends below the viewport).

pub fn content_height(&self) -> u32

Get the total content height in rows.

pub fn viewport_height(&self) -> u32

Get the viewport height in rows.

pub fn progress_ratio(&self) -> f64

Get the scroll progress as a ratio in [0.0, 1.0].

Returns f64 to match the rest of the ratio surface unified in v0.20 (Gauge::ratio, SplitPaneState::ratio, progress(ratio), progress_bar(ratio)). Feed the value straight into Context::gauge or Context::progress_bar without a cast.

let scroll = ScrollState::new();
// Bounds are populated by the `scrollable` widget each frame; a fresh
// state with no content reports 0.0.
let ratio: f64 = scroll.progress_ratio();
assert!((0.0..=1.0).contains(&ratio));

pub fn progress(&self) -> f32

👎Deprecated since 0.21.0:

use progress_ratio() — f64 matches the rest of the v0.20+ ratio surface (gauge/progress_bar take f64; drop any as f64 cast)

Deprecated f32 alias for progress_ratio.

ScrollState::progress was the only f32 ratio left after the v0.20 f32 → f64 ratio unification. Migrate to progress_ratio: call sites that wrapped the result in as f64 can drop the cast, while call sites passing the value to gauge / progress_bar (which already take f64) need no cast at all.

pub fn scroll_up(&mut self, amount: usize)

Scroll up by the given number of rows, clamped to 0.

pub fn scroll_down(&mut self, amount: usize)

Scroll down by the given number of rows, clamped to the maximum offset.

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

Set the absolute scroll offset, clamped to [0, content - viewport].

Uses the same max_offset semantics as scroll_down. Click-to-jump and thumb-drag in Context::scrollbar route through this so an out-of-range target row never leaves the offset past the last full screen of content. Direct state.offset = … writes keep working; this is the clamping-safe alternative.

let mut scroll = ScrollState::new();
// Bounds are populated by the `scrollable` widget each frame; on a
// fresh state max_offset is 0 so any target clamps to 0.
scroll.set_offset(999);
assert_eq!(scroll.offset, 0);

pub fn can_scroll_left(&self) -> bool

Check if scrolling left is possible (offset_x is greater than 0, #247).

let scroll = ScrollState::new();
assert!(!scroll.can_scroll_left());

pub fn can_scroll_right(&self) -> bool

Check if scrolling right is possible (content extends past the right edge of the viewport, #247).

let scroll = ScrollState::new();
// A fresh state with no content cannot scroll right.
assert!(!scroll.can_scroll_right());

pub fn content_width(&self) -> u32

Total horizontal content width in columns (#247).

pub fn viewport_width(&self) -> u32

Horizontal viewport width in columns (#247).

pub fn progress_x(&self) -> f64

Horizontal scroll progress as a ratio in [0.0, 1.0] (#247).

The x-axis mirror of progress_ratio. Returns 0.0 when the content fits the viewport (no horizontal overflow). Feed it to a future horizontal scrollbar, a position readout, or a minimap.

let scroll = ScrollState::new();
let p: f64 = scroll.progress_x();
assert!((0.0..=1.0).contains(&p));

pub fn scroll_left(&mut self, amount: usize)

Scroll left by the given number of columns, clamped to 0 (#247).

let mut scroll = ScrollState::new();
scroll.scroll_left(4); // clamps at 0 with no content
assert_eq!(scroll.offset_x, 0);

pub fn scroll_right(&mut self, amount: usize)

Scroll right by the given number of columns, clamped to the maximum horizontal offset (#247).

let mut scroll = ScrollState::new();
scroll.scroll_right(4); // clamps to content bounds (0 with no content)
assert_eq!(scroll.offset_x, 0);

pub fn set_highlights(&mut self, ranges: &[HighlightRange])

Set the active highlight ranges. Replaces any previous highlights.

Selecting the first highlight automatically when the list is non-empty matches the behavior of search-result navigation in code editors.

pub fn highlights(&self) -> &[HighlightRange]

Read-only access to the active highlight ranges.

pub fn current_highlight(&self) -> Option<usize>

Index of the currently focused highlight, if any.

pub fn clear_highlights(&mut self)

Clear all highlights and reset the current index.

pub fn highlight_next(&mut self)

Advance to the next highlight, scrolling the viewport to show it. Wraps from last to first.

pub fn highlight_previous(&mut self)

Move to the previous highlight, scrolling the viewport to show it. Wraps from first to last.

pub fn scroll_to_current_highlight(&mut self)

Scroll the viewport so the currently focused highlight is visible with one line of context above when possible.

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() -> Self

Returns the “default value” for a type.