Convert drag gestures to use details objects (#4343)

Previously we supplied individual parameters to the various drag and pan
callbacks. However, that approach isn't extensible because each new
parameter is a breaking change to the API.

This patch makes a one-time breaking change to the API to provide a
"details" object that we can extend over time as we need to expose more
information. The first planned extension is adding enough information to
accurately produce an overscroll glow on Android.

dev/manual_tests/mozart.dart

@@ -48,7 +48,7 @@ class WindowDecoration extends StatelessWidget {
   final WindowSide side;
   final Color color;
   final GestureTapCallback onTap;
-  final GesturePanUpdateCallback onPanUpdate;
+  final GestureDragUpdateCallback onPanUpdate;
 
   @override
   Widget build(BuildContext context) {
@@ -106,18 +106,18 @@ class _WindowState extends State<Window> {
   Offset _offset = Offset.zero;
   Size _size = _kInitialWindowSize;
 
-  void _handleResizerDrag(Offset delta) {
+  void _handleResizerDrag(DragUpdateDetails details) {
     setState(() {
       _size = new Size(
-        math.max(0.0, _size.width + delta.dx),
-        math.max(0.0, _size.height + delta.dy)
+        math.max(0.0, _size.width + details.delta.dx),
+        math.max(0.0, _size.height + details.delta.dy)
       );
     });
   }
 
-  void _handleRepositionDrag(Offset delta) {
+  void _handleRepositionDrag(DragUpdateDetails details) {
     setState(() {
-      _offset += delta;
+      _offset += details.delta;
     });
   }
 

packages/flutter/lib/src/material/bottom_sheet.dart

@@ -97,17 +97,17 @@ class _BottomSheetState extends State<BottomSheet> {
 
   bool get _dismissUnderway => config.animationController.status == AnimationStatus.reverse;
 
-  void _handleDragUpdate(double delta) {
+  void _handleDragUpdate(DragUpdateDetails details) {
     if (_dismissUnderway)
       return;
-    config.animationController.value -= delta / (_childHeight ?? delta);
+    config.animationController.value -= details.primaryDelta / (_childHeight ?? details.primaryDelta);
   }
 
-  void _handleDragEnd(Velocity velocity) {
+  void _handleDragEnd(DragEndDetails details) {
     if (_dismissUnderway)
       return;
-    if (velocity.pixelsPerSecond.dy > _kMinFlingVelocity) {
-      double flingVelocity = -velocity.pixelsPerSecond.dy / _childHeight;
+    if (details.velocity.pixelsPerSecond.dy > _kMinFlingVelocity) {
+      double flingVelocity = -details.velocity.pixelsPerSecond.dy / _childHeight;
       config.animationController.fling(velocity: flingVelocity);
       if (flingVelocity < 0.0)
         config.onClosing();

packages/flutter/lib/src/material/drawer.dart

@@ -173,7 +173,7 @@ class DrawerControllerState extends State<DrawerController> {
 
   AnimationController _controller;
 
-  void _handleDragDown(Point position) {
+  void _handleDragDown(DragDownDetails details) {
     _controller.stop();
     _ensureHistoryEntry();
   }
@@ -195,15 +195,15 @@ class DrawerControllerState extends State<DrawerController> {
     return _kWidth; // drawer not being shown currently
   }
 
-  void _move(double delta) {
-    _controller.value += delta / _width;
+  void _move(DragUpdateDetails details) {
+    _controller.value += details.primaryDelta / _width;
   }
 
-  void _settle(Velocity velocity) {
+  void _settle(DragEndDetails details) {
     if (_controller.isDismissed)
       return;
-    if (velocity.pixelsPerSecond.dx.abs() >= _kMinFlingVelocity) {
-      _controller.fling(velocity: velocity.pixelsPerSecond.dx / _width);
+    if (details.velocity.pixelsPerSecond.dx.abs() >= _kMinFlingVelocity) {
+      _controller.fling(velocity: details.velocity.pixelsPerSecond.dx / _width);
     } else if (_controller.value < 0.5) {
       close();
     } else {

packages/flutter/lib/src/material/slider.dart

@@ -290,24 +290,24 @@ class _RenderSlider extends RenderConstrainedBox {
     return dragValue;
   }
 
-  void _handleDragStart(Point globalPosition) {
+  void _handleDragStart(DragStartDetails details) {
     if (onChanged != null) {
       _active = true;
-      _currentDragValue = (globalToLocal(globalPosition).x - _kReactionRadius) / _trackLength;
+      _currentDragValue = (globalToLocal(details.globalPosition).x - _kReactionRadius) / _trackLength;
       onChanged(_discretizedCurrentDragValue);
       _reactionController.forward();
       markNeedsPaint();
     }
   }
 
-  void _handleDragUpdate(double delta) {
+  void _handleDragUpdate(DragUpdateDetails details) {
     if (onChanged != null) {
-      _currentDragValue += delta / _trackLength;
+      _currentDragValue += details.primaryDelta / _trackLength;
       onChanged(_discretizedCurrentDragValue);
     }
   }
 
-  void _handleDragEnd(Velocity velocity) {
+  void _handleDragEnd(DragEndDetails details) {
     if (_active) {
       _active = false;
       _currentDragValue = 0.0;

packages/flutter/lib/src/material/switch.dart

@@ -270,21 +270,21 @@ class _RenderSwitch extends RenderToggleable {
 
   HorizontalDragGestureRecognizer _drag;
 
-  void _handleDragStart(Point globalPosition) {
+  void _handleDragStart(DragStartDetails details) {
     if (onChanged != null)
       reactionController.forward();
   }
 
-  void _handleDragUpdate(double delta) {
+  void _handleDragUpdate(DragUpdateDetails details) {
     if (onChanged != null) {
       position
         ..curve = null
         ..reverseCurve = null;
-      positionController.value += delta / _trackInnerLength;
+      positionController.value += details.primaryDelta / _trackInnerLength;
     }
   }
 
-  void _handleDragEnd(Velocity velocity) {
+  void _handleDragEnd(DragEndDetails details) {
     if (position.value >= 0.5)
       positionController.forward();
     else

packages/flutter/lib/src/material/time_picker.dart

@@ -489,24 +489,24 @@ class _DialState extends State<_Dial> {
   Point _position;
   Point _center;
 
-  void _handlePanStart(Point globalPosition) {
+  void _handlePanStart(DragStartDetails details) {
     assert(!_dragging);
     _dragging = true;
     RenderBox box = context.findRenderObject();
-    _position = box.globalToLocal(globalPosition);
+    _position = box.globalToLocal(details.globalPosition);
     double radius = box.size.shortestSide / 2.0;
     _center = new Point(radius, radius);
     _updateThetaForPan();
     _notifyOnChangedIfNeeded();
   }
 
-  void _handlePanUpdate(Offset delta) {
-    _position += delta;
+  void _handlePanUpdate(DragUpdateDetails details) {
+    _position += details.delta;
     _updateThetaForPan();
     _notifyOnChangedIfNeeded();
   }
 
-  void _handlePanEnd(Velocity velocity) {
+  void _handlePanEnd(DragEndDetails details) {
     assert(_dragging);
     _dragging = false;
     _position = null;

packages/flutter/lib/src/rendering/proxy_box.dart

@@ -2102,26 +2102,42 @@ class RenderSemanticsGestureHandler extends RenderProxyBox implements SemanticAc
 
   @override
   void handleSemanticScrollLeft() {
-    if (onHorizontalDragUpdate != null)
-      onHorizontalDragUpdate(size.width * -scrollFactor);
+    if (onHorizontalDragUpdate != null) {
+      final double primaryDelta = size.width * -scrollFactor;
+      onHorizontalDragUpdate(new DragUpdateDetails(
+        delta: new Offset(primaryDelta, 0.0), primaryDelta: primaryDelta
+      ));
+    }
   }
 
   @override
   void handleSemanticScrollRight() {
-    if (onHorizontalDragUpdate != null)
-      onHorizontalDragUpdate(size.width * scrollFactor);
+    if (onHorizontalDragUpdate != null) {
+      final double primaryDelta = size.width * scrollFactor;
+      onHorizontalDragUpdate(new DragUpdateDetails(
+        delta: new Offset(primaryDelta, 0.0), primaryDelta: primaryDelta
+      ));
+    }
   }
 
   @override
   void handleSemanticScrollUp() {
-    if (onVerticalDragUpdate != null)
-      onVerticalDragUpdate(size.height * -scrollFactor);
+    if (onVerticalDragUpdate != null) {
+      final double primaryDelta = size.height * -scrollFactor;
+      onVerticalDragUpdate(new DragUpdateDetails(
+        delta: new Offset(0.0, primaryDelta), primaryDelta: primaryDelta
+      ));
+    }
   }
 
   @override
   void handleSemanticScrollDown() {
-    if (onVerticalDragUpdate != null)
-      onVerticalDragUpdate(size.height * scrollFactor);
+    if (onVerticalDragUpdate != null) {
+      final double primaryDelta = size.height * scrollFactor;
+      onVerticalDragUpdate(new DragUpdateDetails(
+        delta: new Offset(0.0, primaryDelta), primaryDelta: primaryDelta
+      ));
+    }
   }
 }
 

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

@@ -151,7 +151,7 @@ class _DismissableState extends State<Dismissable> {
     return box.size;
   }
 
-  void _handleDragStart(_) {
+  void _handleDragStart(DragStartDetails details) {
     _dragUnderway = true;
     if (_moveController.isAnimating) {
       _dragExtent = _moveController.value * _findSize().width * _dragExtent.sign;
@@ -165,11 +165,12 @@ class _DismissableState extends State<Dismissable> {
     });
   }
 
-  void _handleDragUpdate(double delta) {
+  void _handleDragUpdate(DragUpdateDetails details) {
     if (!_isActive || _moveController.isAnimating)
       return;
 
-    double oldDragExtent = _dragExtent;
+    final double delta = details.primaryDelta;
+    final double oldDragExtent = _dragExtent;
     switch (config.direction) {
       case DismissDirection.horizontal:
       case DismissDirection.vertical:
@@ -236,14 +237,14 @@ class _DismissableState extends State<Dismissable> {
     return false;
   }
 
-  void _handleDragEnd(Velocity velocity) {
+  void _handleDragEnd(DragEndDetails details) {
     if (!_isActive || _moveController.isAnimating)
       return;
     _dragUnderway = false;
     if (_moveController.isCompleted) {
       _startResizeAnimation();
-    } else if (_isFlingGesture(velocity)) {
-      double flingVelocity = _directionIsXAxis ? velocity.pixelsPerSecond.dx : velocity.pixelsPerSecond.dy;
+    } else if (_isFlingGesture(details.velocity)) {
+      double flingVelocity = _directionIsXAxis ? details.velocity.pixelsPerSecond.dx : details.velocity.pixelsPerSecond.dy;
       _dragExtent = flingVelocity.sign;
       _moveController.fling(velocity: flingVelocity.abs() * _kFlingVelocityScale);
     } else if (_moveController.value > _kDismissThreshold) {

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

@@ -9,6 +9,10 @@ import 'basic.dart';
 import 'framework.dart';
 
 export 'package:flutter/gestures.dart' show
+  DragDownDetails,
+  DragStartDetails,
+  DragUpdateDetails,
+  DragEndDetails,
   GestureTapDownCallback,
   GestureTapUpCallback,
   GestureTapCallback,
@@ -19,11 +23,6 @@ export 'package:flutter/gestures.dart' show
   GestureDragUpdateCallback,
   GestureDragEndCallback,
   GestureDragCancelCallback,
-  GesturePanDownCallback,
-  GesturePanStartCallback,
-  GesturePanUpdateCallback,
-  GesturePanEndCallback,
-  GesturePanCancelCallback,
   GestureScaleStartCallback,
   GestureScaleUpdateCallback,
   GestureScaleEndCallback,
@@ -162,21 +161,21 @@ class GestureDetector extends StatelessWidget {
   final GestureDragCancelCallback onHorizontalDragCancel;
 
   /// A pointer has contacted the screen and might begin to move.
-  final GesturePanDownCallback onPanDown;
+  final GestureDragDownCallback onPanDown;
 
   /// A pointer has contacted the screen and has begun to move.
-  final GesturePanStartCallback onPanStart;
+  final GestureDragStartCallback onPanStart;
 
   /// A pointer that is in contact with the screen and moving has moved again.
-  final GesturePanUpdateCallback onPanUpdate;
+  final GestureDragUpdateCallback onPanUpdate;
 
   /// A pointer that was previously in contact with the screen and moving
   /// is no longer in contact with the screen and was moving at a specific
   /// velocity when it stopped contacting the screen.
-  final GesturePanEndCallback onPanEnd;
+  final GestureDragEndCallback onPanEnd;
 
   /// The pointer that previously triggered [onPanDown] did not complete.
-  final GesturePanCancelCallback onPanCancel;
+  final GestureDragCancelCallback onPanCancel;
 
   /// The pointers in contact with the screen have established a focal point and
   /// initial scale of 1.0.
@@ -474,16 +473,16 @@ class _GestureSemantics extends SingleChildRenderObjectWidget {
       recognizer.onLongPress();
   }
 
-  void _handleHorizontalDragUpdate(double delta) {
+  void _handleHorizontalDragUpdate(DragUpdateDetails updateDetails) {
     {
       HorizontalDragGestureRecognizer recognizer = owner._recognizers[HorizontalDragGestureRecognizer];
       if (recognizer != null) {
         if (recognizer.onStart != null)
-          recognizer.onStart(Point.origin);
+          recognizer.onStart(new DragStartDetails());
         if (recognizer.onUpdate != null)
-          recognizer.onUpdate(delta);
+          recognizer.onUpdate(updateDetails);
         if (recognizer.onEnd != null)
-          recognizer.onEnd(Velocity.zero);
+          recognizer.onEnd(new DragEndDetails());
         return;
       }
     }
@@ -491,27 +490,27 @@ class _GestureSemantics extends SingleChildRenderObjectWidget {
       PanGestureRecognizer recognizer = owner._recognizers[PanGestureRecognizer];
       if (recognizer != null) {
         if (recognizer.onStart != null)
-          recognizer.onStart(Point.origin);
+          recognizer.onStart(new DragStartDetails());
         if (recognizer.onUpdate != null)
-          recognizer.onUpdate(new Offset(delta, 0.0));
+          recognizer.onUpdate(updateDetails);
         if (recognizer.onEnd != null)
-          recognizer.onEnd(Velocity.zero);
+          recognizer.onEnd(new DragEndDetails());
         return;
       }
     }
     assert(false);
   }
 
-  void _handleVerticalDragUpdate(double delta) {
+  void _handleVerticalDragUpdate(DragUpdateDetails updateDetails) {
     {
       VerticalDragGestureRecognizer recognizer = owner._recognizers[VerticalDragGestureRecognizer];
       if (recognizer != null) {
         if (recognizer.onStart != null)
-          recognizer.onStart(Point.origin);
+          recognizer.onStart(new DragStartDetails());
         if (recognizer.onUpdate != null)
-          recognizer.onUpdate(delta);
+          recognizer.onUpdate(updateDetails);
         if (recognizer.onEnd != null)
-          recognizer.onEnd(Velocity.zero);
+          recognizer.onEnd(new DragEndDetails());
         return;
       }
     }
@@ -519,11 +518,11 @@ class _GestureSemantics extends SingleChildRenderObjectWidget {
       PanGestureRecognizer recognizer = owner._recognizers[PanGestureRecognizer];
       if (recognizer != null) {
         if (recognizer.onStart != null)
-          recognizer.onStart(Point.origin);
+          recognizer.onStart(new DragStartDetails());
         if (recognizer.onUpdate != null)
-          recognizer.onUpdate(new Offset(0.0, delta));
+          recognizer.onUpdate(updateDetails);
         if (recognizer.onEnd != null)
-          recognizer.onEnd(Velocity.zero);
+          recognizer.onEnd(new DragEndDetails());
         return;
       }
     }

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

@@ -522,7 +522,7 @@ class ScrollableState<T extends Scrollable> extends State<T> {
     _simulation = null;
   }
 
-  void _handleDragStart(_) {
+  void _handleDragStart(DragStartDetails details) {
     _startScroll();
   }
 
@@ -542,12 +542,12 @@ class ScrollableState<T extends Scrollable> extends State<T> {
     new ScrollNotification(this, ScrollNotificationKind.started).dispatch(context);
   }
 
-  void _handleDragUpdate(double delta) {
-    scrollBy(pixelOffsetToScrollOffset(delta));
+  void _handleDragUpdate(DragUpdateDetails details) {
+    scrollBy(pixelOffsetToScrollOffset(details.primaryDelta));
   }
 
-  Future<Null> _handleDragEnd(Velocity velocity) {
-    double scrollVelocity = pixelDeltaToScrollOffset(velocity.pixelsPerSecond) / Duration.MILLISECONDS_PER_SECOND;
+  Future<Null> _handleDragEnd(DragEndDetails details) {
+    double scrollVelocity = pixelDeltaToScrollOffset(details.velocity.pixelsPerSecond) / Duration.MILLISECONDS_PER_SECOND;
     return fling(scrollVelocity).then(_endScroll);
   }
 

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

@@ -66,9 +66,9 @@ class _SemanticsDebuggerState extends State<SemanticsDebugger> {
       _lastPointerDownLocation = null;
     });
   }
-  void _handlePanEnd(Velocity velocity) {
+  void _handlePanEnd(DragEndDetails details) {
     assert(_lastPointerDownLocation != null);
-    _SemanticsDebuggerListener.instance.handlePanEnd(_lastPointerDownLocation, velocity);
+    _SemanticsDebuggerListener.instance.handlePanEnd(_lastPointerDownLocation, details.velocity);
     setState(() {
       _lastPointerDownLocation = null;
     });

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

@@ -205,12 +205,12 @@ class _TextSelectionHandleOverlay extends StatefulWidget {
 
 class _TextSelectionHandleOverlayState extends State<_TextSelectionHandleOverlay> {
   Point _dragPosition;
-  void _handleDragStart(Point position) {
-    _dragPosition = position;
+  void _handleDragStart(DragStartDetails details) {
+    _dragPosition = details.globalPosition;
   }
 
-  void _handleDragUpdate(double delta) {
-    _dragPosition += new Offset(delta, 0.0);
+  void _handleDragUpdate(DragUpdateDetails details) {
+    _dragPosition += details.delta;
     TextPosition position = config.renderObject.getPositionForPoint(_dragPosition);
 
     if (config.selection.isCollapsed) {

packages/flutter/test/gestures/long_press_test.dart

@@ -104,7 +104,7 @@ void main() {
     bool isDangerousStack = false;
 
     bool dragStartRecognized = false;
-    drag.onStart = (Point globalPosition) {
+    drag.onStart = (DragStartDetails details) {
       expect(isDangerousStack, isFalse);
       dragStartRecognized = true;
     };

packages/flutter/test/gestures/scroll_test.dart

@@ -20,12 +20,12 @@ void main() {
     };
 
     Offset updatedScrollDelta;
-    pan.onUpdate = (Offset offset) {
-      updatedScrollDelta = offset;
+    pan.onUpdate = (DragUpdateDetails details) {
+      updatedScrollDelta = details.delta;
     };
 
     bool didEndPan = false;
-    pan.onEnd = (Velocity velocity) {
+    pan.onEnd = (DragEndDetails details) {
       didEndPan = true;
     };
 
@@ -85,12 +85,12 @@ void main() {
     };
 
     double updatedDelta;
-    drag.onUpdate = (double delta) {
-      updatedDelta = delta;
+    drag.onUpdate = (DragUpdateDetails details) {
+      updatedDelta = details.primaryDelta;
     };
 
     bool didEndDrag = false;
-    drag.onEnd = (Velocity velocity) {
+    drag.onEnd = (DragEndDetails details) {
       didEndDrag = true;
     };
 

packages/flutter/test/widget/gesture_detector_test.dart

@@ -12,13 +12,13 @@ void main() {
     bool didEndDrag = false;
 
     Widget widget = new GestureDetector(
-      onVerticalDragStart: (_) {
+      onVerticalDragStart: (DragStartDetails details) {
         didStartDrag = true;
       },
-      onVerticalDragUpdate: (double scrollDelta) {
-        updatedDragDelta = scrollDelta;
+      onVerticalDragUpdate: (DragUpdateDetails details) {
+        updatedDragDelta = details.primaryDelta;
       },
-      onVerticalDragEnd: (Velocity velocity) {
+      onVerticalDragEnd: (DragEndDetails details) {
         didEndDrag = true;
       },
       child: new Container(
@@ -64,10 +64,10 @@ void main() {
     Point upLocation = new Point(10.0, 20.0);
 
     Widget widget = new GestureDetector(
-      onVerticalDragUpdate: (double delta) { dragDistance += delta; },
-      onVerticalDragEnd: (Velocity velocity) { gestureCount += 1; },
-      onHorizontalDragUpdate: (_) { fail("gesture should not match"); },
-      onHorizontalDragEnd: (Velocity velocity) { fail("gesture should not match"); },
+      onVerticalDragUpdate: (DragUpdateDetails details) { dragDistance += details.primaryDelta; },
+      onVerticalDragEnd: (DragEndDetails details) { gestureCount += 1; },
+      onHorizontalDragUpdate: (DragUpdateDetails details) { fail("gesture should not match"); },
+      onHorizontalDragEnd: (DragEndDetails details) { fail("gesture should not match"); },
       child: new Container(
         decoration: const BoxDecoration(
           backgroundColor: const Color(0xFF00FF00)
@@ -97,13 +97,13 @@ void main() {
 
     await tester.pumpWidget(
       new GestureDetector(
-        onPanStart: (_) {
+        onPanStart: (DragStartDetails details) {
           didStartPan = true;
         },
-        onPanUpdate: (Offset delta) {
-          panDelta = delta;
+        onPanUpdate: (DragUpdateDetails details) {
+          panDelta = details.delta;
         },
-        onPanEnd: (_) {
+        onPanEnd: (DragEndDetails details) {
           didEndPan = true;
         },
         child: new Container(