SerialTapGestureRecognizer class
Recognizes serial taps (taps in a series).
A collection of taps are considered to be in a series if they occur in rapid succession in the same location (within a tolerance). The number of taps in the series is its count. A double-tap, for instance, is a special case of a tap series with a count of two.
Gesture arena behavior
SerialTapGestureRecognizer competes on all pointer events (regardless of button). 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). It will immediately declare victory for every tap that it recognizes.
Each time a pointer contacts the screen, this recognizer will enter that gesture into the arena. This means that this recognizer will yield multiple winning entries in the arena for a single tap series as the series progresses.
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 onSerialTapCancel, and onSerialTapUp will not be fired.
Button behavior
A tap series is defined to have the same buttons across all taps. If a tap with a different combination of buttons is delivered in the middle of a series, it will "steal" the series and begin a new series, starting the count over.
Interleaving tap behavior
A tap must be completed in order for a subsequent tap to be considered "in the same series" as that tap. Thus, if tap A is in-progress (the down event has been received, but the corresponding up event has not yet been received), and tap B begins (another pointer contacts the screen), tap A will fire onSerialTapCancel, and tap B will begin a new series (tap B's SerialTapDownDetails.count will be 1).
Relation to TapGestureRecognizer
and DoubleTapGestureRecognizer
SerialTapGestureRecognizer fires onSerialTapDown and onSerialTapUp
for every tap that it recognizes (passing the count in the details),
regardless of whether that tap is a single-tap, double-tap, etc. This
makes it especially useful when you want to respond to every tap in a
series. Contrast this with DoubleTapGestureRecognizer, which only fires
if the user completes a double-tap, and TapGestureRecognizer, which
doesn't fire if the recognizer is competing with a
DoubleTapGestureRecognizer
, and the user double-taps.
For example, consider a list item that should be selected on the first tap and cause an edit dialog to open on a double-tap. If you use both TapGestureRecognizer and DoubleTapGestureRecognizer, there are a few problems:
- If the user single-taps the list item, it will not select the list item until after enough time has passed to rule out a double-tap.
- If the user double-taps the list item, it will not select the list item at all.
The solution is to use SerialTapGestureRecognizer and use the tap count to either select the list item or open the edit dialog.
When competing with TapGestureRecognizer
and DoubleTapGestureRecognizer
Unlike TapGestureRecognizer and DoubleTapGestureRecognizer, SerialTapGestureRecognizer aggressively declares victory when it detects a tap, so when it is competing with those gesture recognizers, it will beat them in the arena, regardless of which recognizer entered the arena first.
- Inheritance
-
- Object
- GestureArenaMember
- GestureRecognizer
- SerialTapGestureRecognizer
Constructors
-
SerialTapGestureRecognizer({Object? debugOwner, Set<
PointerDeviceKind> ? supportedDevices, AllowedButtonsFilter allowedButtonsFilter = _defaultButtonAcceptBehavior}) - Creates a serial tap gesture recognizer.
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
- 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
- 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
- isTrackingPointer → bool
-
Indicates whether this recognizer is currently tracking a pointer that's
in contact with the screen.
no setter
- onSerialTapCancel ↔ GestureSerialTapCancelCallback?
-
A pointer that previously triggered onSerialTapDown will not end up
triggering the corresponding onSerialTapUp.
getter/setter pair
- onSerialTapDown ↔ GestureSerialTapDownCallback?
-
A pointer has contacted the screen at a particular location, which might
be the start of a serial tap.
getter/setter pair
- onSerialTapUp ↔ GestureSerialTapUpCallback?
-
A pointer has stopped contacting the screen at a particular location,
representing a serial tap.
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 deprecatedkind
. These cannot both be set. If both are null, events from all device kinds will be tracked and recognized.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
-
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
-
handleNonAllowedPointer(
PointerDownEvent event) → void -
Handles a pointer being added that's not allowed by this recognizer.
inherited
-
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(
PointerDownEvent 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
-
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