1# Gesture Binding 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @jiangtao92--> 5<!--Designer: @piggyguy--> 6<!--Tester: @songyanhong--> 7<!--Adviser: @HelloCrease--> 8 9Bind different types of gesture events to components and set response methods for them. 10 11> **NOTE** 12> 13> The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 14 15 16## Binding Gesture Recognition 17 18Use the following APIs to bind gesture recognition to a component. When a gesture is recognized, the event callback is invoked to notify the component. 19A region in which a gesture can be recognized may be specified by the [touch target](ts-universal-attributes-touch-target.md). 20 21**Atomic service API**: This API can be used in atomic services since API version 11. 22 23> **NOTE** 24> 25> The **gesture**, **priorityGesture**, and **parallelGesture** APIs currently do not support switching gesture bindings using the ternary operator (condition ? expression1 : expression2). 26 27### gesture 28 29gesture(gesture: GestureType, mask?: GestureMask): T 30 31Sets the gesture to bind. 32 33**Atomic service API**: This API can be used in atomic services since API version 11. 34 35**System capability**: SystemCapability.ArkUI.ArkUI.Full 36 37**Parameters** 38 39| Name| Type | Mandatory| Description | 40| ------ | ------------------------------------------ | ---- | ---------------------------- | 41| gesture | [GestureType](#gesturetype) | Yes | Type of the gesture to bind.| 42| mask | [GestureMask](#gesturemask) | No | Mask for gesture events.<br>Default value: **GestureMask.Normal**.| 43 44**Return value** 45 46| Type | Description | 47| ------ | --------- | 48| T | Current component.| 49 50### priorityGesture 51 52priorityGesture(gesture: GestureType, mask?: GestureMask): T 53 54Sets the gesture to preferentially recognize. By default, the child component preferentially recognizes the gesture specified by **gesture**, and the parent component preferentially recognizes the gesture specified by **priorityGesture** (if set). 2. With regard to long press gestures, the component with the shortest minimum hold-down time responds first, ignoring the **priorityGesture** settings. 55 56**Atomic service API**: This API can be used in atomic services since API version 11. 57 58**System capability**: SystemCapability.ArkUI.ArkUI.Full 59 60**Parameters** 61 62| Name| Type | Mandatory| Description | 63| ------ | ------------------------------------------ | ---- | ---------------------------- | 64| gesture | [GestureType](#gesturetype) | Yes | Type of the gesture to bind.| 65| mask | [GestureMask](#gesturemask) | No | Mask for gesture events.<br>Default value: **GestureMask.Normal**.| 66 67**Return value** 68 69| Type | Description | 70| ------ | --------- | 71| T | Current component.| 72 73### parallelGesture 74 75parallelGesture(gesture: GestureType, mask?: GestureMask): T 76 77Sets the gesture that can be recognized at once by the component and its child component. The gesture event is not a bubbling event. When **parallelGesture** is set for a component, both it and its child component can respond to the same gesture events, thereby implementing a quasi-bubbling effect. 78 79**Atomic service API**: This API can be used in atomic services since API version 11. 80 81**System capability**: SystemCapability.ArkUI.ArkUI.Full 82 83**Parameters** 84 85| Name| Type | Mandatory| Description | 86| ------ | ------------------------------------------ | ---- | ---------------------------- | 87| gesture | [GestureType](#gesturetype) | Yes | Type of the gesture to bind.| 88| mask | [GestureMask](#gesturemask) | No | Mask for gesture events.<br>Default value: **GestureMask.Normal**.| 89 90**Return value** 91 92| Type | Description | 93| ------ | --------- | 94| T | Current component.| 95 96 97## GestureType 98 99declare type GestureType = TapGesture | LongPressGesture | PanGesture | PinchGesture | SwipeGesture | RotationGesture | GestureGroup; 100 101Defines the gesture type. The value type is a union of the types listed in the table below. 102 103**Atomic service API**: This API can be used in atomic services since API version 11. 104 105**System capability**: SystemCapability.ArkUI.ArkUI.Full 106 107| Name| Description| 108| -------- | -------- | 109| [TapGesture](ts-basic-gestures-tapgesture.md) | Tap gesture, which can be a single-tap or multi-tap gesture.| 110| [LongPressGesture](ts-basic-gestures-longpressgesture.md) | Long press gesture.| 111| [PanGesture](ts-basic-gestures-pangesture.md) | Pan gesture, which requires a minimum 5 vp movement distance of a finger on the screen.| 112| [PinchGesture](ts-basic-gestures-pinchgesture.md) | Pinch gesture.| 113| [RotationGesture](ts-basic-gestures-rotationgesture.md) | Rotation gesture.| 114| [SwipeGesture](ts-basic-gestures-swipegesture.md) | Swipe gesture, which can be recognized when the swipe speed is 100 vp/s or higher.| 115| [GestureGroup](ts-combined-gestures.md) | A group of gestures. Continuous recognition, parallel recognition, and exclusive recognition are supported.| 116 117## GestureInterface\<T><sup>11+</sup> 118 119Defines the gesture API. 120 121**Atomic service API**: This API can be used in atomic services since API version 11. 122 123**System capability**: SystemCapability.ArkUI.ArkUI.Full 124 125### tag<sup>11+</sup> 126 127tag(tag: string): T 128 129Sets a tag for the gesture. 130 131**Atomic service API**: This API can be used in atomic services since API version 11. 132 133**System capability**: SystemCapability.ArkUI.ArkUI.Full 134 135**Parameters** 136 137| Name| Type | Mandatory| Description | 138| ------ | ------------------------------------------ | ---- | ---------------------------- | 139| tag | string | Yes | Tag for the gesture.| 140 141**Return value** 142 143| Type | Description | 144| ------ | --------- | 145| T | Current component.| 146 147### allowedTypes<sup>14+</sup> 148 149allowedTypes(types: Array\<SourceTool>): T 150 151Sets the input types that can trigger the gesture response. 152 153**Atomic service API**: This API can be used in atomic services since API version 14. 154 155**System capability**: SystemCapability.ArkUI.ArkUI.Full 156 157**Parameters** 158 159| Name| Type | Mandatory| Description | 160| ------ | ------------------------------------------ | ---- | ---------------------------- | 161| types | Array\<SourceTool> | Yes | Input types that can trigger the gesture response.| 162 163**Return value** 164 165| Type | Description | 166| ------ | --------- | 167| T | Current component.| 168 169 170## GestureMask 171 172**Atomic service API**: This API can be used in atomic services since API version 11. 173 174**System capability**: SystemCapability.ArkUI.ArkUI.Full 175 176| Name|Value| Description| 177| -------- | ---- |-------- | 178| Normal | - |The gestures of child components are enabled and recognized based on the default gesture recognition sequence.| 179| IgnoreInternal | - | The gestures of child components are disabled, including the built-in gestures, such as the built-in swipe gesture for a **List** component. If the areas of the parent and child components are partly overlapped, only gestures in the overlapped areas are disabled.| 180 181## Gesture Response Event 182 183The component binds gesture objects of different **GestureType** instances through gesture events. Each gesture object provides gesture-related information in the gesture response event. In the following example, the **TapGesture** object provides gesture-related information in the **onAction** event. For details about the event definitions of other gestures, see the corresponding gesture sections. To bind multiple gestures, use [combined gestures](ts-combined-gestures.md). 184 185**TapGesture** 186 187| Name| Description| 188| -------- | -------- | 189| onAction((event:GestureEvent) => void) | Callback invoked when a tap gesture is recognized.| 190 191## GestureEvent 192Inherits from [BaseEvent](ts-gesture-customize-judge.md#baseevent8). 193 194**System capability**: SystemCapability.ArkUI.ArkUI.Full 195 196| Name| Type | Read-Only | Optional | Description| 197| -------- | -------- | ---- | ---- |-------- | 198| repeat | boolean | No| No |Whether the event is a repeat trigger event, used in the **LongPressGesture** scenarios. The value **true** means that the event is a repeat trigger event, and **false** means the opposite.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 199| offsetX | number | No| No |X-axis offset of the gesture event relative to the finger press position, in vp. Used in **PanGesture** scenarios. A positive value means to pan from left to right, and a negative value means the opposite.<br>**Atomic service API**: This API can be used in atomic services since API version 11.<br>Value range: (-∞, +∞).| 200| offsetY | number | No| No |Y-axis offset of the gesture event relative to the finger press position, in vp. Used in **PanGesture** scenarios. A positive value means to pan from top to bottom, and a negative value means the opposite.<br>**Atomic service API**: This API can be used in atomic services since API version 11.<br>Value range: (-∞, +∞). | 201| angle | number | No| No |Rotation angle for the **RotationGesture** event;<br>angle of the swipe gesture for the **SwipeGesture** event, that is, the change in the included angle between the line segment created by the two fingers and the horizontal direction.<br>**NOTE**<br>Angle calculation method: After a swipe gesture is recognized, a line connecting the two fingers is identified as the initial line. As the fingers swipe, the line between the fingers rotates. Based on the coordinates of the initial line's and current line's end points, an arc tangent function is used to calculate the respective included angle of the points relative to the horizontal direction by using the following formula: Rotation angle = arctan2(cy2-cy1,cx2-cx1) - arctan2(y2-y1,x2-x1) The initial line is used as the coordinate system. The clockwise rotation is 0 to 180 degrees, and the counter-clockwise rotation is –180 to 0 degrees.<br>Value range: [-180, +180].<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 202| scale | number |No| No |Scale ratio. This attribute is used for the **PinchGesture** event.<br>Value range: [0, +∞).<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 203| pinchCenterX | number | No| No |X-coordinate of the pinch center, in vp. Used for the **PinchGesture** event.<br>Value range: [0, +∞).<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 204| pinchCenterY | number | No| No |Y-coordinate of the pinch center, in vp. Used for the **PinchGesture** event.<br>Value range: [0, +∞).<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 205| speed<sup>8+</sup> | number | No| No |Swipe gesture speed, that is, the average swipe speed of all fingers relative to the original area of the current component. The unit is vp/s. This attribute is used for the **SwipeGesture** event.<br>Value range: [0, +∞).<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 206| fingerList<sup>8+</sup> | [FingerInfo](#fingerinfo8)[] | No| No |List of touch points of the gesture event. If the event input device is touchscreen, the list includes all touch points. If the event input device is mouse or touchpad, the list contains only one touch point.<br>**NOTE**<br>The index of a finger corresponds to its position, that is, the ID of a finger in **fingerList[index]** refers to its index. If a finger is pressed first and does not participate in triggering of the current gesture, its position in **fingerList** is left empty.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 207| fingerInfos<sup>20+</sup> | [FingerInfo](#fingerinfo8)[] | No| Yes |Information about touch points of the gesture event. For gesture events initiated by a touchscreen, **fingerInfos** includes information about all touch points. For gesture events initiated by a mouse or touchpad, **fingerInfos** contains only one touch point.<br> **NOTE**<br>**fingerInfos** only records information about effective fingers that participate in the touch. Fingers that are pressed first but do not participate in triggering of the current gesture will not be shown in **fingerInfos**. The default value is an empty array **[]**, and an empty array indicates no effective touch point information.<br>**Atomic service API**: This API can be used in atomic services since API version 20.| 208| velocityX<sup>10+</sup> | number | No| No |Velocity along the x-axis. This parameter is used in [PanGesture](ts-basic-gestures-pangesture.md). The origin of the coordinate axis is the upper left corner of the screen. The velocity is positive if the movement is from left to right, and it is negative if the movement is from right to left. The unit is vp/s.<br>Value range: (-∞, +∞).<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 209| velocityY<sup>10+</sup> | number | No| No |Velocity along the y-axis. This parameter is used in [PanGesture](ts-basic-gestures-pangesture.md). The origin of the coordinate axis is the upper left corner of the screen. The velocity is positive if the movement is from top to bottom, and it is negative if the movement is from bottom to top. The unit is vp/s.<br>Value range: (-∞, +∞).<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 210| velocity<sup>10+</sup> | number | No| No |Velocity along the main axis. This parameter is used in [PanGesture](ts-basic-gestures-pangesture.md). The value is the arithmetic square root of the sum of squares of the velocity along the x- and y-axis. The unit is vp/s.<br>Value range: [0, +∞).<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 211| tapLocation<sup>20+</sup> | [EventLocationInfo](ts-basic-gestures-tapgesture.md#eventlocationinfo20) | No| Yes |Coordinate information of the current tap gesture.<br> **Atomic service API**: This API can be used in atomic services since API version 20.| 212 213## SourceType<sup>8+</sup> 214 215**Atomic service API**: This API can be used in atomic services since API version 11. 216 217**System capability**: SystemCapability.ArkUI.ArkUI.Full 218 219| Name| Value| Description| 220| ---- | --- | -------- | 221| Unknown | - | Unknown device type.| 222| Mouse | - | Mouse.| 223| TouchScreen | - | Touchscreen.| 224 225## FingerInfo<sup>8+</sup> 226 227**System capability**: SystemCapability.ArkUI.ArkUI.Full 228 229| Name| Type| Read-Only| Optional| Description| 230| -------- | -------- | -------- |--------- |-------- | 231| id | number | No | No |Index of the finger, determined by the number of fingers pressed. The first pressed finger is assigned 0, with the index incrementing by one for each subsequent finger.<br>**NOTE**<br> Indexes for other input sources (mouse: 1001, stylus: 102, mouse wheel: 0, two-finger trackpad slide: 0) are also converted to finger indexes.<br>Value range: [0, 9).<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 232| globalX | number | No | No |X-coordinate relative to the upper left corner of the application window, in vp.<br>Value range: [0, +∞).<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 233| globalY | number | No | No |Y-coordinate relative to the upper left corner of the application window, in vp.<br>Value range: [0, +∞).<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 234| localX | number | No | No |X-coordinate relative to the upper left corner of the current component's original area, in vp.<br>Value range: [0, +∞).<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 235| localY | number | No | No |Y-coordinate relative to the upper left corner of the current component's original area, in vp.<br>Value range: [0, +∞).<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 236| displayX<sup>12+</sup> | number | No | No | X-coordinate relative to the upper left corner of the screen, in vp.<br>Value range: [0, +∞).<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 237| displayY<sup>12+</sup> | number | No | No |Y-coordinate relative to the upper left corner of the screen, in vp.<br>Value range: [0, +∞).<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 238| hand<sup>15+</sup> | [InteractionHand](#interactionhand15) | No | Yes |Whether the event is triggered by a left-hand or right-hand tap.<br>**Atomic service API**: This API can be used in atomic services since API version 15.| 239| globalDisplayX<sup>20+</sup> | number | No | Yes |X-coordinate relative to the upper left corner of the global display, in vp.<br>Value range: [0, +∞).<br>**Atomic service API**: This API can be used in atomic services since API version 20.| 240| globalDisplayY<sup>20+</sup> | number | No | Yes |Y-coordinate relative to the upper left corner of the global display, in vp.<br>Value range: [0, +∞).<br>**Atomic service API**: This API can be used in atomic services since API version 20.| 241 242## SourceTool<sup>9+</sup> 243 244**System capability**: SystemCapability.ArkUI.ArkUI.Full 245 246| Name| Value| Description| 247| -------- | - | --------- | 248| Unknown | - | Unknown input source.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 249| Finger | - | Finger.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 250| Pen | - | Stylus.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 251| MOUSE<sup>12+</sup> | - | Mouse device.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 252| TOUCHPAD<sup>12+</sup> | - | Touchpad. Single-finger input on the touchpad is treated as a mouse input operation.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 253| JOYSTICK<sup>12+</sup> | - | Joystick.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 254 255## InteractionHand<sup>15+</sup> 256 257Defines whether an event is triggered by a left-hand or right-hand tap. 258 259**Atomic service API**: This API can be used in atomic services since API version 15. 260 261**System capability**: SystemCapability.ArkUI.ArkUI.Full 262 263| Name| Description| 264| -------- | -------- | 265| NONE | Unknown.| 266| LEFT | Left hand.| 267| RIGHT | Right hand.| 268 269 270## Example 271 272### Example 1: Implementing Parent Component Prioritization and Simultaneous Gesture Triggering 273 274This example demonstrates how to configure **priorityGesture** and **parallelGesture** to set up gesture recognition where the parent component has priority in recognizing gestures, and both parent and child components can trigger gestures simultaneously. 275 276```ts 277// xxx.ets 278@Entry 279@Component 280struct GestureSettingsExample { 281 @State priorityTestValue: string = '' 282 @State parallelTestValue: string = '' 283 284 build() { 285 Column() { 286 Column() { 287 Text('TapGesture:' + this.priorityTestValue).fontSize(28) 288 .gesture( 289 TapGesture() 290 .onAction((event: GestureEvent) => { 291 this.priorityTestValue += '\nText' 292 })) 293 } 294 .height(200) 295 .width(250) 296 .padding(20) 297 .margin(20) 298 .border({ width: 3 }) 299 // When priorityGesture is set, the tap gesture on the Column component is prioritized over the tap gesture on the child Text component. 300 .priorityGesture( 301 TapGesture() 302 .onAction((event: GestureEvent) => { 303 this.priorityTestValue += '\nColumn' 304 }), GestureMask.IgnoreInternal) 305 306 Column() { 307 Text('TapGesture:' + this.parallelTestValue).fontSize(28) 308 .gesture( 309 TapGesture() 310 .onAction((event: GestureEvent) => { 311 this.parallelTestValue += '\nText' 312 })) 313 } 314 .height(200) 315 .width(250) 316 .padding(20) 317 .margin(20) 318 .border({ width: 3 }) 319 // When parallelGesture is set, the tap gestures on the Column component and on the child Text component are both recognized. 320 .parallelGesture( 321 TapGesture() 322 .onAction((event: GestureEvent) => { 323 this.parallelTestValue += '\nColumn' 324 }), GestureMask.Normal) 325 } 326 } 327} 328``` 329 330 331 332### Example 2: Implementing Real-time Monitoring of Effective Touch Points Involved in a Swipe Gesture 333 334This example demonstrates how to configure **fingerInfos** to monitor the number of effective touch points involved in a swipe gesture in real time. 335 336```ts 337// xxx.ets 338@Entry 339@Component 340 341struct PanGestureWithFingerCount { 342 @State offsetX: number = 0 343 @State offsetY: number = 0 344 @State positionX: number = 0 345 @State positionY: number = 0 346 @State fingerCount: number = 0 // Used to record the number of touch points involved in the gesture. 347 348 private panOption: PanGestureOptions = new PanGestureOptions({ 349 direction: PanDirection.All, 350 fingers: 1 351 }) 352 353 build() { 354 Column() { 355 // Display the number of effective touch points. 356 Text(`Touch Points: ${this.fingerCount}`) 357 .fontSize(20) 358 .margin(10) 359 360 Column() { 361 Text('PanGesture offset:\nX: ' + this.offsetX + '\n' + 'Y: ' + this.offsetY) 362 } 363 .height(200) 364 .width(300) 365 .padding(20) 366 .border({ width: 3 }) 367 .margin(50) 368 .translate({ x: this.offsetX, y: this.offsetY, z: 0 }) 369 .gesture( 370 PanGesture(this.panOption) 371 .onActionStart((event: GestureEvent) => { 372 console.info('Pan start') 373 this.fingerCount = event.fingerInfos?.length || 0 // Record the number of touch points. 374 }) 375 .onActionUpdate((event: GestureEvent) => { 376 if (event) { 377 console.info('fingerInfos',JSON.stringify(event.fingerInfos)) 378 this.offsetX = this.positionX + event.offsetX 379 this.offsetY = this.positionY + event.offsetY 380 this.fingerCount = event.fingerInfos?.length || 0 // Update the number of touch points, recording the effective touch points involved in the current gesture. 381 } 382 }) 383 .onActionEnd((event: GestureEvent) => { 384 this.positionX = this.offsetX 385 this.positionY = this.offsetY 386 this.fingerCount = 0 // Reset the value to zero when the touch points leave the touch target. 387 console.info('Pan end') 388 }) 389 .onActionCancel(() => { 390 this.fingerCount = 0 // Reset the value to zero when the gesture is canceled. 391 }) 392 ) 393 394 Button('Switch to Two-Finger Swipe') 395 .onClick(() => { 396 this.panOption.setFingers(2) 397 }) 398 } 399 } 400} 401``` 402
