Struct ScrollController 

pub struct ScrollController {
    pub bounds: State<Option<(Size2D, Size2D)>>,
    /* private fields */
}

Handle to drive a scrollview programmatically.

By default a scrollview owns its scroll position and only the user can move it, through the wheel, the scrollbar, arrow keys or dragging. A ScrollController lets your own code read and change that position instead. Create one with use_scroll_controller and hand it to a scrollview through its new_controlled constructor.

Some cases where a controller is needed:

• Jumping to the top or bottom in response to an action, for example scrolling a chat to the newest message after sending one.
• Keeping several scrollviews in sync, like a diff view with two panes that move together.
• Reading the current scroll position to drive something else, such as a “scroll to top” button that only appears once the user has scrolled down.

Scrolling from code

scroll_to jumps to the start or end of an axis, with the end resolved against the content on the next layout. This is the common way to snap a list to its top or bottom.

fn app() -> impl IntoElement {
    let mut scroll_controller = use_scroll_controller(ScrollConfig::default);

    rect()
        .child(
            Button::new()
                .on_press(move |_| {
                    scroll_controller.scroll_to(ScrollPosition::End, Direction::Vertical);
                })
                .child("Scroll to bottom"),
        )
        .child(
            ScrollView::new_controlled(scroll_controller)
                .children((0..100).map(|i| label().key(i).text(format!("Item {i}")))),
        )
}

For an exact pixel offset use scroll_to_y or scroll_to_x. The current position is available by converting the controller into a (i32, i32) tuple of (x, y) pixels, or calling position.

Animated scrolling

Scrolling to a position is instant by default. To animate, call animate_from with the current position before setting the target offset.

fn app() -> impl IntoElement {
    let mut scroll_controller = use_scroll_controller(ScrollConfig::default);

    rect()
        .child(
            Button::new()
                .on_press(move |_| {
                    let current = scroll_controller.position();
                    scroll_controller.animate_from(current);
                    scroll_controller.scroll_to_y(-500);
                })
                .child("Animate scroll"),
        )
        .child(
            ScrollView::new_controlled(scroll_controller)
                .children((0..100).map(|i| label().key(i).text(format!("Item {i}")))),
        )
}

Keeping scrollviews in sync

Pass the same ScrollController to several scrollviews to share a single scroll position. Moving any of them moves the rest.

fn app() -> impl IntoElement {
    let scroll_controller = use_scroll_controller(ScrollConfig::default);

    rect()
        .horizontal()
        .spacing(6.)
        .child(
            ScrollView::new_controlled(scroll_controller)
                .width(Size::flex(1.))
                .children((0..30).map(|i| label().key(i).text(format!("Left {i}")))),
        )
        .child(
            ScrollView::new_controlled(scroll_controller)
                .width(Size::flex(1.))
                .children((0..30).map(|i| label().key(i).text(format!("Right {i}")))),
        )
}

Starting position

The ScrollConfig passed to use_scroll_controller also decides where each axis starts. Set default_vertical_position to ScrollPosition::End to open a list already scrolled to the bottom.

fn app() -> impl IntoElement {
    let scroll_controller = use_scroll_controller(|| ScrollConfig {
        default_vertical_position: ScrollPosition::End,
        ..Default::default()
    });

    ScrollView::new_controlled(scroll_controller)
        .children((0..100).map(|i| label().key(i).text(format!("Item {i}"))))
}

Fields

bounds: State<Option<(Size2D, Size2D)>>

Implementations

impl ScrollController

pub fn new(x: i32, y: i32) -> Self

Creates a controller starting at the scroll position (x, y).

pub fn apply_layout(&mut self, content_size: Size2D, viewport_size: Size2D)

Updates the content and viewport bounds used to clamp scroll positions.

pub fn position(self) -> Point2D

Reads the current scroll position in pixels.

pub fn scroll_to_x(&mut self, to: i32) -> bool

Scrolls the horizontal axis to to pixels. Returns whether the position actually changed.

pub fn scroll_to_y(&mut self, to: i32) -> bool

Scrolls the vertical axis to to pixels. Returns whether the position actually changed.

pub fn scroll_to( &mut self, scroll_position: ScrollPosition, scroll_direction: Direction, )

Scrolls scroll_direction to scroll_position.

impl ScrollController

Follows the target held by a ScrollController.

pub fn animated_position(&self, target: Point2D) -> Point2D

Position to render, the animated one while a scroll animation is running.

pub fn animate_from(&mut self, current: Point2D)

Chases the controller position from current, keeping the current velocity.

pub fn begin_drag(&mut self)

Freezes the animation and starts a drag from the momentum it caught.

pub fn drag(&mut self, delta: Vector2D)

Feeds a drag movement into the tracked velocity.

pub fn release_drag(&mut self, from: Point2D, content: Size2D, viewport: Size2D)

Ends a drag, flinging when it was fast enough to be a flick.

pub fn stop(&mut self) -> Vector2D

Freezes the scroll where it is, returning the velocity it was moving at.

Trait Implementations

impl Clone for ScrollController

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for ScrollController

impl From<ScrollController> for (i32, i32)

fn from(val: ScrollController) -> Self

Reads the current (x, y) scroll position in pixels.

impl PartialEq for ScrollController

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for ScrollController