Add a DrivenScrollActivity.simulation constructor (flutter#166730)

I'd like to have a scroll activity that drives the scroll view through a
particular animation -- just like a DrivenScrollActivity does -- but
where the animation doesn't have an end point or duration that's known
when the animation begins.

(Concretely, this is to implement a "scroll to the end of history"
button in the Zulip message list. The end point is maxScrollExtent...
except that maxScrollExtent while in the middle of history is only an
estimate, and will change as the list view scrolls through shorter and
longer messages.)

That means the animation is naturally described by a Simulation, but not
by the parameters accepted by the current DrivenScrollActivity
constructor, or by the animateTo method which wraps it.

I think this can be handled quite cleanly with an alternate constructor
on DrivenScrollActivity, one that accepts a Simulation instead of the
from/to/duration/curve parameters accepted by the default constructor.
The new constructor is very similar to the constructor of
BallisticScrollActivity.

Most of the changes here are in revising the docs of both
DrivenScrollActivity and BallisticScrollActivity. The docs had
characterized the difference between the two as about using a Simulation
vs. the from/to/duration/curve animation parameters, but I think that's
never been the most important difference between them: the key
difference is really the `goBallistic` calls in BallisticScrollActivity,
particularly in `applyNewDimensions`, and the implications those have
for how the simulation needs to relate to the scroll physics. So this
rewrites the docs to describe that.

Author: gnprice

packages/flutter/lib/src/widgets/scroll_activity.dart

@@ -557,21 +557,36 @@ class DragScrollActivity extends ScrollActivity {
   }
 }
 
-/// An activity that animates a scroll view based on a physics [Simulation].
+/// The activity a scroll view performs after being set into motion.
 ///
-/// A [BallisticScrollActivity] is typically used when the user lifts their
-/// finger off the screen to continue the scrolling gesture with the current velocity.
+/// For example, a [BallisticScrollActivity] is used when the user
+/// lifts their finger off the screen after a [DragScrollActivity],
+/// to continue the scrolling motion starting from the current velocity.
 ///
 /// [BallisticScrollActivity] is also used to restore a scroll view to a valid
 /// scroll offset when the geometry of the scroll view changes. In these
 /// situations, the [Simulation] typically starts with a zero velocity.
 ///
+/// The scrolling will be driven by the given [Simulation]. If a
+/// [BallisticScrollActivity] is in progress when the scroll metrics change,
+/// then the activity will be replaced with a new ballistic activity starting
+/// from the current velocity (see [ScrollPhysics.createBallisticSimulation]).
+/// To ensure the user perceives smooth motion across such a change,
+/// the simulation should typically be the result
+/// of [ScrollPhysics.createBallisticSimulation]
+/// for the scroll physics of the scroll view.
+///
 /// See also:
 ///
-///  * [DrivenScrollActivity], which animates a scroll view based on a set of
-///    animation parameters.
+///  * [DrivenScrollActivity], which drives a scroll view through
+///    a given animation, without resetting to a ballistic simulation
+///    when scroll metrics change.
 class BallisticScrollActivity extends ScrollActivity {
-  /// Creates an activity that animates a scroll view based on a [simulation].
+  /// Creates an activity that sets into motion a scroll view.
+  ///
+  /// The simulation should typically be the result
+  /// of [ScrollPhysics.createBallisticSimulation]
+  /// for the scroll physics of the scroll view.
   BallisticScrollActivity(
     super.delegate,
     Simulation simulation,
@@ -662,18 +677,24 @@ class BallisticScrollActivity extends ScrollActivity {
   }
 }
 
-/// An activity that animates a scroll view based on animation parameters.
+/// An activity that drives a scroll view through a given animation.
 ///
 /// For example, a [DrivenScrollActivity] is used to implement
 /// [ScrollController.animateTo].
 ///
+/// The scrolling will be driven by the given animation parameters
+/// or the given [Simulation].
+///
+/// Unlike a [BallisticScrollActivity], if a [DrivenScrollActivity] is
+/// in progress when the scroll metrics change, the activity will continue
+/// with its original animation.
+///
 /// See also:
 ///
-///  * [BallisticScrollActivity], which animates a scroll view based on a
-///    physics [Simulation].
+///  * [BallisticScrollActivity], which sets into motion a scroll view.
 class DrivenScrollActivity extends ScrollActivity {
-  /// Creates an activity that animates a scroll view based on animation
-  /// parameters.
+  /// Creates an activity that drives a scroll view through an animation
+  /// given by animation parameters.
   DrivenScrollActivity(
     super.delegate, {
     required double from,
@@ -697,6 +718,25 @@ class DrivenScrollActivity extends ScrollActivity {
           ).whenComplete(_end); // won't trigger if we dispose _controller before it completes.
   }
 
+  /// Creates an activity that drives a scroll view through an animation
+  /// given by a [Simulation].
+  DrivenScrollActivity.simulation(
+    super.delegate,
+    Simulation simulation, {
+    required TickerProvider vsync,
+  }) {
+    _completer = Completer<void>();
+    _controller =
+        AnimationController.unbounded(
+            debugLabel: objectRuntimeType(this, 'DrivenScrollActivity'),
+            vsync: vsync,
+          )
+          ..addListener(_tick)
+          ..animateWith(
+            simulation,
+          ).whenComplete(_end); // won't trigger if we dispose _controller before it completes.
+  }
+
   late final Completer<void> _completer;
   late final AnimationController _controller;
 

packages/flutter/test/widgets/scroll_activity_test.dart

@@ -4,6 +4,7 @@
 
 import 'package:flutter/gestures.dart';
 import 'package:flutter/material.dart';
+import 'package:flutter/physics.dart';
 import 'package:flutter/scheduler.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:leak_tracker_flutter_testing/leak_tracker_flutter_testing.dart';
@@ -246,6 +247,34 @@ void main() {
     await tester.pumpAndSettle();
   });
 
+  testWidgets('DrivenScrollActivity.simulation constructor', (WidgetTester tester) async {
+    final ScrollController controller = ScrollController();
+    addTearDown(controller.dispose);
+    await tester.pumpWidget(
+      Directionality(
+        textDirection: TextDirection.ltr,
+        child: ListView(controller: controller, children: children(10)),
+      ),
+    );
+    final ScrollPositionWithSingleContext position =
+        controller.position as ScrollPositionWithSingleContext;
+
+    const double g = 9.8;
+    position.beginActivity(
+      DrivenScrollActivity.simulation(
+        position,
+        vsync: position.context.vsync,
+        GravitySimulation(g, 0, 1000, 0),
+      ),
+    );
+    await tester.pump();
+    expect(position.pixels, 0.0);
+    await tester.pump(const Duration(seconds: 1));
+    expect(position.pixels, (1 / 2) * g);
+    await tester.pump(const Duration(seconds: 1));
+    expect(position.pixels, 2 * g);
+  });
+
   test('$ScrollActivity dispatches memory events', () async {
     await expectLater(
       await memoryEvents(