Struct ScrollState 

pub struct ScrollState { /* private fields */ }

Shared scroll state for a scrollable surface.

Offsets are always clamped to the valid range derived from content_size and viewport_size.

Implementations

impl ScrollState

pub fn new(content: ScrollSize, viewport: ScrollSize) -> Self

Create a new ScrollState with the given content and viewport sizes.

Examples found in repository

examples/scroll_demo.rs (lines 72-75)

fn main() -> minui::Result<()> {
    // Shared scroll model (content size + viewport size + offsets).
    // Seed with non-zero sizes so scrollbar math is sane before first draw.
    let scroll = Rc::new(RefCell::new(ScrollState::new(
        ScrollSize::new(1, 1),
        ScrollSize::new(1, 1),
    )));

    // Initial scrollbars; sizes are refreshed every draw frame.
    let vbar = ScrollBar::new(
        1,
        1,
        Rc::clone(&scroll),
        ScrollBarOptions {
            orientation: ScrollOrientation::Vertical,
            show_arrows: true,
            scroll_step: Some(1),
            ..ScrollBarOptions::default()
        },
    );

    let hbar = ScrollBar::new(
        1,
        1,
        Rc::clone(&scroll),
        ScrollBarOptions {
            orientation: ScrollOrientation::Horizontal,
            show_arrows: true,
            scroll_step: Some(2),
            ..ScrollBarOptions::default()
        },
    );

    let initial = ScrollDemoState {
        ui: UiScene::new(),
        scroll,
        vbar,
        hbar,
        autohide: AutoHide::new(Duration::from_millis(900), 2),
    };

    let mut app = App::new(initial)?;

    app.run(
        // ============================
        // Update: route events
        // ============================
        |state, event| {
            // Apply common scene policies:
            // - observe mouse position
            // - tab traversal (if any focusables are registered this frame)
            // - click-to-focus + mouse capture
            let _effects = state.ui.apply_policies(&event);

            // Quit (prefer modifier-aware events, with legacy fallback)
            if let Event::KeyWithModifiers(k) = event {
                if matches!(k.key, KeyKind::Char('q')) {
                    return false;
                }
            }
            if matches!(event, Event::Character('q')) {
                return false;
            }

            // Mouse wheel scrolling:
            // Route ONLY to the scroll target under cursor (preferred) or the focused scroll target.
            // This is now centralized in UiScene.
            match event {
                Event::MouseScroll { delta } => {
                    if let Some(RouteTarget::Id(_id)) = state.ui.route_wheel_event(&event) {
                        state.autohide.mark_activity();

                        // Convention: delta > 0 scrolls up, delta < 0 scrolls down.
                        // We invert to translate "scroll down" into positive offset movement.
                        let dy: i16 = -(delta as i16);
                        state
                            .scroll
                            .borrow_mut()
                            .scroll_by(ScrollOrientation::Vertical, dy);
                    }
                }
                Event::MouseScrollHorizontal { delta } => {
                    if let Some(RouteTarget::Id(_id)) = state.ui.route_wheel_event(&event) {
                        state.autohide.mark_activity();

                        let dx: i16 = -(delta as i16);
                        state
                            .scroll
                            .borrow_mut()
                            .scroll_by(ScrollOrientation::Horizontal, dx);
                    }
                }
                _ => {}
            }

            // Keyboard scrolling (prefer modifier-aware events, with legacy fallback).
            match event {
                Event::KeyWithModifiers(k) => match k.key {
                    KeyKind::Up => state
                        .vbar
                        .scroll_by_fraction(-1.0 / 5.0, ScrollUnit::Viewport),
                    KeyKind::Down => state
                        .vbar
                        .scroll_by_fraction(1.0 / 5.0, ScrollUnit::Viewport),
                    KeyKind::Left => state
                        .hbar
                        .scroll_by_fraction(-1.0 / 5.0, ScrollUnit::Viewport),
                    KeyKind::Right => state
                        .hbar
                        .scroll_by_fraction(1.0 / 5.0, ScrollUnit::Viewport),
                    _ => {}
                },

                // Legacy fallback.
                Event::KeyUp => state
                    .vbar
                    .scroll_by_fraction(-1.0 / 5.0, ScrollUnit::Viewport),
                Event::KeyDown => state
                    .vbar
                    .scroll_by_fraction(1.0 / 5.0, ScrollUnit::Viewport),
                Event::KeyLeft => state
                    .hbar
                    .scroll_by_fraction(-1.0 / 5.0, ScrollUnit::Viewport),
                Event::KeyRight => state
                    .hbar
                    .scroll_by_fraction(1.0 / 5.0, ScrollUnit::Viewport),

                _ => {}
            }

            // Route pointer events into scrollbars (click/drag/arrows), using UiScene owner grouping.
            //
            // IMPORTANT:
            // - Only route if the relevant areas were registered (i.e. visible).
            // - If capture is active, UiScene ensures drag/release continue to target the captured id.
            //
            // We route to an OWNER so the app can forward to the owning ScrollBar instance.
            if let Some(target) = state.ui.route_mouse_event_to_owner(&event) {
                match target {
                    RouteTarget::Owner(OWNER_VSCROLL) => {
                        if let Some(entry) = state.ui.get(ID_VSCROLL_ROOT) {
                            let _ = state.vbar.handle_event(&event, entry.area);
                        }
                    }
                    RouteTarget::Owner(OWNER_HSCROLL) => {
                        if let Some(entry) = state.ui.get(ID_HSCROLL_ROOT) {
                            let _ = state.hbar.handle_event(&event, entry.area);
                        }
                    }
                    _ => {}
                }
            }

            true
        },
        // ============================
        // Draw: register areas + draw
        // ============================
        |state, window| {
            state.ui.begin_frame();

            let (term_w, term_h) = window.get_size();

            // Layout constants
            let margin: u16 = 1;
            let header_h: u16 = 1;

            // Scrollbar sizes (vbar on the right, hbar on bottom)
            let vbar_w: u16 = 1;
            let hbar_h: u16 = 1;

            // ScrollBox styling affects its *outer* size vs the *inner* content viewport.
            // Because the ScrollBox draws a border + padding, we must reserve extra space so
            // the right/bottom borders don't get overwritten by scrollbars.
            let box_border: u16 = 1; // single-line border thickness
            let box_padding: u16 = 1; // we set ContainerPadding::uniform(1) below

            // Compute a safe outer rect for the ScrollBox (what you pass to with_position_and_size)
            // leaving room for:
            // - header line
            // - scrollbars (drawn OUTSIDE the ScrollBox frame)
            //
            // IMPORTANT:
            // - The ScrollBox outer rect must be fully within the terminal bounds.
            // - The scrollbars are then placed at `outer_x + outer_w` (right) and `outer_y + outer_h` (bottom),
            //   so we must reserve 1 extra column/row for them as well.
            let outer_x = margin;
            let outer_y = margin + header_h;

            // Total insets that reduce the usable inner content area.
            let inner_inset_x = box_border + box_padding;
            let inner_inset_y = box_border + box_padding;

            // Available space inside terminal margins for the ScrollBox outer rect.
            // We reserve the scrollbar column/row OUTSIDE the ScrollBox.
            let max_outer_w = term_w.saturating_sub(margin * 2).saturating_sub(vbar_w);
            let max_outer_h = term_h
                .saturating_sub(margin * 2)
                .saturating_sub(header_h)
                .saturating_sub(hbar_h);

            // Clamp outer size to available space. Do NOT force a minimum that can exceed terminal bounds.
            // If the terminal is too small, we'll end up with a very small box (and the scrollbars may be skipped).
            let outer_w = max_outer_w;
            let outer_h = max_outer_h;

            // Inner viewport (content area) starts after border+padding.
            // NOTE: these are currently unused in this example, but kept for clarity.
            let viewport_x = outer_x + inner_inset_x;
            let viewport_y = outer_y + inner_inset_y;
            let viewport_w = outer_w.saturating_sub(inner_inset_x * 2);
            let viewport_h = outer_h.saturating_sub(inner_inset_y * 2);

            let _ = (viewport_x, viewport_y, viewport_w, viewport_h);

            // Header / help line
            window.write_str(
                margin,
                margin,
                "Scroll demo: wheel/drag scrollbars • arrows/keys work • press 'q' to quit",
            )?;

            // Build content each frame (no cloning needed).
            // Use a row gap to exercise gap-aware content measurement in ScrollBox.
            let mut content = Container::vertical().with_row_gap(Gap::Pixels(1));

            // Lots of lines (taller than viewport).
            for i in 0..150u16 {
                content = content.add_child(
                    Label::new(format!(
                        "Line {:03} | The quick brown fox jumps over the lazy dog. {}",
                        i,
                        if i % 5 == 0 { "[drag the thumb]" } else { "" }
                    ))
                    .with_text_color(Color::White),
                );
            }

            // ScrollBox bound to shared state and sized to viewport.
            let scrollbox = ScrollBox::both()
                .with_state(Rc::clone(&state.scroll))
                // IMPORTANT: pass the OUTER rect (includes border/padding), not the inner viewport.
                .with_position_and_size(outer_x, outer_y, outer_w, outer_h)
                .with_border()
                .with_border_chars(BorderChars::single_line())
                .with_title("Scrollable content")
                .with_title_alignment(TitleAlignment::Left)
                .with_padding(minui::widgets::ContainerPadding::uniform(1))
                .with_row_gap(Gap::Pixels(1))
                .add_child(content);

            // Register scrollbox interaction regions:
            // - outer frame as focusable (panel/split-friendly)
            // - inner viewport as scrollable (wheel routing)
            let outer_area = WidgetArea::new(outer_x, outer_y, outer_w, outer_h);
            scrollbox.register_with_ids(
                state.ui.cache_mut(),
                outer_area,
                ID_SCROLLBOX,
                ID_SCROLLBOX_VIEWPORT,
            );

            // Draw scrollbox (updates ScrollState sizes + applies offsets via WindowView).
            scrollbox.draw(window)?;

            // Vertical scrollbar area (right side)
            // Place it just outside the ScrollBox's outer border so it doesn't overwrite the frame.
            // This must still be inside the terminal bounds (x < term_w).
            let vbar_x = outer_x + outer_w;
            let vbar_y = outer_y;
            let vbar_h = outer_h;

            // If there isn't room for the scrollbar column (e.g. tiny terminals), just skip drawing it.
            if vbar_x >= term_w {
                return Ok(());
            }

            // Resize + sync existing scrollbar instead of recreating it every frame.
            // Recreating would reset drag state, making thumb dragging feel broken.
            state.vbar.set_size(1, vbar_h);
            state.vbar.set_show_arrows(true);
            state.vbar.set_scroll_step(Some(1));
            state.vbar.sync_from_state_and_resize_parts();

            let v_area = WidgetArea::new(vbar_x, vbar_y, 1, vbar_h);

            // Auto-hide policy: show if recently scrolled, mouse is near, or currently dragging.
            // Reveal policy:
            // - show when recently scrolled
            // - show when mouse is near the scrollbar area
            // - show when mouse is near the scrollbox RIGHT edge strip (even if the bar itself is hidden)
            // - show while dragging
            let mouse_pos = state.ui.last_mouse_pos();

            // Only consider proximity to a thin strip along the scrollbox's right edge.
            // This prevents the scrollbars from staying visible just because the cursor is somewhere
            // inside/near the scrollbox.
            let near_scrollbox_right_edge = if let Some((mx, my)) = mouse_pos {
                // A 1-column strip at the right edge of the scrollbox.
                let edge_x = outer_x + outer_w.saturating_sub(1);
                let edge_strip = WidgetArea::new(edge_x, outer_y, 1, outer_h);
                state.autohide.is_point_near_area(mx, my, edge_strip)
            } else {
                false
            };

            let show_vbar = state
                .autohide
                .should_show(v_area, mouse_pos, state.vbar.is_dragging())
                || near_scrollbox_right_edge;

            if show_vbar {
                // Register sub-areas so routing can distinguish thumb vs arrows.
                // Root is scrollable (hover target), thumb/track is draggable, arrows are focusable.
                // Register areas into the underlying cache (UiScene wraps InteractionCache).
                state.vbar.register_with_ids(
                    state.ui.cache_mut(),
                    v_area,
                    ID_VSCROLL_ROOT,
                    ID_VSCROLL_THUMB,
                    Some(ID_VSCROLL_ARROW_START),
                    Some(ID_VSCROLL_ARROW_END),
                );

                // Group all scrollbar sub-ids under a single owner for routing.
                state.ui.set_owner_for_ids(
                    OWNER_VSCROLL,
                    &[
                        ID_VSCROLL_ROOT,
                        ID_VSCROLL_THUMB,
                        ID_VSCROLL_ARROW_START,
                        ID_VSCROLL_ARROW_END,
                    ],
                );

                {
                    let mut view = WindowView {
                        window,
                        x_offset: vbar_x,
                        y_offset: vbar_y,
                        scroll_x: 0,
                        scroll_y: 0,
                        width: 1,
                        height: vbar_h,
                    };
                    state.vbar.draw(&mut view)?;
                }
            }

            // Horizontal scrollbar area (bottom)
            // Place it just outside the ScrollBox's outer border so it doesn't overwrite the frame.
            // This must still be inside the terminal bounds (y < term_h).
            let hbar_x = outer_x;
            let hbar_y = outer_y + outer_h;
            let hbar_w = outer_w;

            // If there isn't room for the scrollbar row (e.g. tiny terminals), just skip drawing it.
            if hbar_y >= term_h {
                return Ok(());
            }

            // Resize + sync existing scrollbar instead of recreating it every frame.
            // Recreating would reset drag state, making thumb dragging feel broken.
            state.hbar.set_size(hbar_w, 1);
            state.hbar.set_show_arrows(true);
            state.hbar.set_scroll_step(Some(2));
            state.hbar.sync_from_state_and_resize_parts();

            let h_area = WidgetArea::new(hbar_x, hbar_y, hbar_w, 1);

            // Auto-hide policy: show if recently scrolled, mouse is near, or currently dragging.
            // Reveal policy:
            // - show when recently scrolled
            // - show when mouse is near the scrollbar area
            // - show when mouse is near the scrollbox BOTTOM edge strip (even if the bar itself is hidden)
            // - show while dragging
            let mouse_pos = state.ui.last_mouse_pos();

            // Only consider proximity to a thin strip along the scrollbox's bottom edge.
            // This prevents the scrollbars from staying visible just because the cursor is somewhere
            // inside/near the scrollbox.
            let near_scrollbox_bottom_edge = if let Some((mx, my)) = mouse_pos {
                // A 1-row strip at the bottom edge of the scrollbox.
                let edge_y = outer_y + outer_h.saturating_sub(1);
                let edge_strip = WidgetArea::new(outer_x, edge_y, outer_w, 1);
                state.autohide.is_point_near_area(mx, my, edge_strip)
            } else {
                false
            };

            let show_hbar = state
                .autohide
                .should_show(h_area, mouse_pos, state.hbar.is_dragging())
                || near_scrollbox_bottom_edge;

            if show_hbar {
                // Register sub-areas so routing can distinguish thumb vs arrows.
                // Root is scrollable (hover target), thumb/track is draggable, arrows are focusable.
                // Register areas into the underlying cache (UiScene wraps InteractionCache).
                state.hbar.register_with_ids(
                    state.ui.cache_mut(),
                    h_area,
                    ID_HSCROLL_ROOT,
                    ID_HSCROLL_THUMB,
                    Some(ID_HSCROLL_ARROW_START),
                    Some(ID_HSCROLL_ARROW_END),
                );

                // Group all scrollbar sub-ids under a single owner for routing.
                state.ui.set_owner_for_ids(
                    OWNER_HSCROLL,
                    &[
                        ID_HSCROLL_ROOT,
                        ID_HSCROLL_THUMB,
                        ID_HSCROLL_ARROW_START,
                        ID_HSCROLL_ARROW_END,
                    ],
                );

                {
                    let mut view = WindowView {
                        window,
                        x_offset: hbar_x,
                        y_offset: hbar_y,
                        scroll_x: 0,
                        scroll_y: 0,
                        width: hbar_w,
                        height: 1,
                    };
                    state.hbar.draw(&mut view)?;
                }
            }

            window.end_frame()?;
            Ok(())
        },
    )?;

    Ok(())
}

