SpringDescription parameter for the AnimationController fling method (flutter#65057)

Author: nt4f04uNd

AUTHORS

@@ -68,3 +68,4 @@ meritozh <ah841814092@gmail.com>
 Terrence Addison Tandijono(flotilla) <terrenceaddison32@gmail.com>
 YeungKC <flutter@yeungkc.com>
 Nobuhiro Tabuki <japanese.around30@gmail.com>
+nt4f04uNd <nt4f04und@gmail.com>

packages/flutter/lib/src/animation/animation_controller.dart

@@ -645,18 +645,27 @@ class AnimationController extends Animation<double>
     _checkStatusChanged();
   }
 
-  /// Drives the animation with a critically damped spring (within [lowerBound]
-  /// and [upperBound]) and initial velocity.
+  /// Drives the animation with a spring (within [lowerBound] and [upperBound])
+  /// and initial velocity.
   ///
   /// If velocity is positive, the animation will complete, otherwise it will
   /// dismiss.
   ///
+  /// The [springDescription] parameter can be used to specify a custom [SpringType.criticallyDamped]
+  /// or [SpringType.overDamped] spring to drive the animation with. Defaults to null, which uses a
+  /// [SpringType.criticallyDamped] spring. See [SpringDescription.withDampingRatio] for how
+  /// to create a suitable [SpringDescription].
+  ///
+  /// The resulting spring simulation cannot be of type [SpringType.underDamped],
+  /// as this can lead to unexpected look of the produced animation.
+  ///
   /// Returns a [TickerFuture] that completes when the animation is complete.
   ///
   /// The most recently returned [TickerFuture], if any, is marked as having been
   /// canceled, meaning the future never completes and its [TickerFuture.orCancel]
   /// derivative future completes with a [TickerCanceled] error.
-  TickerFuture fling({ double velocity = 1.0, AnimationBehavior? animationBehavior }) {
+  TickerFuture fling({ double velocity = 1.0, SpringDescription? springDescription, AnimationBehavior? animationBehavior }) {
+    springDescription ??= _kFlingSpringDescription;
     _direction = velocity < 0.0 ? _AnimationDirection.reverse : _AnimationDirection.forward;
     final double target = velocity < 0.0 ? lowerBound - _kFlingTolerance.distance
                                          : upperBound + _kFlingTolerance.distance;
@@ -673,8 +682,13 @@ class AnimationController extends Animation<double>
           break;
       }
     }
-    final Simulation simulation = SpringSimulation(_kFlingSpringDescription, value, target, velocity * scale)
+    final SpringSimulation simulation = SpringSimulation(springDescription, value, target, velocity * scale)
       ..tolerance = _kFlingTolerance;
+    assert(
+      simulation.type != SpringType.underDamped,
+      'The resulting spring simulation is of type SpringType.underDamped.\n'
+      'This can lead to unexpected look of the animation, please adjust the springDescription parameter'
+    );
     stop();
     return _startSimulation(simulation);
   }

packages/flutter/test/animation/animation_controller_test.dart

@@ -253,6 +253,29 @@ void main() {
     largeRangeController.stop();
   });
 
+  test('Custom springDescription can be applied', () {
+    final AnimationController controller = AnimationController(
+      vsync: const TestVSync(),
+    );
+    final AnimationController customSpringController = AnimationController(
+      vsync: const TestVSync(),
+    );
+
+    controller.fling();
+    // Will produce longer and smoother animation than the default.
+    customSpringController.fling(
+      springDescription: SpringDescription.withDampingRatio(
+        mass: 0.01,
+        stiffness: 10.0,
+        ratio: 2.0,
+      ),
+    );
+    tick(const Duration(milliseconds: 0));
+    tick(const Duration(milliseconds: 50));
+
+    expect(customSpringController.value < controller.value, true);
+  });
+
   test('lastElapsedDuration control test', () {
     final AnimationController controller = AnimationController(
       duration: const Duration(milliseconds: 100),