Implementing Gesture Responses

When a user action matches the predefined characteristics of a gesture, the system recognizes it as that gesture. This process is called gesture recognition. To respond to a gesture, you need to attach a gesture object to a component so the system can collect and process the gesture input.

Basic Gestures and Features

Gesture	Operation Feature	Triggering Example
TapGesture	Quick press and release (≤ 300 ms by default).	Tap with a finger or stylus on a touchscreen; left-click with a mouse; single tap on a touchpad.
LongPressGesture	Press and hold for a sustained duration.	Long press with a finger or stylus; hold down the left mouse button; long press on a touchpad.
PanGesture	Press and drag (displacement-based movement).	Drag with a finger or stylus; move the mouse while holding the left button; swipe with two fingers on a touchpad; scroll the mouse wheel over a scrollable component.
PinchGesture	Pinch inward or outward using two fingers.	Pinch gesture on touchscreen or touchpad; scroll the mouse wheel while holding Ctrl over a pinch-enabled component.
RotationGesture	Rotate two fingers around a central point.	Rotate gesture using two fingers on a touchscreen.
SwipeGesture	Speed-based directional swipe (triggered on release velocity). The key distinction between PanGesture and SwipeGesture lies in their recognition criteria: PanGesture is triggered based on movement distance while the pointer is still active; SwipeGesture is triggered based on release velocity after the pointer is lifted.	Quick swipe with one finger on a touchscreen; two-finger swipe on a touchpad; fast scroll with a mouse wheel.

Gesture Response Rules

Basic Rules

• Gesture recognition is based on the component hit at a specific location and time.
• If multiple components define the same gesture type, the gesture on the child component takes precedence over the parent.
• For gestures with different recognition conditions, the gesture that meets its condition first is triggered.
• If no parallel gestures are defined, once one gesture succeeds, others are excluded from recognition during that interaction.
• When a gesture of the same type succeeds on a child component, the same gesture type on the parent component is also considered successful.
• Built-in gestures (automatically bound by the framework) have higher priority than developer-defined gestures of the same type, unless you explicitly sets a higher priority using the priority binding mode.

The following scenarios illustrate these rules in practice:

Scenario 1:

Pan A and Pan B are defined with identical threshold conditions. Pan B is bound to a child component, while Pan A is bound to the parent. As a result, Pan B is triggered first due to child component precedence.

Scenario 2:

Pan A and Pan B are defined with different threshold conditions. Pan B is on a child component and has higher structural priority. However, Pan A has a lower threshold and may succeed first under normal movement speed. If the movement speed is high, both gestures may succeed due to spacing between report points. In this case, Pan B wins in contention because it processes the report point first.

Scenario 3:

The gesture that matches the actual user operation is triggered.

Example: If the user lifts their finger before the pan gesture threshold is met, a tap gesture is recognized instead.

Intervention in Gesture Processing

While the ArkUI gesture framework automatically handles gesture recognition based on predefined rules, applications often require dynamic control over gesture behavior. This allows you to intervene in the recognition process to achieve specific interaction outcomes, as long as the standard response rules are respected.

Gesture recognition is still initiated based on hit testing, and any method used to intervene in basic event processing can also be applied to gestures. In addition, ArkUI offers several advanced APIs for gesture-level intervention:

Method	Purpose	API	Description
Custom gesture judgment	Allows applications to conditionally approve or reject a gesture before the system finalizes recognition.	onGestureJudgeBegin	Invoked when a gesture is about to be recognized as successful. The application can override the system's decision by returning a rejection, allowing other gestures to compete for recognition.
Enhanced gesture judgment	Allows applications to conditionally approve or reject a gesture before the system finalizes recognition.	onGestureRecognizerJudgeBegin	1. Works similarly to onGestureJudgeBegin, but with higher priority. 2. If this API is bound, onGestureJudgeBegin becomes ineffective.
Parallel gesture control	Enables concurrent gesture recognition between parent and child components, which is useful for nested scrolling.	shouldBuiltInRecognizerParallelWith	1. Triggered when the user presses a component and the system begins collecting gesture objects. 2. Returns built-in gestures (currently only PanGesture) on the current component and previously collected gestures of the same type from child components. By default, child gestures have higher priority and override parent gestures. 3. Allows the application to forcibly specify that the low-priority gesture (for example, pan) on the current component runs in parallel with the high-priority gesture of the same type on the child component. That is, when the high-priority gesture on the child component is successfully recognized, the gesture of the same type on the current component can also be triggered and responded to successfully. 4. The returned gesture object provides an API to control the enabling of gesture responses. Therefore, after gestures are set to run in parallel, the application can control the response behavior of the two parallel gestures to achieve nested scrolling (e.g., one scrolls first, and the other triggers when the edge is reached). NOTE This method only takes effect when the bound component has built-in system gestures (e.g., List or Swiper). Otherwise, it has no effect.
Gesture recognition prevention	Prevents specific gestures from participating in recognition before they are processed.	preventBegin	1. Triggered during the onTouchTestDone callback when the user presses the screen. 2. Returns all gesture recognizers eligible for processing at the current position. 3. You can selectively call preventBegin on recognizers to exclude them from recognition, helping avoid gesture conflicts. This capability is supported since API version 20.

For details, see Gesture Conflict Handling.