pub fn content_size(&self) -> ScrollSize

Returns the content size.

pub fn viewport_size(&self) -> ScrollSize

Returns the viewport size.

pub fn offset(&self) -> ScrollOffset

Returns the current scroll offset.

pub fn offset_for(&self, orientation: ScrollOrientation) -> u16

Returns the current scroll offset along an orientation.

pub fn set_content_size(&mut self, size: ScrollSize)

Sets the content size and clamps the current offset.

pub fn set_viewport_size(&mut self, size: ScrollSize)

Sets the viewport size and clamps the current offset.

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

Sets the offset (x,y) and clamps it.

pub fn set_offset_for(&mut self, orientation: ScrollOrientation, value: u16)

Sets the offset along a single axis and clamps.

pub fn scroll_by(&mut self, orientation: ScrollOrientation, delta: i16)

Scrolls by a signed delta on the given axis.

Negative values scroll up/left, positive scroll down/right.

Examples found in repository

examples/scroll_demo.rs (line 147)

fn main() -> minui::Result<()> {
    // Shared scroll model (content size + viewport size + offsets).
    // Seed with non-zero sizes so scrollbar math is sane before first draw.
    let scroll = Rc::new(RefCell::new(ScrollState::new(
        ScrollSize::new(1, 1),
        ScrollSize::new(1, 1),
    )));

    // Initial scrollbars; sizes are refreshed every draw frame.
    let vbar = ScrollBar::new(
        1,
        1,
        Rc::clone(&scroll),
        ScrollBarOptions {
            orientation: ScrollOrientation::Vertical,
            show_arrows: true,
            scroll_step: Some(1),
            ..ScrollBarOptions::default()
        },
    );

    let hbar = ScrollBar::new(
        1,
        1,
        Rc::clone(&scroll),
        ScrollBarOptions {
            orientation: ScrollOrientation::Horizontal,
            show_arrows: true,
            scroll_step: Some(2),
            ..ScrollBarOptions::default()
        },
    );

    let initial = ScrollDemoState {
        ui: UiScene::new(),
        scroll,
        vbar,
        hbar,
        autohide: AutoHide::new(Duration::from_millis(900), 2),
    };

    let mut app = App::new(initial)?;

    app.run(
        // ============================
        // Update: route events
        // ============================
        |state, event| {
            // Apply common scene policies:
            // - observe mouse position
            // - tab traversal (if any focusables are registered this frame)
            // - click-to-focus + mouse capture
            let _effects = state.ui.apply_policies(&event);

            // Quit (prefer modifier-aware events, with legacy fallback)
            if let Event::KeyWithModifiers(k) = event {
                if matches!(k.key, KeyKind::Char('q')) {
                    return false;
                }
            }
            if matches!(event, Event::Character('q')) {
                return false;
            }

            // Mouse wheel scrolling:
            // Route ONLY to the scroll target under cursor (preferred) or the focused scroll target.
            // This is now centralized in UiScene.
            match event {
                Event::MouseScroll { delta } => {
                    if let Some(RouteTarget::Id(_id)) = state.ui.route_wheel_event(&event) {
                        state.autohide.mark_activity();

                        // Convention: delta > 0 scrolls up, delta < 0 scrolls down.
                        // We invert to translate "scroll down" into positive offset movement.
                        let dy: i16 = -(delta as i16);
                        state
                            .scroll
                            .borrow_mut()
                            .scroll_by(ScrollOrientation::Vertical, dy);
                    }
                }
                Event::MouseScrollHorizontal { delta } => {
                    if let Some(RouteTarget::Id(_id)) = state.ui.route_wheel_event(&event) {
                        state.autohide.mark_activity();

                        let dx: i16 = -(delta as i16);
                        state
                            .scroll
                            .borrow_mut()
                            .scroll_by(ScrollOrientation::Horizontal, dx);
                    }
                }
                _ => {}
            }

            // Keyboard scrolling (prefer modifier-aware events, with legacy fallback).
            match event {
                Event::KeyWithModifiers(k) => match k.key {
                    KeyKind::Up => state
                        .vbar
                        .scroll_by_fraction(-1.0 / 5.0, ScrollUnit::Viewport),
                    KeyKind::Down => state
                        .vbar
                        .scroll_by_fraction(1.0 / 5.0, ScrollUnit::Viewport),
                    KeyKind::Left => state
                        .hbar
                        .scroll_by_fraction(-1.0 / 5.0, ScrollUnit::Viewport),
                    KeyKind::Right => state
                        .hbar
                        .scroll_by_fraction(1.0 / 5.0, ScrollUnit::Viewport),
                    _ => {}
                },

                // Legacy fallback.
                Event::KeyUp => state
                    .vbar
                    .scroll_by_fraction(-1.0 / 5.0, ScrollUnit::Viewport),
                Event::KeyDown => state
                    .vbar
                    .scroll_by_fraction(1.0 / 5.0, ScrollUnit::Viewport),
                Event::KeyLeft => state
                    .hbar
                    .scroll_by_fraction(-1.0 / 5.0, ScrollUnit::Viewport),
                Event::KeyRight => state
                    .hbar
                    .scroll_by_fraction(1.0 / 5.0, ScrollUnit::Viewport),

                _ => {}
            }

            // Route pointer events into scrollbars (click/drag/arrows), using UiScene owner grouping.
            //
            // IMPORTANT:
            // - Only route if the relevant areas were registered (i.e. visible).
            // - If capture is active, UiScene ensures drag/release continue to target the captured id.
            //
            // We route to an OWNER so the app can forward to the owning ScrollBar instance.
            if let Some(target) = state.ui.route_mouse_event_to_owner(&event) {
                match target {
                    RouteTarget::Owner(OWNER_VSCROLL) => {
                        if let Some(entry) = state.ui.get(ID_VSCROLL_ROOT) {
                            let _ = state.vbar.handle_event(&event, entry.area);
                        }
                    }
                    RouteTarget::Owner(OWNER_HSCROLL) => {
                        if let Some(entry) = state.ui.get(ID_HSCROLL_ROOT) {
                            let _ = state.hbar.handle_event(&event, entry.area);
                        }
                    }
                    _ => {}
                }
            }

            true
        },
        // ============================
        // Draw: register areas + draw
        // ============================
        |state, window| {
            state.ui.begin_frame();

            let (term_w, term_h) = window.get_size();

            // Layout constants
            let margin: u16 = 1;
            let header_h: u16 = 1;

            // Scrollbar sizes (vbar on the right, hbar on bottom)
            let vbar_w: u16 = 1;
            let hbar_h: u16 = 1;

            // ScrollBox styling affects its *outer* size vs the *inner* content viewport.
            // Because the ScrollBox draws a border + padding, we must reserve extra space so
            // the right/bottom borders don't get overwritten by scrollbars.
            let box_border: u16 = 1; // single-line border thickness
            let box_padding: u16 = 1; // we set ContainerPadding::uniform(1) below

            // Compute a safe outer rect for the ScrollBox (what you pass to with_position_and_size)
            // leaving room for:
            // - header line
            // - scrollbars (drawn OUTSIDE the ScrollBox frame)
            //
            // IMPORTANT:
            // - The ScrollBox outer rect must be fully within the terminal bounds.
            // - The scrollbars are then placed at `outer_x + outer_w` (right) and `outer_y + outer_h` (bottom),
            //   so we must reserve 1 extra column/row for them as well.
            let outer_x = margin;
            let outer_y = margin + header_h;

            // Total insets that reduce the usable inner content area.
            let inner_inset_x = box_border + box_padding;
            let inner_inset_y = box_border + box_padding;

            // Available space inside terminal margins for the ScrollBox outer rect.
            // We reserve the scrollbar column/row OUTSIDE the ScrollBox.
            let max_outer_w = term_w.saturating_sub(margin * 2).saturating_sub(vbar_w);
            let max_outer_h = term_h
                .saturating_sub(margin * 2)
                .saturating_sub(header_h)
                .saturating_sub(hbar_h);

            // Clamp outer size to available space. Do NOT force a minimum that can exceed terminal bounds.
            // If the terminal is too small, we'll end up with a very small box (and the scrollbars may be skipped).
            let outer_w = max_outer_w;
            let outer_h = max_outer_h;

            // Inner viewport (content area) starts after border+padding.
            // NOTE: these are currently unused in this example, but kept for clarity.
            let viewport_x = outer_x + inner_inset_x;
            let viewport_y = outer_y + inner_inset_y;
            let viewport_w = outer_w.saturating_sub(inner_inset_x * 2);
            let viewport_h = outer_h.saturating_sub(inner_inset_y * 2);

            let _ = (viewport_x, viewport_y, viewport_w, viewport_h);

            // Header / help line
            window.write_str(
                margin,
                margin,
                "Scroll demo: wheel/drag scrollbars • arrows/keys work • press 'q' to quit",
            )?;

            // Build content each frame (no cloning needed).
            // Use a row gap to exercise gap-aware content measurement in ScrollBox.
            let mut content = Container::vertical().with_row_gap(Gap::Pixels(1));

            // Lots of lines (taller than viewport).
            for i in 0..150u16 {
                content = content.add_child(
                    Label::new(format!(
                        "Line {:03} | The quick brown fox jumps over the lazy dog. {}",
                        i,
                        if i % 5 == 0 { "[drag the thumb]" } else { "" }
                    ))
                    .with_text_color(Color::White),
                );
            }

            // ScrollBox bound to shared state and sized to viewport.
            let scrollbox = ScrollBox::both()
                .with_state(Rc::clone(&state.scroll))
                // IMPORTANT: pass the OUTER rect (includes border/padding), not the inner viewport.
                .with_position_and_size(outer_x, outer_y, outer_w, outer_h)
                .with_border()
                .with_border_chars(BorderChars::single_line())
                .with_title("Scrollable content")
                .with_title_alignment(TitleAlignment::Left)
                .with_padding(minui::widgets::ContainerPadding::uniform(1))
                .with_row_gap(Gap::Pixels(1))
                .add_child(content);

            // Register scrollbox interaction regions:
            // - outer frame as focusable (panel/split-friendly)
            // - inner viewport as scrollable (wheel routing)
            let outer_area = WidgetArea::new(outer_x, outer_y, outer_w, outer_h);
            scrollbox.register_with_ids(
                state.ui.cache_mut(),
                outer_area,
                ID_SCROLLBOX,
                ID_SCROLLBOX_VIEWPORT,
            );

            // Draw scrollbox (updates ScrollState sizes + applies offsets via WindowView).
            scrollbox.draw(window)?;

            // Vertical scrollbar area (right side)
            // Place it just outside the ScrollBox's outer border so it doesn't overwrite the frame.
            // This must still be inside the terminal bounds (x < term_w).
            let vbar_x = outer_x + outer_w;
            let vbar_y = outer_y;
            let vbar_h = outer_h;

            // If there isn't room for the scrollbar column (e.g. tiny terminals), just skip drawing it.
            if vbar_x >= term_w {
                return Ok(());
            }

            // Resize + sync existing scrollbar instead of recreating it every frame.
            // Recreating would reset drag state, making thumb dragging feel broken.
            state.vbar.set_size(1, vbar_h);
            state.vbar.set_show_arrows(true);
            state.vbar.set_scroll_step(Some(1));
            state.vbar.sync_from_state_and_resize_parts();

            let v_area = WidgetArea::new(vbar_x, vbar_y, 1, vbar_h);

            // Auto-hide policy: show if recently scrolled, mouse is near, or currently dragging.
            // Reveal policy:
            // - show when recently scrolled
            // - show when mouse is near the scrollbar area
            // - show when mouse is near the scrollbox RIGHT edge strip (even if the bar itself is hidden)
            // - show while dragging
            let mouse_pos = state.ui.last_mouse_pos();

            // Only consider proximity to a thin strip along the scrollbox's right edge.
            // This prevents the scrollbars from staying visible just because the cursor is somewhere
            // inside/near the scrollbox.
            let near_scrollbox_right_edge = if let Some((mx, my)) = mouse_pos {
                // A 1-column strip at the right edge of the scrollbox.
                let edge_x = outer_x + outer_w.saturating_sub(1);
                let edge_strip = WidgetArea::new(edge_x, outer_y, 1, outer_h);
                state.autohide.is_point_near_area(mx, my, edge_strip)
            } else {
                false
            };

            let show_vbar = state
                .autohide
                .should_show(v_area, mouse_pos, state.vbar.is_dragging())
                || near_scrollbox_right_edge;

            if show_vbar {
                // Register sub-areas so routing can distinguish thumb vs arrows.
                // Root is scrollable (hover target), thumb/track is draggable, arrows are focusable.
                // Register areas into the underlying cache (UiScene wraps InteractionCache).
                state.vbar.register_with_ids(
                    state.ui.cache_mut(),
                    v_area,
                    ID_VSCROLL_ROOT,
                    ID_VSCROLL_THUMB,
                    Some(ID_VSCROLL_ARROW_START),
                    Some(ID_VSCROLL_ARROW_END),
                );

                // Group all scrollbar sub-ids under a single owner for routing.
                state.ui.set_owner_for_ids(
                    OWNER_VSCROLL,
                    &[
                        ID_VSCROLL_ROOT,
                        ID_VSCROLL_THUMB,
                        ID_VSCROLL_ARROW_START,
                        ID_VSCROLL_ARROW_END,
                    ],
                );

                {
                    let mut view = WindowView {
                        window,
                        x_offset: vbar_x,
                        y_offset: vbar_y,
                        scroll_x: 0,
                        scroll_y: 0,
                        width: 1,
                        height: vbar_h,
                    };
                    state.vbar.draw(&mut view)?;
                }
            }

            // Horizontal scrollbar area (bottom)
            // Place it just outside the ScrollBox's outer border so it doesn't overwrite the frame.
            // This must still be inside the terminal bounds (y < term_h).
            let hbar_x = outer_x;
            let hbar_y = outer_y + outer_h;
            let hbar_w = outer_w;

            // If there isn't room for the scrollbar row (e.g. tiny terminals), just skip drawing it.
            if hbar_y >= term_h {
                return Ok(());
            }

            // Resize + sync existing scrollbar instead of recreating it every frame.
            // Recreating would reset drag state, making thumb dragging feel broken.
            state.hbar.set_size(hbar_w, 1);
            state.hbar.set_show_arrows(true);
            state.hbar.set_scroll_step(Some(2));
            state.hbar.sync_from_state_and_resize_parts();

            let h_area = WidgetArea::new(hbar_x, hbar_y, hbar_w, 1);

            // Auto-hide policy: show if recently scrolled, mouse is near, or currently dragging.
            // Reveal policy:
            // - show when recently scrolled
            // - show when mouse is near the scrollbar area
            // - show when mouse is near the scrollbox BOTTOM edge strip (even if the bar itself is hidden)
            // - show while dragging
            let mouse_pos = state.ui.last_mouse_pos();

            // Only consider proximity to a thin strip along the scrollbox's bottom edge.
            // This prevents the scrollbars from staying visible just because the cursor is somewhere
            // inside/near the scrollbox.
            let near_scrollbox_bottom_edge = if let Some((mx, my)) = mouse_pos {
                // A 1-row strip at the bottom edge of the scrollbox.
                let edge_y = outer_y + outer_h.saturating_sub(1);
                let edge_strip = WidgetArea::new(outer_x, edge_y, outer_w, 1);
                state.autohide.is_point_near_area(mx, my, edge_strip)
            } else {
                false
            };

            let show_hbar = state
                .autohide
                .should_show(h_area, mouse_pos, state.hbar.is_dragging())
                || near_scrollbox_bottom_edge;

            if show_hbar {
                // Register sub-areas so routing can distinguish thumb vs arrows.
                // Root is scrollable (hover target), thumb/track is draggable, arrows are focusable.
                // Register areas into the underlying cache (UiScene wraps InteractionCache).
                state.hbar.register_with_ids(
                    state.ui.cache_mut(),
                    h_area,
                    ID_HSCROLL_ROOT,
                    ID_HSCROLL_THUMB,
                    Some(ID_HSCROLL_ARROW_START),
                    Some(ID_HSCROLL_ARROW_END),
                );

                // Group all scrollbar sub-ids under a single owner for routing.
                state.ui.set_owner_for_ids(
                    OWNER_HSCROLL,
                    &[
                        ID_HSCROLL_ROOT,
                        ID_HSCROLL_THUMB,
                        ID_HSCROLL_ARROW_START,
                        ID_HSCROLL_ARROW_END,
                    ],
                );

                {
                    let mut view = WindowView {
                        window,
                        x_offset: hbar_x,
                        y_offset: hbar_y,
                        scroll_x: 0,
                        scroll_y: 0,
                        width: hbar_w,
                        height: 1,
                    };
                    state.hbar.draw(&mut view)?;
                }
            }

            window.end_frame()?;
            Ok(())
        },
    )?;

    Ok(())
}

