BaseTapAndDragGestureRecognizer class sealed

A base class for gesture recognizers that recognize taps and movements.

Takes on the responsibilities of TapGestureRecognizer and DragGestureRecognizer in one GestureRecognizer.

Gesture arena behavior

BaseTapAndDragGestureRecognizer competes on the pointer events of kPrimaryButton only when it has at least one non-null onTap* or onDrag* callback.

It will declare defeat if it determines that a gesture is not a tap (e.g. if the pointer is dragged too far while it's contacting the screen) or a drag (e.g. if the pointer was not dragged far enough to be considered a drag.

This recognizer will not immediately declare victory for every tap that it recognizes, but it declares victory for every drag.

The recognizer will declare victory when all other recognizer's in the arena have lost, if the timer of kPressTimeout elapses and a tap series greater than 1 is being tracked, or until the pointer has moved a sufficient global distance from the origin to be considered a drag.

If this recognizer loses the arena (either by declaring defeat or by another recognizer declaring victory) while the pointer is contacting the screen, it will fire onCancel instead of onTapUp or onDragEnd.

When competing with TapGestureRecognizer and DragGestureRecognizer

Similar to TapGestureRecognizer and DragGestureRecognizer, BaseTapAndDragGestureRecognizer will not aggressively declare victory when it detects a tap, so when it is competing with those gesture recognizers and others it has a chance of losing. Similarly, when eagerVictoryOnDrag is set to false, this recognizer will not aggressively declare victory when it detects a drag. By default, eagerVictoryOnDrag is set to true, so this recognizer will aggressively declare victory when it detects a drag.

When competing against TapGestureRecognizer, if the pointer does not move past the tap tolerance, then the recognizer that entered the arena first will win. In this case the gesture detected is a tap. If the pointer does travel past the tap tolerance then this recognizer will be declared winner by default. The gesture detected in this case is a drag.

When competing against DragGestureRecognizer, if the pointer does not move a sufficient global distance to be considered a drag, the recognizers will tie in the arena. If the pointer does travel enough distance then the recognizer that entered the arena first will win. The gesture detected in this case is a drag.

This example shows how to use the TapAndPanGestureRecognizer along with a RawGestureDetector to scale a Widget.
link

To create a local project with this code sample, run:
flutter create --sample=gestures.BaseTapAndDragGestureRecognizer.1 mysample

This example shows how to hook up TapAndPanGestureRecognizers' to nested RawGestureDetectors'. It assumes that the code is being used inside a State object with a _last field that is then displayed as the child of the gesture detector.

In this example, if the pointer has moved past the drag threshold, then the the first TapAndPanGestureRecognizer instance to receive the PointerEvent will win the arena because the recognizer will immediately declare victory.

The first one to receive the event in the example will depend on where on both containers the pointer lands first. If your pointer begins in the overlapping area of both containers, then the inner-most widget will receive the event first. If your pointer begins in the yellow container then it will be the first to receive the event.

If the pointer has not moved past the drag threshold, then the first recognizer to enter the arena will win (i.e. they both tie and the gesture arena will call GestureArenaManager.sweep so the first member of the arena will win).

link
RawGestureDetector(
  gestures: <Type, GestureRecognizerFactory>{
    TapAndPanGestureRecognizer: GestureRecognizerFactoryWithHandlers<TapAndPanGestureRecognizer>(
      () => TapAndPanGestureRecognizer(),
      (TapAndPanGestureRecognizer instance) {
        instance
          ..onTapDown = (TapDragDownDetails details) { setState(() { _last = 'down_a'; }); }
          ..onDragStart = (TapDragStartDetails details) { setState(() { _last = 'drag_start_a'; }); }
          ..onDragUpdate = (TapDragUpdateDetails details) { setState(() { _last = 'drag_update_a'; }); }
          ..onDragEnd = (TapDragEndDetails details) { setState(() { _last = 'drag_end_a'; }); }
          ..onTapUp = (TapDragUpDetails details) { setState(() { _last = 'up_a'; }); }
          ..onCancel = () { setState(() { _last = 'cancel_a'; }); };
      },
    ),
  },
  child: Container(
    width: 300.0,
    height: 300.0,
    color: Colors.yellow,
    alignment: Alignment.center,
    child: RawGestureDetector(
      gestures: <Type, GestureRecognizerFactory>{
        TapAndPanGestureRecognizer: GestureRecognizerFactoryWithHandlers<TapAndPanGestureRecognizer>(
          () => TapAndPanGestureRecognizer(),
          (TapAndPanGestureRecognizer instance) {
            instance
              ..onTapDown = (TapDragDownDetails details) { setState(() { _last = 'down_b'; }); }
              ..onDragStart = (TapDragStartDetails details) { setState(() { _last = 'drag_start_b'; }); }
              ..onDragUpdate = (TapDragUpdateDetails details) { setState(() { _last = 'drag_update_b'; }); }
              ..onDragEnd = (TapDragEndDetails details) { setState(() { _last = 'drag_end_b'; }); }
              ..onTapUp = (TapDragUpDetails details) { setState(() { _last = 'up_b'; }); }
              ..onCancel = () { setState(() { _last = 'cancel_b'; }); };
          },
        ),
      },
      child: Container(
        width: 150.0,
        height: 150.0,
        color: Colors.blue,
        child: Text(_last),
      ),
    ),
  ),
)

Inheritance
Implementers

Properties

allowedButtonsFilter AllowedButtonsFilter
Called when interaction starts. This limits the dragging behavior for custom clicks (such as scroll click). Its parameter comes from PointerEvent.buttons.
finalinherited
consecutiveTapCount int
no setterinherited
currentDown PointerDownEvent?
no setterinherited
currentUp PointerUpEvent?
no setterinherited
debugDescription String
Returns a very short pretty description of the gesture that the recognizer looks for, like 'tap' or 'horizontal drag'.
no setteroverride
debugOwner Object?
The recognizer's owner.
finalinherited
dragStartBehavior DragStartBehavior
Configure the behavior of offsets passed to onDragStart.
getter/setter pair
dragUpdateThrottleFrequency Duration?
The frequency at which the onDragUpdate callback is called.
getter/setter pair
eagerVictoryOnDrag bool
Whether this recognizer eagerly declares victory when it has detected a drag.
getter/setter pair
gestureSettings DeviceGestureSettings?
Optional device specific configuration for device gestures that will take precedence over framework defaults.
getter/setter pairinherited
hashCode int
The hash code for this object.
no setterinherited
maxConsecutiveTap int?
An upper bound for the amount of taps that can belong to one tap series.
getter/setter pair
onCancel GestureCancelCallback?
The pointer that previously triggered onTapDown did not complete.
getter/setter pair
onDragEnd GestureTapDragEndCallback?
A pointer that was previously in contact with the screen with a primary button and moving is no longer in contact with the screen and was moving at a specific velocity when it stopped contacting the screen.
getter/setter pair
onDragStart GestureTapDragStartCallback?
A pointer has contacted the screen with a primary button and has begun to move.
getter/setter pair
onDragUpdate GestureTapDragUpdateCallback?
A pointer that is in contact with the screen with a primary button and moving has moved again.
getter/setter pair
onTapDown GestureTapDragDownCallback?
A pointer has contacted the screen at a particular location with a primary button, which might be the start of a tap.
getter/setter pair
onTapTrackReset VoidCallback?
Callback used to indicate that a tap tracking has been reset which happens on the next PointerDownEvent after the timer between two taps elapses, the recognizer loses the arena, the gesture is cancelled or the recognizer is disposed of.
getter/setter pairinherited
onTapTrackStart VoidCallback?
Callback used to indicate that a tap tracking has started upon a PointerDownEvent.
getter/setter pairinherited
onTapUp GestureTapDragUpCallback?
A pointer has stopped contacting the screen at a particular location, which is recognized as a tap of a primary button.
getter/setter pair
runtimeType Type
A representation of the runtime type of the object.
no setterinherited
supportedDevices Set<PointerDeviceKind>?
The kind of devices that are allowed to be recognized as provided by supportedDevices in the constructor, or the currently deprecated kind. These cannot both be set. If both are null, events from all device kinds will be tracked and recognized.
getter/setter pairinherited
team GestureArenaTeam?
The team that this recognizer belongs to, if any.
getter/setter pairinherited

Methods

acceptGesture(int pointer) → void
Called when this member wins the arena for the given pointer id.
override
addAllowedPointer(PointerDownEvent event) → void
Registers a new pointer that's been checked to be allowed by this gesture recognizer.
override
addAllowedPointerPanZoom(PointerPanZoomStartEvent event) → void
Registers a new pointer pan/zoom that's been checked to be allowed by this gesture recognizer.
inherited
addPointer(PointerDownEvent event) → void
Registers a new pointer that might be relevant to this gesture detector.
inherited
addPointerPanZoom(PointerPanZoomStartEvent event) → void
Registers a new pointer pan/zoom that might be relevant to this gesture detector.
inherited
debugDescribeChildren() List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
didStopTrackingLastPointer(int pointer) → void
Called when the number of pointers this recognizer is tracking changes from one to zero.
override
dispose() → void
Releases any resources used by the object.
override
getKindForPointer(int pointer) PointerDeviceKind
For a given pointer ID, returns the device kind associated with it.
inherited
handleEvent(PointerEvent event) → void
Called when a pointer event is routed to this recognizer.
override
handleNonAllowedPointer(PointerDownEvent event) → void
Handles a pointer being added that's not allowed by this recognizer.
override
handleNonAllowedPointerPanZoom(PointerPanZoomStartEvent event) → void
Handles a pointer pan/zoom being added that's not allowed by this recognizer.
inherited
invokeCallback<T>(String name, RecognizerCallback<T> callback, {String debugReport()?}) → T?
Invoke a callback provided by the application, catching and logging any exceptions.
inherited
isPointerAllowed(PointerEvent event) bool
Checks whether or not a pointer is allowed to be tracked by this recognizer.
override
isPointerPanZoomAllowed(PointerPanZoomStartEvent event) bool
Checks whether or not a pointer pan/zoom is allowed to be tracked by this recognizer.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
rejectGesture(int pointer) → void
Called when this member loses the arena for the given pointer id.
override
resolve(GestureDisposition disposition) → void
Resolves this recognizer's participation in each gesture arena with the given disposition.
inherited
resolvePointer(int pointer, GestureDisposition disposition) → void
Resolves this recognizer's participation in the given gesture arena with the given disposition.
inherited
startTrackingPointer(int pointer, [Matrix4? transform]) → void
Causes events related to the given pointer ID to be routed to this recognizer.
inherited
stopTrackingIfPointerNoLongerDown(PointerEvent event) → void
Stops tracking the pointer associated with the given event if the event is a PointerUpEvent or a PointerCancelEvent event.
inherited
stopTrackingPointer(int pointer) → void
Stops events related to the given pointer ID from being routed to this recognizer.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug}) String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) String
Returns a one-line detailed description of the object.
inherited
toStringShort() String
A brief description of this object, usually just the runtimeType and the hashCode.
inherited

Operators

operator ==(Object other) bool
The equality operator.
inherited