Struct ScrollController 

pub struct ScrollController {
    pub offset: Atom<[f32; 2]>,
    pub content_size: Atom<[f32; 2]>,
    pub viewport_size: Atom<[f32; 2]>,
    /* private fields */
}

Controls a [ScrollView] programmatically.

All clones share the same underlying atoms so that separate handles can observe and mutate the scroll position from different call sites.

Fields

offset: Atom<[f32; 2]>

Current scroll offset [x, y] in pixels.

content_size: Atom<[f32; 2]>

viewport_size: Atom<[f32; 2]>

Implementations

impl ScrollController

pub const DRAG_SLOP: f32 = 6.0

Drag slop (Phase 32 bug fix, user-reported): a press must travel this many logical px from its DOWN point before drag-to-pan engages. Without it, the 1-3 px of natural pointer jitter during a plain click pans the view — visible whenever the click lands on non-interactive content inside a scroll view (a hit falls through to the viewport’s positional drag region). 6 px matches the common touch-slop convention (small enough that intentional drags feel instant, large enough that clicks never pan).

pub fn for_ctx(ctx: &mut Context) -> Self

Create (or retrieve) a controller persisted in component state — the scroll position survives rebuilds. Follows the hook rules: call unconditionally in build(), stable order.

pub fn new() -> Self

pub fn scroll_to(&self, x: f32, y: f32)

Jump to an absolute position, clamped to valid bounds.

pub fn scroll_to_top(&self)

Scroll to the top (y = 0), preserving x.

pub fn scroll_to_bottom(&self)

Scroll to the bottom (y = content_height − viewport_height), preserving x.

pub fn scroll_by(&self, dx: f32, dy: f32)

Add (dx, dy) to the current offset, clamped to valid bounds.

pub fn offset(&self) -> [f32; 2]

Returns the current [offset_x, offset_y].

pub fn save_position(&self) -> [f32; 2]

Snapshot the current position for later restoration.

pub fn restore_position(&self, pos: [f32; 2])

Restore a previously saved position.

pub fn drag_delta(&self, x: f32, y: f32) -> (f32, f32)

Streamed absolute drag position → delta since the last call. Returns (0, 0) on the first call of a drag AND while the pointer stays within Self::DRAG_SLOP of the down point — see its doc. Call end_drag on release so the next drag starts fresh.

pub fn end_drag(&self)

Clears drag-position tracking — call on release so the next drag doesn’t diff against a stale point.

pub fn track_velocity(&self, dt: f32)

Recomputes velocity from the real offset delta since the last call, in px/s — the actual measured drag/momentum speed, never an assumed constant. Call once per frame while dragging or coasting. Clamped to MAX_VELOCITY — see its doc comment for why.

pub fn velocity(&self) -> [f32; 2]

The most recently tracked velocity (px/s) — see track_velocity.

pub fn set_velocity(&self, v: [f32; 2])

Sets the tracked velocity directly (px/s) — for input sources that aren’t a continuous drag track_velocity can measure frame-to-frame (e.g. a discrete wheel/trackpad event), so coast still has a real speed to decay from once the events stop arriving. Clamped to MAX_VELOCITY — see its doc comment for why.

pub fn was_pressed(&self) -> bool

Whether this controller was pressed as of the last frame — used to detect the true→false transition that hands off to momentum.

pub fn set_was_pressed(&self, v: bool)

pub fn mark_wheel_active(&self)

Called by a wheel/trackpad scroll callback when it fires — resets the idle clock to 0.

pub fn advance_wheel_idle(&self, dt: f32)

Advances the wheel-idle clock by one real frame — call once per frame regardless of whether a wheel event landed.

pub fn wheel_recently_active(&self) -> bool

Whether a wheel/trackpad event landed within the last WHEEL_IDLE_GRACE real seconds — the caller uses this to hold off coast’s momentum/spring-back until the gesture has genuinely stopped, not just “no event in this exact frame” (see wheel_idle_time’s doc comment for why a single-frame check jittered).

pub fn velocity_magnitude(&self) -> f32

Current drag/momentum speed (px/s), for callers that just need “is this still visibly moving” (e.g. an auto-hiding scrollbar) without caring about direction. Zero once coast has fully settled.

pub fn is_overscrolled(&self) -> bool

Whether the current offset sits past either bound — used by coast and by callers that need to keep a Bounce spring recovering even while something else (e.g. a still-live wheel-idle gate) is holding off the rest of coast’s own logic.

pub fn coast(&self, physics: ScrollPhysics, dt: f32) -> bool

Advances one frame of post-release momentum/bounce, using the real velocity track_velocity/set_velocity measured from actual input. Returns true while still moving/settling (caller should keep requesting frames); false once fully at rest.

pub fn stop_coasting(&self)

Hard-stops all coasting immediately and clamps the offset into bounds — used when animations are globally disabled, so release never coasts or bounces.

pub fn apply_momentum(&self, dx: f32, dy: f32, physics: ScrollPhysics)

Applies a (dx, dy) step to the offset. Under Bounce, overscroll is allowed but resisted (35% magnitude) while already out of bounds and moving further out; moving back toward bounds is full-speed. Every other physics hard-clamps, identical to scroll_by.

pub fn try_apply_delta(&self, dx: f32, dy: f32, physics: ScrollPhysics) -> bool

Like Self::apply_momentum, but reports whether the offset actually moved — false means this scroll is already fully exhausted in this exact direction (hard-clamped with nothing left, or already stretched to MAX_OVERSCROLL under Bounce) and the delta was NOT applied at all. Callers driving nested scroll chains (an inner ScrollView sitting inside an outer one) use this to decide whether to also offer the same delta to an enclosing scrollable ancestor: keep walking outward until one reports true, or the chain runs out.

pub fn settle_bounce(&self, spring_stiffness: f32, dt: f32) -> bool

Eases an out-of-bounds offset back to the nearest valid bound — called once velocity has settled while Bounce-configured and still overscrolled. Same exponential-ease shape as PaintCtx::animate_to. Returns true while still settling (caller should keep requesting frames); false once within bounds (nothing left to do).

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 Default for ScrollController

fn default() -> Self

Returns the “default value” for a type.