pub fn scroll_to(&mut self, orientation: ScrollOrientation, value: u16)

Scrolls to a specific value on the given axis and clamps.

pub fn scroll_to_start(&mut self, orientation: ScrollOrientation)

Scrolls to the start (0) on the given axis.

pub fn scroll_to_end(&mut self, orientation: ScrollOrientation)

Scrolls to the end (max) on the given axis.

pub fn max_offset(&self) -> ScrollOffset

Returns the maximum scroll offset (x,y).

pub fn max_offset_for(&self, orientation: ScrollOrientation) -> u16

Returns the maximum scroll offset for the given axis.

pub fn max_offset_x(&self) -> u16

Returns the maximum horizontal scroll offset.

pub fn max_offset_y(&self) -> u16

Returns the maximum vertical scroll offset.

pub fn can_scroll(&self, orientation: ScrollOrientation) -> bool

Returns whether there is any scrollable range for the given axis.

pub fn can_scroll_vertical(&self) -> bool

Returns whether there is scrollable vertical range.

pub fn can_scroll_horizontal(&self) -> bool

Returns whether there is scrollable horizontal range.

pub fn at_start(&self, orientation: ScrollOrientation) -> bool

Returns whether the current offset is at the start (top/left) on the given axis.

pub fn at_end(&self, orientation: ScrollOrientation) -> bool

Returns whether the current offset is at the end (bottom/right) on the given axis.

pub fn scroll_ratio(&self, orientation: ScrollOrientation) -> f32

Returns a normalized scroll ratio in [0.0, 1.0] for the given axis.

If there is no scrollable range, this returns 0.0.

pub fn visible_range(&self) -> (u16, u16, u16, u16)

Returns the visible content range as (start_x, start_y, end_x, end_y) (end is exclusive).

pub fn clamp(&mut self)

Clamp offsets to valid ranges derived from current sizes.

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 Copy for ScrollState

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.

impl Eq for ScrollState

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 StructuralPartialEq for ScrollState