SerialTapGestureRecognizer class Null safety

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:

1. 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.
2. 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.