1# Gesture Binding 2 3Bind different types of gesture events to components and set response methods for them. 4 5> **NOTE** 6> 7> The APIs of this module are supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. 8 9 10## Binding Gesture Recognition 11 12Use the following attributes to bind gesture recognition to a component. When a gesture is recognized, the event callback is invoked to notify the component. 13A region in which a gesture can be recognized may be specified by the [touch target](ts-universal-attributes-touch-target.md). 14 15**Atomic service API**: This API can be used in atomic services since API version 11. 16 17| Name| Type| Default Value| Description| 18| -------- | -------- | -------- | -------- | 19| gesture | gesture: [GestureType](#gesturetype),<br>mask?: [GestureMask](#gesturemask) | gesture: -,<br>mask: GestureMask.Normal | Gesture to bind.<br>- **gesture**: type of the gesture to bind. <br>- **mask**: mask for gesture events.| 20| priorityGesture | gesture: [GestureType](#gesturetype),<br>mask?: [GestureMask](#gesturemask) | gesture: -,<br>mask: GestureMask.Normal | Gesture to preferentially recognize.<br>- **gesture**: type of the gesture to bind.<br>- **mask**: mask for gesture events.<br>1. 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).<br>2. With regard to long press gestures, the component with the shortest minimum hold-down time responds first, ignoring the **priorityGesture** settings.| 21| parallelGesture | gesture: [GestureType](#gesturetype),<br>mask?: [GestureMask](#gesturemask) | gesture: -,<br>mask: GestureMask.Normal | Gesture that can be recognized at once by the component and its child component.<br>- **gesture**: type of the gesture to bind. <br>- **mask**: mask for gesture events.<br>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.| 22 23 24## GestureType 25 26**Atomic service API**: This API can be used in atomic services since API version 12. 27 28| Name| Description| 29| -------- | -------- | 30| [TapGesture](ts-basic-gestures-tapgesture.md) | Tap gesture, which can be a single-tap or multi-tap gesture.| 31| [LongPressGesture](ts-basic-gestures-longpressgesture.md) | Long press gesture.| 32| [PanGesture](ts-basic-gestures-pangesture.md) | Pan gesture, which requires a minimum 5 vp movement distance of a finger on the screen.| 33| [PinchGesture](ts-basic-gestures-pinchgesture.md) | Pinch gesture.| 34| [RotationGesture](ts-basic-gestures-rotationgesture.md) | Rotation gesture.| 35| [SwipeGesture](ts-basic-gestures-swipegesture.md) | Swipe gesture, which can be recognized when the swipe speed is 100 vp/s or higher.| 36| [GestureGroup](ts-combined-gestures.md) | A group of gestures. Continuous recognition, parallel recognition, and exclusive recognition are supported.| 37 38 39## GestureMask 40 41**Atomic service API**: This API can be used in atomic services since API version 11. 42 43| Name| Description| 44| -------- | -------- | 45| Normal | The gestures of child components are enabled and recognized based on the default gesture recognition sequence.| 46| 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.| 47 48## Gesture Response Event 49 50The 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). 51 52**TapGesture** 53 54| Name| Description| 55| -------- | -------- | 56| onAction((event:GestureEvent) => void) | Callback invoked when a tap gesture is recognized.| 57 58## GestureEvent 59 60Inherits from [BaseEvent](ts-gesture-customize-judge.md#baseevent). 61 62**Atomic service API**: This API can be used in atomic services since API version 11. 63 64| Name| Type| Description| 65| -------- | -------- | -------- | 66| repeat | boolean | Whether the event is triggered repeatedly. This attribute is used for the **LongPressGesture** event.| 67| offsetX | number | Offset in the X coordinate of the gesture event, in vp. This attribute is used for the **PanGesture** event. A positive value means to pan from left to right, and a negative value means the opposite.| 68| offsetY | number | Offset in the Y coordinate of the gesture event, in vp. This attribute is used for the **PanGesture** event. A positive value means to pan from top to bottom, and a negative value means the opposite.| 69| angle | number | 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.| 70| scale | number | Scale ratio. This attribute is used for the **PinchGesture** event.| 71| pinchCenterX | number | X coordinate of the pinch center, in vp. This attribute is used for the **PinchGesture** event.| 72| pinchCenterY | number | Y coordinate of the pinch center, in vp. This attribute is used for the **PinchGesture** event.| 73| speed<sup>8+</sup> | number | 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.| 74| fingerList<sup>8+</sup> | [FingerInfo](#fingerinfo8)[] | List of contact points of the gesture event. If the event input device is touchscreen, the list includes all contact points. If the event input device is mouse or touchpad, the list contains only one contact 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.| 75| velocityX<sup>10+</sup> | number | 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.| 76| velocityY<sup>10+</sup> | number | 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.| 77| velocity<sup>10+</sup> | number | 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.| 78 79## SourceType 80 81**Atomic service API**: This API can be used in atomic services since API version 11. 82 83| Name| Description| 84| -------- | -------- | 85| Unknown | Unknown device type.| 86| Mouse | Mouse.| 87| TouchScreen | Touchscreen.| 88 89## FingerInfo<sup>8+</sup> 90 91| Name| Type| Description| 92| -------- | -------- | -------- | 93| id | number | Index of a finger.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 94| globalX | number | X-coordinate relative to the upper left corner of the application window, in vp.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 95| globalY | number | Y-coordinate relative to the upper left corner of the application window, in vp.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 96| localX | number | X-coordinate relative to the upper left corner of the current component's original area, in vp.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 97| localY | number | Y-coordinate relative to the upper left corner of the current component's original area, in vp.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 98| displayX<sup>12+</sup> | number | X-coordinate relative to the upper left corner of the screen, in vp.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 99| displayY<sup>12+</sup> | number | Y-coordinate relative to the upper left corner of the screen, in vp.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 100 101## SourceTool<sup>9+</sup> 102 103| Name| Description| 104| -------- | -------- | 105| Unknown | Unknown input source.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 106| Finger | Finger.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 107| Pen | Stylus.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 108| Mouse<sup>12+</sup> | Mouse device.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 109| 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.| 110| Joystick<sup>12+</sup> | Joystick.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 111 112 113## Example 114 115This 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. 116 117```ts 118// xxx.ets 119@Entry 120@Component 121struct GestureSettingsExample { 122 @State priorityTestValue: string = '' 123 @State parallelTestValue: string = '' 124 125 build() { 126 Column() { 127 Column() { 128 Text('TapGesture:' + this.priorityTestValue).fontSize(28) 129 .gesture( 130 TapGesture() 131 .onAction((event: GestureEvent) => { 132 this.priorityTestValue += '\nText' 133 })) 134 } 135 .height(200) 136 .width(250) 137 .padding(20) 138 .margin(20) 139 .border({ width: 3 }) 140 // When priorityGesture is set, the tap gesture on the Column component is prioritized over the tap gesture on the child Text component. 141 .priorityGesture( 142 TapGesture() 143 .onAction((event: GestureEvent) => { 144 this.priorityTestValue += '\nColumn' 145 }), GestureMask.IgnoreInternal) 146 147 Column() { 148 Text('TapGesture:' + this.parallelTestValue).fontSize(28) 149 .gesture( 150 TapGesture() 151 .onAction((event: GestureEvent) => { 152 this.parallelTestValue += '\nText' 153 })) 154 } 155 .height(200) 156 .width(250) 157 .padding(20) 158 .margin(20) 159 .border({ width: 3 }) 160 // When parallelGesture is set, the tap gestures on the Column component and on the child Text component are both recognized. 161 .parallelGesture( 162 TapGesture() 163 .onAction((event: GestureEvent) => { 164 this.parallelTestValue += '\nColumn' 165 }), GestureMask.Normal) 166 } 167 } 168} 169``` 170 171 172
