Unverified Commit ea09f4ec authored by xubaolin's avatar xubaolin Committed by GitHub

update the DragStartBehavior documetations (#82327)

parent 9108c062
...@@ -110,9 +110,9 @@ class CupertinoSwitch extends StatefulWidget { ...@@ -110,9 +110,9 @@ class CupertinoSwitch extends StatefulWidget {
/// Determines the way that drag start behavior is handled. /// Determines the way that drag start behavior is handled.
/// ///
/// If set to [DragStartBehavior.start], the drag behavior used to move the /// If set to [DragStartBehavior.start], the drag behavior used to move the
/// switch from on to off will begin upon the detection of a drag gesture. If /// switch from on to off will begin at the position where the drag gesture won
/// set to [DragStartBehavior.down] it will begin when a down event is first /// the arena. If set to [DragStartBehavior.down] it will begin at the position
/// detected. /// where a down event was first detected.
/// ///
/// In general, setting this to [DragStartBehavior.start] will make drag /// In general, setting this to [DragStartBehavior.start] will make drag
/// animation smoother and setting it to [DragStartBehavior.down] will make /// animation smoother and setting it to [DragStartBehavior.down] will make
......
...@@ -82,12 +82,15 @@ abstract class DragGestureRecognizer extends OneSequenceGestureRecognizer { ...@@ -82,12 +82,15 @@ abstract class DragGestureRecognizer extends OneSequenceGestureRecognizer {
); );
static VelocityTracker _defaultBuilder(PointerEvent event) => VelocityTracker.withKind(event.kind); static VelocityTracker _defaultBuilder(PointerEvent event) => VelocityTracker.withKind(event.kind);
/// Configure the behavior of offsets sent to [onStart].
/// Configure the behavior of offsets passed to [onStart].
/// ///
/// If set to [DragStartBehavior.start], the [onStart] callback will be called /// If set to [DragStartBehavior.start], the [onStart] callback will be called
/// at the time and position when this gesture recognizer wins the arena. If /// with the position of the pointer at the time this gesture recognizer won
/// [DragStartBehavior.down], [onStart] will be called at the time and /// the arena. If [DragStartBehavior.down], [onStart] will be called with
/// position when a down event was first detected. /// the position of the first detected down event for the pointer. When there
/// are no other gestures competing with this gesture in the arena, there's
/// no difference in behavior between the two settings.
/// ///
/// For more information about the gesture arena: /// For more information about the gesture arena:
/// https://flutter.dev/docs/development/ui/advanced/gestures#gesture-disambiguation /// https://flutter.dev/docs/development/ui/advanced/gestures#gesture-disambiguation
...@@ -96,13 +99,14 @@ abstract class DragGestureRecognizer extends OneSequenceGestureRecognizer { ...@@ -96,13 +99,14 @@ abstract class DragGestureRecognizer extends OneSequenceGestureRecognizer {
/// ///
/// ## Example: /// ## Example:
/// ///
/// A finger presses down on the screen with offset (500.0, 500.0), and then /// A [HorizontalDragGestureRecognizer] and a [VerticalDragGestureRecognizer]
/// moves to position (510.0, 500.0) before winning the arena. With /// compete with each other. A finger presses down on the screen with
/// offset (500.0, 500.0), and then moves to position (510.0, 500.0) before
/// the [HorizontalDragGestureRecognizer] wins the arena. With
/// [dragStartBehavior] set to [DragStartBehavior.down], the [onStart] /// [dragStartBehavior] set to [DragStartBehavior.down], the [onStart]
/// callback will be called at the time corresponding to the touch's position /// callback will be called with position (500.0, 500.0). If it is
/// at (500.0, 500.0). If it is instead set to [DragStartBehavior.start], /// instead set to [DragStartBehavior.start], [onStart] will be called with
/// [onStart] will be called at the time corresponding to the touch's position /// position (510.0, 500.0).
/// at (510.0, 500.0).
DragStartBehavior dragStartBehavior; DragStartBehavior dragStartBehavior;
/// A pointer has contacted the screen with a primary button and might begin /// A pointer has contacted the screen with a primary button and might begin
...@@ -121,12 +125,8 @@ abstract class DragGestureRecognizer extends OneSequenceGestureRecognizer { ...@@ -121,12 +125,8 @@ abstract class DragGestureRecognizer extends OneSequenceGestureRecognizer {
/// move. /// move.
/// ///
/// The position of the pointer is provided in the callback's `details` /// The position of the pointer is provided in the callback's `details`
/// argument, which is a [DragStartDetails] object. /// argument, which is a [DragStartDetails] object. The [dragStartBehavior]
/// /// determines this position.
/// Depending on the value of [dragStartBehavior], this function will be
/// called on the initial touch down, if set to [DragStartBehavior.down] or
/// when the drag gesture is first detected, if set to
/// [DragStartBehavior.start].
/// ///
/// See also: /// See also:
/// ///
......
...@@ -27,19 +27,17 @@ typedef RecognizerCallback<T> = T Function(); ...@@ -27,19 +27,17 @@ typedef RecognizerCallback<T> = T Function();
/// Configuration of offset passed to [DragStartDetails]. /// Configuration of offset passed to [DragStartDetails].
/// ///
/// The settings determines when a drag formally starts when the user
/// initiates a drag.
///
/// See also: /// See also:
/// ///
/// * [DragGestureRecognizer.dragStartBehavior], which gives an example for the different behaviors. /// * [DragGestureRecognizer.dragStartBehavior], which gives an example for the
/// different behaviors.
enum DragStartBehavior { enum DragStartBehavior {
/// Set the initial offset, at the position where the first down event was /// Set the initial offset at the position where the first down event was
/// detected. /// detected.
down, down,
/// Set the initial position at the position where the drag start event was /// Set the initial position at the position where this gesture recognizer
/// detected. /// won the arena.
start, start,
} }
......
...@@ -2273,9 +2273,9 @@ class _MonthItem extends StatefulWidget { ...@@ -2273,9 +2273,9 @@ class _MonthItem extends StatefulWidget {
/// Determines the way that drag start behavior is handled. /// Determines the way that drag start behavior is handled.
/// ///
/// If set to [DragStartBehavior.start], the drag gesture used to scroll a /// If set to [DragStartBehavior.start], the drag gesture used to scroll a
/// date picker wheel will begin upon the detection of a drag gesture. If set /// date picker wheel will begin at the position where the drag gesture won
/// to [DragStartBehavior.down] it will begin when a down event is first /// the arena. If set to [DragStartBehavior.down] it will begin at the position
/// detected. /// where a down event is first detected.
/// ///
/// In general, setting this to [DragStartBehavior.start] will make drag /// In general, setting this to [DragStartBehavior.start] will make drag
/// animation smoother and setting it to [DragStartBehavior.down] will make /// animation smoother and setting it to [DragStartBehavior.down] will make
......
...@@ -124,9 +124,9 @@ class DayPicker extends StatelessWidget { ...@@ -124,9 +124,9 @@ class DayPicker extends StatelessWidget {
/// Determines the way that drag start behavior is handled. /// Determines the way that drag start behavior is handled.
/// ///
/// If set to [DragStartBehavior.start], the drag gesture used to scroll a /// If set to [DragStartBehavior.start], the drag gesture used to scroll a
/// date picker wheel will begin upon the detection of a drag gesture. If set /// date picker wheel will begin at the position where the drag gesture won
/// to [DragStartBehavior.down] it will begin when a down event is first /// the arena. If set to [DragStartBehavior.down] it will begin at the
/// detected. /// position where a down event is first detected.
/// ///
/// In general, setting this to [DragStartBehavior.start] will make drag /// In general, setting this to [DragStartBehavior.start] will make drag
/// animation smoother and setting it to [DragStartBehavior.down] will make /// animation smoother and setting it to [DragStartBehavior.down] will make
......
...@@ -259,9 +259,9 @@ class DrawerController extends StatefulWidget { ...@@ -259,9 +259,9 @@ class DrawerController extends StatefulWidget {
/// Determines the way that drag start behavior is handled. /// Determines the way that drag start behavior is handled.
/// ///
/// If set to [DragStartBehavior.start], the drag behavior used for opening /// If set to [DragStartBehavior.start], the drag behavior used for opening
/// and closing a drawer will begin upon the detection of a drag gesture. If /// and closing a drawer will begin at the position where the drag gesture won
/// set to [DragStartBehavior.down] it will begin when a down event is first /// the arena. If set to [DragStartBehavior.down] it will begin at the position
/// detected. /// where a down event is first detected.
/// ///
/// In general, setting this to [DragStartBehavior.start] will make drag /// In general, setting this to [DragStartBehavior.start] will make drag
/// animation smoother and setting it to [DragStartBehavior.down] will make /// animation smoother and setting it to [DragStartBehavior.down] will make
......
...@@ -212,8 +212,9 @@ class Dismissible extends StatefulWidget { ...@@ -212,8 +212,9 @@ class Dismissible extends StatefulWidget {
/// Determines the way that drag start behavior is handled. /// Determines the way that drag start behavior is handled.
/// ///
/// If set to [DragStartBehavior.start], the drag gesture used to dismiss a /// If set to [DragStartBehavior.start], the drag gesture used to dismiss a
/// dismissible will begin upon the detection of a drag gesture. If set to /// dismissible will begin at the position where the drag gesture won the arena.
/// [DragStartBehavior.down] it will begin when a down event is first detected. /// If set to [DragStartBehavior.down] it will begin at the position where
/// a down event is first detected.
/// ///
/// In general, setting this to [DragStartBehavior.start] will make drag /// In general, setting this to [DragStartBehavior.start] will make drag
/// animation smoother and setting it to [DragStartBehavior.down] will make /// animation smoother and setting it to [DragStartBehavior.down] will make
......
...@@ -975,8 +975,9 @@ class GestureDetector extends StatelessWidget { ...@@ -975,8 +975,9 @@ class GestureDetector extends StatelessWidget {
/// Determines the way that drag start behavior is handled. /// Determines the way that drag start behavior is handled.
/// ///
/// If set to [DragStartBehavior.start], gesture drag behavior will /// If set to [DragStartBehavior.start], gesture drag behavior will
/// begin upon the detection of a drag gesture. If set to /// begin at the position where the drag gesture won the arena. If set to
/// [DragStartBehavior.down] it will begin when a down event is first detected. /// [DragStartBehavior.down] it will begin at the position where a down event
/// is first detected.
/// ///
/// In general, setting this to [DragStartBehavior.start] will make drag /// In general, setting this to [DragStartBehavior.start] will make drag
/// animation smoother and setting it to [DragStartBehavior.down] will make /// animation smoother and setting it to [DragStartBehavior.down] will make
......
...@@ -214,8 +214,9 @@ class Scrollable extends StatefulWidget { ...@@ -214,8 +214,9 @@ class Scrollable extends StatefulWidget {
/// Determines the way that drag start behavior is handled. /// Determines the way that drag start behavior is handled.
/// ///
/// If set to [DragStartBehavior.start], scrolling drag behavior will /// If set to [DragStartBehavior.start], scrolling drag behavior will
/// begin upon the detection of a drag gesture. If set to /// begin at the position where the drag gesture won the arena. If set to
/// [DragStartBehavior.down] it will begin when a down event is first detected. /// [DragStartBehavior.down] it will begin at the position where a down
/// event is first detected.
/// ///
/// In general, setting this to [DragStartBehavior.start] will make drag /// In general, setting this to [DragStartBehavior.start] will make drag
/// animation smoother and setting it to [DragStartBehavior.down] will make /// animation smoother and setting it to [DragStartBehavior.down] will make
......
...@@ -385,8 +385,9 @@ class TextSelectionOverlay { ...@@ -385,8 +385,9 @@ class TextSelectionOverlay {
/// Determines the way that drag start behavior is handled. /// Determines the way that drag start behavior is handled.
/// ///
/// If set to [DragStartBehavior.start], handle drag behavior will /// If set to [DragStartBehavior.start], handle drag behavior will
/// begin upon the detection of a drag gesture. If set to /// begin at the position where the drag gesture won the arena. If set to
/// [DragStartBehavior.down] it will begin when a down event is first detected. /// [DragStartBehavior.down] it will begin at the position where a down
/// event is first detected.
/// ///
/// In general, setting this to [DragStartBehavior.start] will make drag /// In general, setting this to [DragStartBehavior.start] will make drag
/// animation smoother and setting it to [DragStartBehavior.down] will make /// animation smoother and setting it to [DragStartBehavior.down] will make
......
...@@ -281,6 +281,125 @@ void main() { ...@@ -281,6 +281,125 @@ void main() {
expect(didEndDrag, isFalse); expect(didEndDrag, isFalse);
}); });
testGesture('DragGestureRecognizer.onStart behavior test', (GestureTester tester) {
final HorizontalDragGestureRecognizer drag = HorizontalDragGestureRecognizer()
..dragStartBehavior = DragStartBehavior.down;
addTearDown(drag.dispose);
Duration? startTimestamp;
Offset? positionAtOnStart;
drag.onStart = (DragStartDetails details) {
startTimestamp = details.sourceTimeStamp;
positionAtOnStart = details.globalPosition;
};
Duration? updatedTimestamp;
Offset? updateDelta;
drag.onUpdate = (DragUpdateDetails details) {
updatedTimestamp = details.sourceTimeStamp;
updateDelta = details.delta;
};
// No competing, dragStartBehavior == DragStartBehavior.down
final TestPointer pointer = TestPointer(5);
PointerDownEvent down = pointer.down(const Offset(10.0, 10.0), timeStamp: const Duration(milliseconds: 100));
drag.addPointer(down);
tester.closeArena(5);
expect(startTimestamp, isNull);
expect(positionAtOnStart, isNull);
expect(updatedTimestamp, isNull);
tester.route(down);
// The only horizontal drag gesture win the arena when the pointer down.
expect(startTimestamp, const Duration(milliseconds: 100));
expect(positionAtOnStart, const Offset(10.0, 10.0));
expect(updatedTimestamp, isNull);
tester.route(pointer.move(const Offset(20.0, 25.0), timeStamp: const Duration(milliseconds: 200)));
expect(updatedTimestamp, const Duration(milliseconds: 200));
expect(updateDelta, const Offset(10.0, 0.0));
tester.route(pointer.move(const Offset(20.0, 25.0), timeStamp: const Duration(milliseconds: 300)));
expect(updatedTimestamp, const Duration(milliseconds: 300));
expect(updateDelta, Offset.zero);
tester.route(pointer.up());
// No competing, dragStartBehavior == DragStartBehavior.start
// When there are no other gestures competing with this gesture in the arena,
// there's no difference in behavior between the two settings.
drag.dragStartBehavior = DragStartBehavior.start;
startTimestamp = null;
positionAtOnStart = null;
updatedTimestamp = null;
updateDelta = null;
down = pointer.down(const Offset(10.0, 10.0), timeStamp: const Duration(milliseconds: 400));
drag.addPointer(down);
tester.closeArena(5);
tester.route(down);
expect(startTimestamp, const Duration(milliseconds: 400));
expect(positionAtOnStart, const Offset(10.0, 10.0));
expect(updatedTimestamp, isNull);
tester.route(pointer.move(const Offset(20.0, 25.0), timeStamp: const Duration(milliseconds: 500)));
expect(updatedTimestamp, const Duration(milliseconds: 500));
tester.route(pointer.up());
// With competing, dragStartBehavior == DragStartBehavior.start
startTimestamp = null;
positionAtOnStart = null;
updatedTimestamp = null;
updateDelta = null;
final VerticalDragGestureRecognizer competingDrag = VerticalDragGestureRecognizer()
..onStart = (_) {};
addTearDown(() => competingDrag.dispose);
down = pointer.down(const Offset(10.0, 10.0), timeStamp: const Duration(milliseconds: 600));
drag.addPointer(down);
competingDrag.addPointer(down);
tester.closeArena(5);
tester.route(down);
// The pointer down event do not trigger anything.
expect(startTimestamp, isNull);
expect(positionAtOnStart, isNull);
expect(updatedTimestamp, isNull);
tester.route(pointer.move(const Offset(30.0, 10.0), timeStamp: const Duration(milliseconds: 700)));
expect(startTimestamp, const Duration(milliseconds: 700));
// Using the position of the pointer at the time this gesture recognizer won the arena.
expect(positionAtOnStart, const Offset(30.0, 10.0));
expect(updatedTimestamp, isNull); // Do not trigger an update event.
tester.route(pointer.up());
// With competing, dragStartBehavior == DragStartBehavior.down
drag.dragStartBehavior = DragStartBehavior.down;
startTimestamp = null;
positionAtOnStart = null;
updatedTimestamp = null;
updateDelta = null;
down = pointer.down(const Offset(10.0, 10.0), timeStamp: const Duration(milliseconds: 800));
drag.addPointer(down);
competingDrag.addPointer(down);
tester.closeArena(5);
tester.route(down);
expect(startTimestamp, isNull);
expect(positionAtOnStart, isNull);
expect(updatedTimestamp, isNull);
tester.route(pointer.move(const Offset(30.0, 10.0), timeStamp: const Duration(milliseconds: 900)));
expect(startTimestamp, const Duration(milliseconds: 900));
// Using the position of the first detected down event for the pointer.
expect(positionAtOnStart, const Offset(10.0, 10.0));
expect(updatedTimestamp, const Duration(milliseconds: 900)); // Also, trigger an update event.
expect(updateDelta, const Offset(20.0, 0.0));
tester.route(pointer.up());
});
testGesture('Should report original timestamps', (GestureTester tester) { testGesture('Should report original timestamps', (GestureTester tester) {
final HorizontalDragGestureRecognizer drag = HorizontalDragGestureRecognizer() ..dragStartBehavior = DragStartBehavior.down; final HorizontalDragGestureRecognizer drag = HorizontalDragGestureRecognizer() ..dragStartBehavior = DragStartBehavior.down;
addTearDown(drag.dispose); addTearDown(drag.dispose);
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment