1# Combined Gestures
2
3
4A combined gesture is a combination of multiple single gestures. Its recognition mode is subject to **GestureMode** passed in **GestureGroup**. Three recognition modes are supported: [sequential recognition](#sequential-recognition), [parallel recognition](#parallel-recognition), and [exclusive recognition](#exclusive-recognition).
5
6```ts
7GestureGroup(mode:GestureMode, gesture:GestureType[])
8```
9
10
11- **mode**: recognition mode of combined gestures. The value belongs to the **GestureMode** enumeration class.
12
13- **gesture**: array of multiple gestures.
14
15
16## Sequential Recognition
17
18For sequential recognition, the value of **GestureMode** is **Sequence**. In this gesture recognition mode, gestures are recognized in the order in which they were registered until they are all recognized successfully. If any of the registered gestures fails to be recognized, subsequent gestures will also fail. Only the last gesture recognized responds to the **onActionEnd** event.
19
20In the following example, the combined gestures for continuous recognition are the long press gesture and pan gesture.
21
22The **translate** attribute is bound to a **Column** component. You can set the attribute to translate the component. Then, bind **LongPressGesture** and **PanGesture** to the component in the **Sequence** gesture mode. When a long press gesture is recognized, the displayed number is updated. When the user drags the component after the long press gesture, the component is dragged based on the callback function of the pan gesture.
23
24```ts
25// xxx.ets
26@Entry
27@Component
28struct Index {
29  @State offsetX: number = 0;
30  @State offsetY: number = 0;
31  @State count: number = 0;
32  @State positionX: number = 0;
33  @State positionY: number = 0;
34  @State borderStyles: BorderStyle = BorderStyle.Solid
35
36  build() {
37    Column() {
38      Text('sequence gesture\n' + 'LongPress onAction:' + this.count + '\nPanGesture offset:\nX: ' + this.offsetX + '\n' + 'Y: ' + this.offsetY)
39        .fontSize(28)
40    }.margin(10)
41    .borderWidth(1)
42    // Bind the translate attribute to translate the component.
43    .translate({ x: this.offsetX, y: this.offsetY, z: 0 })
44    .height(250)
45    .width(300)
46    // The following combined gestures are recognized in sequence. When the long press gesture event is not triggered correctly, the pan gesture event is not triggered.
47    .gesture(
48      // Set the gesture mode to Sequence.
49      GestureGroup(GestureMode.Sequence,
50        // The first gesture recognized in the combined gestures is the long press gesture, which can be responded to for multiple times.
51        LongPressGesture({ repeat: true })
52          // When the long press gesture is successfully recognized, the value of count displayed on the Text component is increased.
53          .onAction((event: GestureEvent|undefined) => {
54            if(event){
55              if (event.repeat) {
56                this.count++;
57              }
58            }
59            console.info('LongPress onAction');
60          })
61          .onActionEnd(() => {
62            console.info('LongPress end');
63          }),
64        // The pan gesture is triggered when the component is dragged after the long press gesture is recognized.
65        PanGesture()
66          .onActionStart(() => {
67            this.borderStyles = BorderStyle.Dashed;
68            console.info('pan start');
69          })
70            // When the gesture is triggered, the pan distance is obtained based on the callback, and the displacement distance of the component is modified. In this way, the component is translated.
71          .onActionUpdate((event: GestureEvent|undefined) => {
72            if(event){
73              this.offsetX = (this.positionX + event.offsetX);
74              this.offsetY = this.positionY + event.offsetY;
75            }
76            console.info('pan update');
77          })
78          .onActionEnd(() => {
79            this.positionX = this.offsetX;
80            this.positionY = this.offsetY;
81            this.borderStyles = BorderStyle.Solid;
82          })
83      )
84      .onCancel(() => {
85        console.log("sequence gesture canceled")
86      })
87    )
88  }
89}
90```
91
92
93![sequence](figures/sequence.gif)
94
95
96>**NOTE**
97>
98>The drag event is a typical use case of sequential recognition on the long press gesture and pan gesture. It is triggered only when the user performs a pan gesture within the preset time frame after a long press gesture is recognized. If the long press gesture is not recognized or the pan gesture is not performed within the preset time frame, the drag event will not be triggered.
99
100
101## Parallel Recognition
102
103For parallel recognition, the value of **GestureMode** is **Parallel**. In this gesture recognition mode, gestures registered in the combined gestures will be recognized at the same time until they are all recognized successfully. The gestures are recognized in parallel without affecting each other.
104
105For example, if the tap gesture and the double-tap gesture are bound to the **Column** component in parallel recognition mode, they can be recognized at the same time, and the recognition of these two gestures does not interfere with each other.
106
107```ts
108// xxx.ets
109@Entry
110@Component
111struct Index {
112  @State count1: number = 0;
113  @State count2: number = 0;
114
115  build() {
116    Column() {
117      Text('Parallel gesture\n' + 'tapGesture count is 1:' + this.count1 + '\ntapGesture count is 2:' + this.count2 + '\n')
118        .fontSize(28)
119    }
120    .height(200)
121    .width('100%')
122    // The following combined gestures are recognized in parallel mode. After a tap gesture is recognized successfully, if another tap gesture is recognized within the specified time frame, a double-tap gesture will also be recognized.
123    .gesture(
124      GestureGroup(GestureMode.Parallel,
125        TapGesture({ count: 1 })
126          .onAction(() => {
127            this.count1++;
128          }),
129        TapGesture({ count: 2 })
130          .onAction(() => {
131            this.count2++;
132          })
133      )
134    )
135  }
136}
137```
138
139
140![parallel](figures/parallel.gif)
141
142
143>**NOTE**
144>
145>After a tap gesture and a double-tap gesture are combined for parallel recognition, when taps are performed in an area, the tap gesture and the double-tap gesture are recognized at the same time.
146>
147>When there is only a single tap, the tap gesture is recognized, but the double-tap gesture fails to be recognized.
148>
149>When there are two taps and the interval between the two taps is within a specified period (300 ms by default), two tap events and one double-tap event are triggered.
150>
151>When there are two taps, but the interval between the two taps exceeds the specified time, two tap events are triggered but the double-tap event is not triggered.
152
153
154## Exclusive Recognition
155
156For exclusive recognition, the value of **GestureMode** is **Exclusive**. In this gesture recognition mode, all registered gestures are recognized at once. Once any of the gestures is recognized successfully, the gesture recognition ends, and all other gestures fail to be recognized.
157
158For example, when the tap gesture and the double-tap gesture are bound to the **Column** component in exclusive recognition mode, if you bind the tap gesture first, followed by the double-tap, the double-tap gesture won't be recognized because the tap consumes all touch events. However, if you bind the double-tap gesture first, it will be recognized without triggering the tap.
159
160```ts
161// xxx.ets
162@Entry
163@Component
164struct Index {
165  @State count1: number = 0;
166  @State count2: number = 0;
167
168  build() {
169    Column() {
170      Text('Exclusive gesture\n' + 'tapGesture count is 1:' + this.count1 + '\ntapGesture count is 2:' + this.count2 + '\n')
171        .fontSize(28)
172    }
173    .height(200)
174    .width('100%')
175    // The following combined gestures are mutually exclusive. After the tap gesture is recognized successfully, the double-tap gesture fails to be recognized.
176    .gesture(
177      GestureGroup(GestureMode.Exclusive,
178        TapGesture({ count: 1 })
179          .onAction(() => {
180            this.count1++;
181          }),
182        TapGesture({ count: 2 })
183          .onAction(() => {
184            this.count2++;
185          })
186      )
187    )
188  }
189}
190```
191
192
193![exclusive](figures/exclusive.gif)
194
195
196>**NOTE**
197>
198>After a tap gesture and a double-tap gesture are combined for exclusive recognition, when taps are performed in an area, the tap gesture and the double-tap gesture are recognized at the same time.
199>
200>When there is only a single tap, the tap gesture is recognized, but the double-tap gesture fails to be recognized.
201>
202>When there are two taps, the gesture response depends on the order of gesture binding. If you bind the tap gesture first, followed by the double-tap gesture, the tap gesture will be recognized on the first tap, causing the double-tap gesture to fail. Even if the second tap is performed within the specified time, the double-tap gesture event is not responded to. Instead, another tap gesture event is triggered. Conversely, if you bind the double-tap gesture first, it will be recognized without triggering the tap gesture.
203