Struct ScrollController 

pub struct ScrollController { /* private fields */ }

Handle to drive and read a scrollable area programmatically.

By default a scrollable 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 scrollable 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 scrollables 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 queues a jump to the start or end of an axis, applied 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}")).into())),
        )
}

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.

Keeping scrollables in sync

Because a ScrollController is a cheap Copy handle, pass the same one to several scrollables and they 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}")).into())),
        )
        .child(
            ScrollView::new_controlled(scroll_controller)
                .width(Size::flex(1.))
                .children((0..30).map(|i| label().key(i).text(format!("Right {i}")).into())),
        )
}

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}")).into()))
}

Implementations

impl ScrollController

pub fn new(x: i32, y: i32, initial_requests: Vec<ScrollRequest>) -> Self

Creates a controller starting at scroll position (x, y) with a list of requests to apply.

pub fn managed( notifier: State<()>, requests: State<Vec<ScrollRequest>>, on_scroll: State<Callback<ScrollEvent, bool>>, get_scroll: State<Callback<(), (i32, i32)>>, ) -> Self

Builds a controller from externally owned state, letting the caller manage its storage.

pub fn use_apply(&mut self, width: f32, height: f32)

Applies any pending requests against the given content size. Called by the scrollable on every layout.

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, )

Queues a scroll of scroll_direction to scroll_position, applied on the next layout.

Trait Implementations

impl Clone for ScrollController

fn clone(&self) -> ScrollController

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: &ScrollController) -> bool

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for ScrollController