477 lines
16 KiB
Rust
477 lines
16 KiB
Rust
//! `ScrollArea`: a fixed child, slid about by a [`ScrollController`].
|
|
//!
|
|
//! **`docs/SCROLL.md` is the overview** -- the one sign convention, what
|
|
//! `amt` means, and how this differs from a `LazySpan`, which scrolls
|
|
//! itself. Read it first; this file is the detail.
|
|
|
|
use crate::prelude::*;
|
|
use std::time::Instant;
|
|
|
|
/// A scrolling view that moves one fixed child as a subtree.
|
|
pub struct ScrollArea {
|
|
inner: StrongWidget,
|
|
ctl: ScrollController,
|
|
container_len: f32,
|
|
content_len: Option<f32>,
|
|
}
|
|
|
|
impl Scrollable for ScrollArea {
|
|
fn controller(&self) -> &ScrollController {
|
|
&self.ctl
|
|
}
|
|
|
|
fn controller_mut(&mut self) -> &mut ScrollController {
|
|
&mut self.ctl
|
|
}
|
|
}
|
|
|
|
impl Widget for ScrollArea {
|
|
fn tick(&mut self, now: Instant) -> bool {
|
|
self.tick_fling(now)
|
|
}
|
|
|
|
fn draw(&mut self, painter: &mut Painter) {
|
|
let axis = self.ctl.axis();
|
|
let container_len = painter.px_size().axis(axis);
|
|
self.container_len = container_len;
|
|
self.ctl.set_density(painter.density());
|
|
|
|
let delta = self.ctl.take_delta();
|
|
let travelled = self.ctl.amt() - delta;
|
|
self.ctl.set_amt(travelled);
|
|
|
|
let hint = self.content_len.unwrap_or(container_len);
|
|
let used = painter
|
|
.widget_within(&self.inner, self.child_region(hint))
|
|
.size();
|
|
|
|
let measured = used
|
|
.axis(axis)
|
|
.apply_rest(painter.density())
|
|
.to_abs(container_len);
|
|
self.content_len = Some(measured);
|
|
let range = (measured - container_len).max(0.0);
|
|
|
|
let amt = if self.ctl.pinned_to_end() && delta == 0.0 {
|
|
range
|
|
} else {
|
|
travelled.clamp(0.0, range)
|
|
};
|
|
self.ctl.set_amt(amt);
|
|
self.ctl.set_pinned_to_end(amt >= range);
|
|
self.ctl.set_travel(Travel {
|
|
back: amt,
|
|
fwd: range - amt,
|
|
});
|
|
|
|
let size = painter
|
|
.place(&self.inner, self.child_region(measured))
|
|
.size();
|
|
painter.set_size(size);
|
|
}
|
|
}
|
|
|
|
impl ScrollArea {
|
|
/// `pin` says which end this area opens at and clings to -- see
|
|
/// [`Pin`], and `WidgetLike::scrollable`, which is how one of these is
|
|
/// normally built.
|
|
pub fn new(inner: StrongWidget, axis: Axis, pin: Pin) -> Self {
|
|
Self {
|
|
inner,
|
|
// A fixed child is laid out from the box's negative edge
|
|
// onward, always, so the end of its content is the positive
|
|
// one -- which is what makes `Pin::End` and `Pin::Pos` the
|
|
// same pin here and different ones in a reversed `LazySpan`.
|
|
ctl: ScrollController::new(Dir::new(axis, Sign::Pos), pin),
|
|
container_len: 0.0,
|
|
content_len: None,
|
|
}
|
|
}
|
|
|
|
/// A content-sized box offset by the current scroll amount.
|
|
fn child_region(&self, content_len: f32) -> UiRegion {
|
|
let axis = self.ctl.axis();
|
|
let mut region = UiRegion::FULL;
|
|
region.axis_mut(axis).end = region.axis(axis).start.offset(content_len);
|
|
region.offset(Vec2::from_axis(axis, -self.ctl.amt(), 0.0))
|
|
}
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod tests {
|
|
use super::*;
|
|
use crate::layout_tests::TestRsc;
|
|
use crate::sense::{CursorButton, DRAG_SLOP, PointerRequests};
|
|
use iris_core::UiData;
|
|
use std::time::Duration;
|
|
|
|
/// A scroll area with 1000px of content in a 100px box, drawn once and
|
|
/// settled somewhere in the middle so a drag has room in both
|
|
/// directions.
|
|
///
|
|
/// Built and rendered for real rather than assembled field by field,
|
|
/// because a delta is spent in `draw` now (the controller banks it, and
|
|
/// only a layout knows where the content ends) -- so a test that never
|
|
/// draws would watch `amt` never move and read that as a broken
|
|
/// gesture.
|
|
fn area() -> (Fixture, WidgetId) {
|
|
area_on(Axis::Y)
|
|
}
|
|
|
|
/// The same fixture on either axis -- a code fence pans sideways
|
|
/// through one of these exactly as a field pans down, and the pair of
|
|
/// them is what caught a fling that only worked vertically.
|
|
fn area_on(axis: Axis) -> (Fixture, WidgetId) {
|
|
let mut rsc = TestRsc {
|
|
ui: UiData::default(),
|
|
};
|
|
let fill = rsc.ui.widgets.add_strong(Rect::new(UiColor::WHITE)).any();
|
|
let id = fill.id();
|
|
let long = Some(Len::abs(1000.0));
|
|
let tall = rsc.ui.widgets.add_strong(Sized {
|
|
inner: fill,
|
|
x: (axis == Axis::X).then_some(long).flatten(),
|
|
y: (axis == Axis::Y).then_some(long).flatten(),
|
|
});
|
|
let area = rsc
|
|
.ui
|
|
.widgets
|
|
.add_strong(ScrollArea::new(tall.any(), axis, Pin::Start));
|
|
let weak = area.weak();
|
|
let root = area.any();
|
|
let mut render = UiRenderState::new();
|
|
render.resize((100.0, 100.0));
|
|
render.update(&root, &mut rsc);
|
|
|
|
let mut fixture = Fixture {
|
|
rsc,
|
|
area: weak,
|
|
root,
|
|
render,
|
|
};
|
|
// 400px in, which is the middle of the 900px of travel this
|
|
// content has.
|
|
fixture.get().scroll(-400.0);
|
|
fixture.draw();
|
|
assert!((fixture.amt() - 400.0).abs() < 0.01);
|
|
(fixture, id)
|
|
}
|
|
|
|
/// The area under test with everything needed to draw it -- the drag
|
|
/// tests all do the same three things (reach the widget, draw, read
|
|
/// `amt`) and each of the three is a line of arena plumbing.
|
|
struct Fixture {
|
|
rsc: TestRsc,
|
|
area: WeakWidget<ScrollArea>,
|
|
root: StrongWidget,
|
|
render: UiRenderState,
|
|
}
|
|
|
|
impl Fixture {
|
|
fn get(&mut self) -> &mut ScrollArea {
|
|
self.rsc.ui.widgets.get_mut(&self.area).unwrap()
|
|
}
|
|
|
|
fn draw(&mut self) {
|
|
self.render.update(&self.root, &mut self.rsc);
|
|
}
|
|
|
|
fn amt(&self) -> f32 {
|
|
self.rsc.ui.widgets.get(&self.area).unwrap().amt()
|
|
}
|
|
|
|
/// One frame of a fling, the way `UiData::tick_animations` drives
|
|
/// it: tick, then draw. Answers whether it is still going.
|
|
fn fling_frame(&mut self, now: Instant) -> bool {
|
|
let still = self.get().tick(now);
|
|
self.draw();
|
|
still
|
|
}
|
|
}
|
|
|
|
/// One frame of a touch gesture, followed by the draw that spends it.
|
|
fn press(f: &mut Fixture, id: WidgetId, sense: CursorSense, y: f32, t: Instant) {
|
|
drag(f, id, sense, Vec2::new(0.0, y), t);
|
|
}
|
|
|
|
/// The same, for a gesture whose position is not on the Y axis.
|
|
fn drag(f: &mut Fixture, id: WidgetId, sense: CursorSense, pos: Vec2, t: Instant) {
|
|
let pointer = PointerRequests::default();
|
|
let flung = f.get().drag(&pointer, id, sense, pos, t);
|
|
// What `WidgetLike::scrollable`'s own handler does with the
|
|
// answer, and the half a fling does not move without.
|
|
if flung {
|
|
let id = f.area.id();
|
|
f.rsc.ui.animate(id);
|
|
}
|
|
f.draw();
|
|
}
|
|
|
|
#[test]
|
|
fn a_vertical_finger_drag_pans_the_content_with_the_finger() {
|
|
let (mut f, id) = area();
|
|
let t = Instant::now();
|
|
press(
|
|
&mut f,
|
|
id,
|
|
CursorSense::PressStart(CursorButton::Left),
|
|
0.0,
|
|
t,
|
|
);
|
|
// Finger down by well past the slop: the content follows it down,
|
|
// which for this widget means *less* `amt`.
|
|
press(
|
|
&mut f,
|
|
id,
|
|
CursorSense::Pressing(CursorButton::Left),
|
|
DRAG_SLOP + 30.0,
|
|
t + Duration::from_millis(20),
|
|
);
|
|
assert!(
|
|
(f.amt() - 370.0).abs() < 0.01,
|
|
"expected the 30px past the slop to be applied downward, got amt={}",
|
|
f.amt()
|
|
);
|
|
// ...and the next frame's motion is a plain per-frame delta.
|
|
press(
|
|
&mut f,
|
|
id,
|
|
CursorSense::Pressing(CursorButton::Left),
|
|
DRAG_SLOP + 50.0,
|
|
t + Duration::from_millis(40),
|
|
);
|
|
assert!((f.amt() - 350.0).abs() < 0.01, "amt={}", f.amt());
|
|
}
|
|
|
|
/// The half the change had no reason to touch: a press that never
|
|
/// leaves the slop is a tap, and must move nothing at all -- otherwise
|
|
/// every tap on a scrollable field nudges its text.
|
|
#[test]
|
|
fn a_press_that_stays_inside_the_slop_does_not_scroll() {
|
|
let (mut f, id) = area();
|
|
let t = Instant::now();
|
|
press(
|
|
&mut f,
|
|
id,
|
|
CursorSense::PressStart(CursorButton::Left),
|
|
0.0,
|
|
t,
|
|
);
|
|
for (i, y) in [1.0, -2.0, DRAG_SLOP - 0.5].into_iter().enumerate() {
|
|
press(
|
|
&mut f,
|
|
id,
|
|
CursorSense::Pressing(CursorButton::Left),
|
|
y,
|
|
t + Duration::from_millis(10 * (i as u64 + 1)),
|
|
);
|
|
}
|
|
press(
|
|
&mut f,
|
|
id,
|
|
CursorSense::PressEnd(CursorButton::Left),
|
|
DRAG_SLOP - 0.5,
|
|
t + Duration::from_millis(50),
|
|
);
|
|
assert!(
|
|
(f.amt() - 400.0).abs() < 0.01,
|
|
"a tap scrolled: amt={}",
|
|
f.amt()
|
|
);
|
|
}
|
|
|
|
/// A horizontal drag is not this widget's gesture: it must stay put
|
|
/// rather than pick up the vertical noise in a sideways swipe.
|
|
#[test]
|
|
fn a_horizontal_drag_does_not_scroll() {
|
|
let (mut f, id) = area();
|
|
let t = Instant::now();
|
|
drag(
|
|
&mut f,
|
|
id,
|
|
CursorSense::PressStart(CursorButton::Left),
|
|
Vec2::new(0.0, 0.0),
|
|
t,
|
|
);
|
|
drag(
|
|
&mut f,
|
|
id,
|
|
CursorSense::Pressing(CursorButton::Left),
|
|
Vec2::new(120.0, 3.0),
|
|
t + Duration::from_millis(20),
|
|
);
|
|
assert!((f.amt() - 400.0).abs() < 0.01, "amt={}", f.amt());
|
|
}
|
|
|
|
/// Panning stops at the ends of the content rather than running off,
|
|
/// which is `update_amt`'s clamp -- checked through `drag` so the two
|
|
/// cannot drift apart.
|
|
#[test]
|
|
fn a_pan_past_the_end_clamps_instead_of_running_off() {
|
|
let (mut f, id) = area();
|
|
let t = Instant::now();
|
|
drag(
|
|
&mut f,
|
|
id,
|
|
CursorSense::PressStart(CursorButton::Left),
|
|
Vec2::new(0.0, 0.0),
|
|
t,
|
|
);
|
|
drag(
|
|
&mut f,
|
|
id,
|
|
CursorSense::Pressing(CursorButton::Left),
|
|
Vec2::new(0.0, 5000.0),
|
|
t + Duration::from_millis(20),
|
|
);
|
|
assert!((f.amt() - 0.0).abs() < 0.01, "amt={}", f.amt());
|
|
}
|
|
|
|
/// Iris, 2026-09-08: "Flinging doesn't work in horizontal scroll
|
|
/// areas. Flinging should be enabled by default in all scroll areas
|
|
/// on android to match composes behavior." A release with real
|
|
/// velocity coasts, decelerating, and settles on its own.
|
|
#[test]
|
|
fn a_released_pan_flings_and_settles() {
|
|
for axis in [Axis::X, Axis::Y] {
|
|
let (mut f, id) = area_on(axis);
|
|
let t = Instant::now();
|
|
let at = |d: f32| Vec2::from_axis(axis, d, 0.0);
|
|
|
|
drag(
|
|
&mut f,
|
|
id,
|
|
CursorSense::PressStart(CursorButton::Left),
|
|
at(0.0),
|
|
t,
|
|
);
|
|
// Four samples 8ms apart, accelerating away from the start --
|
|
// three is the fewest `VelocityTracker`'s quadratic fit can
|
|
// use, so this is a gesture that genuinely has a velocity.
|
|
for (i, d) in [-40.0, -100.0, -180.0, -280.0].into_iter().enumerate() {
|
|
drag(
|
|
&mut f,
|
|
id,
|
|
CursorSense::Pressing(CursorButton::Left),
|
|
at(d),
|
|
t + Duration::from_millis(8 * (i as u64 + 1)),
|
|
);
|
|
}
|
|
let at_release = f.amt();
|
|
drag(
|
|
&mut f,
|
|
id,
|
|
CursorSense::PressEnd(CursorButton::Left),
|
|
at(-280.0),
|
|
t + Duration::from_millis(32),
|
|
);
|
|
assert!(
|
|
f.get().is_scrolling(),
|
|
"{axis:?}: a released pan with velocity must fling"
|
|
);
|
|
|
|
// Frames at 8ms until it stops, with each step no longer than
|
|
// the one before it -- a coast that does not decelerate is
|
|
// the linear-spline bug this crate has had once already.
|
|
let mut last_step = f32::INFINITY;
|
|
let mut ticks = 0;
|
|
let mut now = t + Duration::from_millis(32);
|
|
while f.fling_frame(now) {
|
|
let before = f.amt();
|
|
now += Duration::from_millis(8);
|
|
f.fling_frame(now);
|
|
let step = (f.amt() - before).abs();
|
|
assert!(
|
|
step <= last_step + 0.01,
|
|
"{axis:?}: the fling sped up: {last_step} then {step}"
|
|
);
|
|
last_step = step;
|
|
ticks += 1;
|
|
assert!(ticks < 10_000, "{axis:?}: the fling never settled");
|
|
}
|
|
assert!(
|
|
f.amt() > at_release,
|
|
"{axis:?}: the fling moved the content the wrong way: {at_release} -> {}",
|
|
f.amt()
|
|
);
|
|
}
|
|
}
|
|
|
|
/// The wall: a fling must not spend its remaining distance on content
|
|
/// that is not there. Released hard toward the start, it settles
|
|
/// exactly on it.
|
|
#[test]
|
|
fn a_fling_stops_at_the_end_of_the_content() {
|
|
// Both walls. A positive delta is applied as `amt -= delta`, so a
|
|
// positive velocity runs toward the start of the content and a
|
|
// negative one toward its end; 1000px of content in a 100px box
|
|
// leaves `amt` in 0..=900.
|
|
for (velocity, wall) in [(50_000.0f32, 0.0f32), (-50_000.0, 900.0)] {
|
|
let (mut f, _id) = area();
|
|
f.get().fling(velocity);
|
|
let t = Instant::now();
|
|
let mut now = t;
|
|
for _ in 0..1_000 {
|
|
if !f.fling_frame(now) {
|
|
break;
|
|
}
|
|
now += Duration::from_millis(8);
|
|
}
|
|
assert!(
|
|
!f.get().is_scrolling(),
|
|
"the fling toward {wall} ran past the content"
|
|
);
|
|
assert!(
|
|
(f.amt() - wall).abs() < 0.01,
|
|
"it should have settled on {wall}, got amt={}",
|
|
f.amt()
|
|
);
|
|
}
|
|
}
|
|
|
|
/// A finger on coasting content stops it there, from the first
|
|
/// sample, with no `DRAG_SLOP` to wait out -- the catch
|
|
/// `DragArbiter::press_start` describes, which a scroll area needs
|
|
/// for the same reason a list does now that it can coast at all.
|
|
#[test]
|
|
fn a_press_on_a_coasting_area_catches_it() {
|
|
let (mut f, id) = area();
|
|
f.get().fling(-4_000.0);
|
|
let t = Instant::now();
|
|
f.fling_frame(t);
|
|
f.fling_frame(t + Duration::from_millis(8));
|
|
let caught_at = f.amt();
|
|
assert!(f.get().is_scrolling(), "the fixture must still be moving");
|
|
|
|
let down = t + Duration::from_millis(16);
|
|
drag(
|
|
&mut f,
|
|
id,
|
|
CursorSense::PressStart(CursorButton::Left),
|
|
Vec2::new(0.0, 0.0),
|
|
down,
|
|
);
|
|
assert!(!f.get().is_scrolling(), "a touch-down must end the fling");
|
|
assert!(
|
|
(f.amt() - caught_at).abs() < 0.01,
|
|
"the down itself must not move the content, only stop it"
|
|
);
|
|
|
|
// A move well under `DRAG_SLOP` still tracks the finger, because
|
|
// this press caught something that was moving.
|
|
drag(
|
|
&mut f,
|
|
id,
|
|
CursorSense::Pressing(CursorButton::Left),
|
|
Vec2::new(0.0, 2.0),
|
|
down + Duration::from_millis(8),
|
|
);
|
|
assert!(
|
|
(f.amt() - (caught_at - 2.0)).abs() < 0.01,
|
|
"a caught press must pan from its first sample: {} -> {}",
|
|
caught_at,
|
|
f.amt()
|
|
);
|
|
}
|
|
}
|