Understanding Flutter Gesture System and Conflict Resolution

In everyday Flutter development, gestures and events are ubiquitous, from tapping a like button to long‑pressing a BottomSheet. This article explores how Flutter determines which widget responds to an event, how events are propagated, and how gestures such as Tap and DoubleTap are distinguished.

Event dispatch starts with Window.onPointerDataPacket , which converts raw data into PointerEvent objects that are queued and processed. The _handlePointerEvent method generates a HitTestResult , storing all hit test entries in a _path . The path is then traversed to dispatch the event to the appropriate render objects.

Hit testing walks the widget tree from the deepest leaf toward the root, collecting the nearest RenderBox that contains the pointer.

Gesture recognition is built on top of this system. The GestureDetector widget wraps various gesture recognizers and forwards pointer events to a RawGestureDetector , which calls addPointer on each recognizer. Using TapGestureRecognizer as an example, the recognizer registers handleEvent via startTrackingPointer . If the pointer movement stays within a 18‑pixel threshold, the tap is accepted; otherwise it is rejected.

When multiple gestures compete, Flutter uses a GestureArena . Only one recognizer can win; the winner receives subsequent events while the others fail. For instance, a horizontal drag will win over a vertical drag if the movement is primarily horizontal.

The article then presents a case study of an image viewer built with PageView . Features include image closing, left/right swipe, double‑tap zoom, and long‑press actions. Conflicts arise between the ScaleGestureRecognizer (for pinch‑zoom) and the HorizontalDragGestureRecognizer (used by PageView ) because both compete for horizontal motion.

Two solutions are discussed: disabling PageView scrolling during zoom (which feels jarring) and a more refined approach where the image wrapper forwards drag details to the PageController when the image reaches its boundary, allowing seamless transition to the next page. Additionally, by overriding rejectGesture in a custom ScaleGestureRecognizer , the scale gesture can be forced to win without breaking the arena flow.

Finally, the article outlines future improvements such as adding acceleration, damping at edges, and finer interaction details to enhance the user experience.