1/*
2 * Copyright (c) 2024 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16/**
17 * @addtogroup ArkUI_NativeModule
18 * @{
19 *
20 * @brief Defines APIs for ArkUI to register gesture callbacks on the native side.
21 *
22 * @since 12
23 */
24
25/**
26 * @file native_gesture.h
27 *
28 * @brief Provides type definitions for <b>NativeGesture</b> APIs.
29 *
30 * @library libace_ndk.z.so
31 * @syscap SystemCapability.ArkUI.ArkUI.Full
32 * @kit ArkUI
33 * @since 12
34 */
35
36#ifndef ARKUI_NATIVE_GESTTURE_H
37#define ARKUI_NATIVE_GESTTURE_H
38
39#include "ui_input_event.h"
40#include "native_type.h"
41#include <stdbool.h>
42
43#ifdef __cplusplus
44extern "C" {
45#endif
46
47/**
48 * @brief Defines a gesture recognizer.
49 *
50 * @since 12
51 */
52typedef struct ArkUI_GestureRecognizer ArkUI_GestureRecognizer;
53
54/**
55 * @brief Defines the gesture interruption information.
56 *
57 * @since 12
58 */
59typedef struct ArkUI_GestureInterruptInfo ArkUI_GestureInterruptInfo;
60
61/**
62 * @brief Defines the gesture event.
63 *
64 * @since 12
65 */
66typedef struct ArkUI_GestureEvent ArkUI_GestureEvent;
67
68/**
69 * @brief Enumerates gesture event types.
70 *
71 * @since 12
72 */
73typedef enum {
74    /** Triggered. */
75    GESTURE_EVENT_ACTION_ACCEPT = 0x01,
76
77    /** Updated. */
78    GESTURE_EVENT_ACTION_UPDATE = 0x02,
79
80    /** Ended. */
81    GESTURE_EVENT_ACTION_END = 0x04,
82
83    /** Canceled. */
84    GESTURE_EVENT_ACTION_CANCEL = 0x08,
85} ArkUI_GestureEventActionType;
86
87/**
88 * @brief Defines a set of gesture event types.
89 *
90 * Example: ArkUI_GestureEventActionTypeMask actions = GESTURE_EVENT_ACTION_ACCEPT | GESTURE_EVENT_ACTION_UPDATE;\n
91 *
92 * @since 12
93 */
94typedef uint32_t ArkUI_GestureEventActionTypeMask;
95
96/**
97 * @brief Enumerates gesture event modes.
98 *
99 * @since 12
100 */
101typedef enum {
102    /** Normal. */
103    NORMAL = 0,
104
105    /** High-priority. */
106    PRIORITY = 1,
107
108    /** Parallel. */
109    PARALLEL = 2,
110} ArkUI_GesturePriority;
111
112/**
113 * @brief Enumerates gesture group modes.
114 *
115 * @since 12
116 */
117typedef enum {
118    /* Sequential recognition. Gestures are recognized in the registration sequence until all gestures are recognized
119     * successfully. Once one gesture fails to be recognized, all subsequent gestures fail to be recognized.
120     * Only the last gesture in the gesture group can respond to the end event. */
121    SEQUENTIAL_GROUP = 0,
122
123    /** Parallel recognition. Registered gestures are recognized concurrently until all gestures are recognized.
124      * The recognition result of each gesture does not affect each other. */
125    PARALLEL_GROUP = 1,
126
127    /** Exclusive recognition. Registered gestures are identified concurrently.
128      * If one gesture is successfully recognized, gesture recognition ends. */
129    EXCLUSIVE_GROUP = 2,
130} ArkUI_GroupGestureMode;
131
132/**
133 * @brief Enumerates gesture directions.
134 *
135 * @since 12
136 */
137typedef enum {
138    /** All directions. */
139    GESTURE_DIRECTION_ALL = 0b1111,
140
141    /** Horizontal direction. */
142    GESTURE_DIRECTION_HORIZONTAL = 0b0011,
143
144    /** Vertical direction. */
145    GESTURE_DIRECTION_VERTICAL = 0b1100,
146
147    /** Leftward. */
148    GESTURE_DIRECTION_LEFT = 0b0001,
149
150    /** Rightward. */
151    GESTURE_DIRECTION_RIGHT = 0b0010,
152
153    /** Upward. */
154    GESTURE_DIRECTION_UP = 0b0100,
155
156    /** Downward. */
157    GESTURE_DIRECTION_DOWN = 0b1000,
158
159    /** None. */
160    GESTURE_DIRECTION_NONE = 0,
161} ArkUI_GestureDirection;
162
163/**
164 * @brief Defines a set of gesture directions.
165 *
166 * Example: ArkUI_GestureDirectionMask directions = GESTURE_DIRECTION_LEFT | GESTURE_DIRECTION_RIGHT \n
167 * This example indicates that the leftward and rightward directions are supported. \n
168 *
169 * @since 12
170 */
171typedef uint32_t ArkUI_GestureDirectionMask;
172
173/**
174 * @brief Enumerates gesture masking modes.
175 *
176 * @since 12
177 */
178typedef enum {
179    /** The gestures of child components are enabled and recognized based on the default gesture recognition sequence.*/
180    NORMAL_GESTURE_MASK = 0,
181
182    /** The gestures of child components are disabled, including the built-in gestures. */
183    IGNORE_INTERNAL_GESTURE_MASK,
184} ArkUI_GestureMask;
185
186/**
187 * @brief Enumerates gesture types.
188 *
189 * @since 12
190 */
191typedef enum {
192    /** Tap. */
193    TAP_GESTURE = 0,
194
195    /** Long press. */
196    LONG_PRESS_GESTURE,
197
198    /** Pan. */
199    PAN_GESTURE,
200
201    /** Pinch. */
202    PINCH_GESTURE,
203
204    /** Rotate. */
205    ROTATION_GESTURE,
206
207    /** Swipe. */
208    SWIPE_GESTURE,
209
210    /** A group of gestures. */
211    GROUP_GESTURE,
212} ArkUI_GestureRecognizerType;
213
214/**
215 * @brief Enumerates gesture interruption results.
216 *
217 * @since 12
218 */
219typedef enum {
220    /** The gesture recognition process continues. */
221    GESTURE_INTERRUPT_RESULT_CONTINUE = 0,
222
223    /** The gesture recognition process is paused. */
224    GESTURE_INTERRUPT_RESULT_REJECT,
225} ArkUI_GestureInterruptResult;
226
227/**
228 * @brief Enumerates the gesture recognizer states.
229 *
230 * @since 12
231 */
232typedef enum {
233    /** Ready. */
234    ARKUI_GESTURE_RECOGNIZER_STATE_READY = 0,
235
236    /** Detecting. */
237    ARKUI_GESTURE_RECOGNIZER_STATE_DETECTING = 1,
238
239    /** Pending. */
240    ARKUI_GESTURE_RECOGNIZER_STATE_PENDING = 2,
241
242    /** Blocked. */
243    ARKUI_GESTURE_RECOGNIZER_STATE_BLOCKED = 3,
244
245    /** Successful. */
246    ARKUI_GESTURE_RECOGNIZER_STATE_SUCCESSFUL = 4,
247
248    /** Failed. */
249    ARKUI_GESTURE_RECOGNIZER_STATE_FAILED = 5,
250} ArkUI_GestureRecognizerState;
251
252/**
253 * @brief Defines the gesture recognizer handle.
254 *
255 * @since 12
256 */
257typedef ArkUI_GestureRecognizer* ArkUI_GestureRecognizerHandle;
258
259/**
260 * @brief Defines the gesture recognizer handle array.
261 *
262 * @since 12
263 */
264typedef ArkUI_GestureRecognizerHandle* ArkUI_GestureRecognizerHandleArray;
265
266/**
267 * @brief Defines a <b>GestureEventTargetInfo</b> object that provides information about a gesture event target.
268 *
269 * @since 12
270 */
271typedef struct ArkUI_GestureEventTargetInfo ArkUI_GestureEventTargetInfo;
272
273/**
274 * @brief Defines a parallel internal gesture event.
275 *
276 * @since 12
277 */
278typedef struct ArkUI_ParallelInnerGestureEvent ArkUI_ParallelInnerGestureEvent;
279
280/**
281 * @brief Defines a callback function for notifying gesture recognizer destruction.
282 * @since 12
283 */
284typedef void (*ArkUI_GestureRecognizerDisposeNotifyCallback)(ArkUI_GestureRecognizer* recognizer, void* userData);
285
286/**
287* @brief Checks whether a gesture is a built-in gesture of the component.
288*
289* @param event Indicates the pointer to the gesture interruption information.
290* @return Returns <b>true</b> if the gesture is a built-in gesture; returns <b>false</b> otherwise.
291
292* @since 12
293*/
294bool OH_ArkUI_GestureInterruptInfo_GetSystemFlag(const ArkUI_GestureInterruptInfo* event);
295
296/**
297* @brief Obtains the pointer to interrupted gesture recognizer.
298*
299* @param event Indicates the pointer to the gesture interruption information.
300* @return Returns the pointer to interrupted gesture recognizer.
301* @since 12
302*/
303ArkUI_GestureRecognizer* OH_ArkUI_GestureInterruptInfo_GetRecognizer(const ArkUI_GestureInterruptInfo* event);
304
305/**
306* @brief Obtains the pointer to the interrupted gesture event.
307*
308* @param event Indicates the pointer to the gesture interruption information.
309* @return Returns the pointer to the interrupted gesture event.
310* @since 12
311*/
312ArkUI_GestureEvent* OH_ArkUI_GestureInterruptInfo_GetGestureEvent(const ArkUI_GestureInterruptInfo* event);
313
314/**
315* @brief Obtains the type of the system gesture to trigger.
316*
317* @param event Indicates the pointer to the gesture interruption information.
318* @return Returns the type of the system gesture to trigger. If the gesture to trigger is not a system gesture,
319*         <b>-1</b> is returned.
320* @since 12
321*/
322int32_t OH_ArkUI_GestureInterruptInfo_GetSystemRecognizerType(const ArkUI_GestureInterruptInfo* event);
323
324/**
325* @brief Obtains the gesture event type.
326*
327* @param event Indicates the pointer to the gesture event.
328* @return Returns the gesture event type.
329* @since 12
330*/
331ArkUI_GestureEventActionType OH_ArkUI_GestureEvent_GetActionType(const ArkUI_GestureEvent* event);
332
333/**
334* @brief Obtains gesture input.
335*
336* @param event Indicates the pointer to the gesture event.
337* @return Returns the pointer to the input event of the gesture event.
338* @since 12
339*/
340const ArkUI_UIInputEvent* OH_ArkUI_GestureEvent_GetRawInputEvent(const ArkUI_GestureEvent* event);
341
342/**
343* @brief Obtains the number of times that a long press gesture is triggered periodically.
344*
345* @param event Indicates the pointer to the gesture event.
346* @return Returns the number of times that the long press gesture is triggered periodically.
347* @since 12
348*/
349int32_t OH_ArkUI_LongPress_GetRepeatCount(const ArkUI_GestureEvent* event);
350
351/**
352* @brief Obtains the velocity of a pan gesture along the main axis.
353*
354* @param event Indicates the pointer to the gesture event.
355* @return Returns the velocity of the pan gesture along the main axis, in px/s.
356*         The value is the square root of the sum of the squares of the velocity on the x-axis and y-axis.
357* @since 12
358*/
359float OH_ArkUI_PanGesture_GetVelocity(const ArkUI_GestureEvent* event);
360
361/**
362* @brief Obtains the velocity of a pan gesture along the x-axis.
363*
364* @param event Indicates the pointer to the gesture event.
365* @return Returns the velocity of the pan gesture along the x-axis, in px/s.
366* @since 12
367*/
368float OH_ArkUI_PanGesture_GetVelocityX(const ArkUI_GestureEvent* event);
369
370/**
371* @brief Obtains the velocity of a pan gesture along the y-axis.
372*
373* @param event Indicates the pointer to the gesture event.
374* @return Returns the velocity of the pan gesture along the y-axis, in px/s.
375* @since 12
376*/
377float OH_ArkUI_PanGesture_GetVelocityY(const ArkUI_GestureEvent* event);
378
379/**
380* @brief Obtains the relative offset of a pan gesture along the x-axis.
381*
382* @param event Indicates the pointer to the gesture event.
383* @return Returns the relative offset of the gesture along the x-axis, in px.
384* @since 12
385*/
386float OH_ArkUI_PanGesture_GetOffsetX(const ArkUI_GestureEvent* event);
387
388/**
389* @brief Obtains the relative offset of a pan gesture along the y-axis.
390*
391* @param event Indicates the pointer to the gesture event.
392* @return Returns the relative offset of the gesture along the y-axis, in px.
393* @since 12
394*/
395float OH_ArkUI_PanGesture_GetOffsetY(const ArkUI_GestureEvent* event);
396
397/**
398* @brief Obtains the angle information of the swipe gesture.
399*
400* After a swipe gesture is recognized, a line connecting the two fingers is identified as the initial line.
401* As the fingers swipe, the line between the fingers rotates. \n
402* Based on the coordinates of the initial line's and current line's end points, the arc tangent function is used to
403* calculate the respective included angle of the points relative to the horizontal direction \n
404* by using the following formula: Rotation angle = arctan2(cy2-cy1,cx2-cx1) - arctan2(y2-y1,x2-x1). \n
405* The initial line is used as the coordinate system. Values from 0 to 180 degrees represent clockwise rotation,
406* while values from –180 to 0 degrees represent counterclockwise rotation. \n
407*
408* @param event Indicates the pointer to the gesture event.
409* @return Returns the angle of the swipe gesture, which is the result obtained based on the aforementioned formula.
410* @since 12
411*/
412float OH_ArkUI_SwipeGesture_GetAngle(const ArkUI_GestureEvent* event);
413
414/**
415* @brief Obtains the average velocity of all fingers used in the swipe gesture.
416*
417* @param event Indicates the pointer to the gesture event.
418* @return Returns the average velocity of all fingers used in the swipe gesture, in px/s.
419* @since 12
420*/
421float OH_ArkUI_SwipeGesture_GetVelocity(const ArkUI_GestureEvent* event);
422
423/**
424* @brief Obtains the angle information of a rotation gesture.
425*
426* @param event Indicates the pointer to the gesture event.
427* @return Returns the rotation angle.
428* @since 12
429*/
430float OH_ArkUI_RotationGesture_GetAngle(const ArkUI_GestureEvent* event);
431
432/**
433* @brief Obtains the scale ratio of a pinch gesture.
434*
435* @param event Indicates the pointer to the gesture event.
436* @return Returns the scale ratio.
437* @since 12
438*/
439float OH_ArkUI_PinchGesture_GetScale(const ArkUI_GestureEvent* event);
440
441/**
442* @brief Obtains the X coordinate of the center of the pinch gesture, in vp,
443* relative to the upper left corner of the current component.
444*
445* @param event Indicates the pointer to the gesture event.
446* @return Returns the X coordinate of the center of the pinch gesture, in vp,
447* relative to the upper left corner of the current component.
448* @since 12
449*/
450float OH_ArkUI_PinchGesture_GetCenterX(const ArkUI_GestureEvent* event);
451
452/**
453* @brief Obtains the Y coordinate of the center of the pinch gesture, in vp,
454* relative to the upper left corner of the current component.
455*
456* @param event Indicates the pointer to the gesture event.
457* @return Returns the Y coordinate of the center of the pinch gesture, in vp,
458* relative to the upper left corner of the current component.
459* @since 12
460*/
461float OH_ArkUI_PinchGesture_GetCenterY(const ArkUI_GestureEvent* event);
462
463/**
464* @brief Get the ARKUI component bound to the gesture.
465*
466* @param event gesture event.
467* @return ARKUI component bound to the gesture.If Null is returned, it means event is an invalid value.
468* @since 12
469*/
470ArkUI_NodeHandle OH_ArkUI_GestureEvent_GetNode(const ArkUI_GestureEvent* event);
471
472/**
473* @brief Obtains information about a gesture response chain.
474*
475* @param event Indicates the pointer to the gesture interruption information.
476* @param responseChain Indicates the pointer to an array of gesture recognizers on the response chain.
477* @param count Indicates the pointer to the number of gesture recognizers on the response chain.
478* @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success.
479*         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs.
480* @since 12
481*/
482int32_t OH_ArkUI_GetResponseRecognizersFromInterruptInfo(const ArkUI_GestureInterruptInfo* event,
483    ArkUI_GestureRecognizerHandleArray* responseChain, int32_t* count);
484
485/**
486* @brief Sets the enabled state of a gesture recognizer.
487*
488* @param recognizer Indicates the pointer to a gesture recognizer.
489* @param enabled Indicates the enabled state.
490* @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success.
491*         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs.
492* @since 12
493*/
494int32_t OH_ArkUI_SetGestureRecognizerEnabled(ArkUI_GestureRecognizer* recognizer, bool enabled);
495
496/**
497* @brief Obtains the enabled state of a gesture recognizer.
498*
499* @param recognizer Indicates the pointer to a gesture recognizer.
500* @return Returns <b>true</b> if the gesture recognizer is enabled.
501*         Returns <b>false</b> if the gesture recognizer is disabled.
502* @since 12
503*/
504bool OH_ArkUI_GetGestureRecognizerEnabled(ArkUI_GestureRecognizer* recognizer);
505
506/**
507* @brief Obtains the state of a gesture recognizer.
508*
509* @param recognizer Indicates the pointer to a gesture recognizer.
510* @param state Indicates the pointer to the state of the gesture recognizer.
511* @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success.
512*         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs.
513* @since 12
514*/
515int32_t OH_ArkUI_GetGestureRecognizerState(ArkUI_GestureRecognizer* recognizer, ArkUI_GestureRecognizerState* state);
516
517/**
518* @brief Obtains the information about a gesture event target.
519*
520* @param recognizer Indicates the pointer to a gesture recognizer.
521* @param info Indicates the information about a gesture event target.
522* @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success.
523*         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs.
524* @since 12
525*/
526int32_t OH_ArkUI_GetGestureEventTargetInfo(ArkUI_GestureRecognizer* recognizer, ArkUI_GestureEventTargetInfo** info);
527
528/**
529* @brief Obtains whether this scroll container is scrolled to the top.
530*
531* @param info Indicates the information about a gesture event target.
532* @param ret Indicates whether the scroll container is scrolled to the top.
533* @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success.
534*         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs.
535*         Returns {@link ARKUI_ERROR_CODE_NON_SCROLLABLE_CONTAINER} if the component is not a scroll container.
536* @since 12
537*/
538int32_t OH_ArkUI_GestureEventTargetInfo_IsScrollBegin(ArkUI_GestureEventTargetInfo* info, bool* ret);
539
540/**
541* @brief Obtains whether this scroll container is scrolled to the bottom.
542*
543* @param info Indicates the information about a gesture event target.
544* @param ret Indicates whether the scroll container is scrolled to the bottom.
545* @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success.
546*         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs.
547*         Returns {@link ARKUI_ERROR_CODE_NON_SCROLLABLE_CONTAINER} if the component is not a scroll container.
548* @since 12
549*/
550int32_t OH_ArkUI_GestureEventTargetInfo_IsScrollEnd(ArkUI_GestureEventTargetInfo* info, bool* ret);
551
552/**
553* @brief Obtains the direction of a pan gesture.
554*
555* @param recognizer Indicates the pointer to a gesture recognizer.
556* @param directionMask Indicates the pan direction.
557* @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success.
558*         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs.
559* @since 12
560*/
561int32_t OH_ArkUI_GetPanGestureDirectionMask(ArkUI_GestureRecognizer* recognizer,
562    ArkUI_GestureDirectionMask* directionMask);
563
564/**
565* @brief Obtains whether a gesture is a built-in gesture.
566*
567* @param recognizer Indicates the pointer to a gesture recognizer.
568* @return Returns <b>true</b> if the gesture is a built-in gesture; returns <b>false</b> otherwise.
569* @since 12
570*/
571bool OH_ArkUI_IsBuiltInGesture(ArkUI_GestureRecognizer* recognizer);
572
573/**
574* @brief Obtains the tag of a gesture recognizer.
575*
576* @param recognizer Indicates the pointer to a gesture recognizer.
577* @param buffer Indicates the buffer.
578* @param bufferSize Indicates the buffer size.
579* @param result Indicates the length of the string to be written to the buffer.
580* @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success.
581*         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs.
582*         Returns {@link ARKUI_ERROR_CODE_BUFFER_SIZE_NOT_ENOUGH} if the buffer is not large enough.
583* @since 12
584*/
585int32_t OH_ArkUI_GetGestureTag(ArkUI_GestureRecognizer* recognizer, char* buffer, int32_t bufferSize, int32_t* result);
586
587/**
588* @brief Obtains the ID of the component linked to a gesture recognizer.
589*
590* @param recognizer Indicates the pointer to a gesture recognizer.
591* @param nodeId Indicates the component ID.
592* @param size Indicates the buffer size.
593* @param result Indicates the length of the string to be written to the buffer.
594* @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success.
595*         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs.
596*         Returns {@link ARKUI_ERROR_CODE_BUFFER_SIZE_NOT_ENOUGH} if the buffer is not large enough.
597* @since 12
598*/
599int32_t OH_ArkUI_GetGestureBindNodeId(ArkUI_GestureRecognizer* recognizer, char* nodeId, int32_t size,
600    int32_t* result);
601
602/**
603* @brief Obtains whether a gesture recognizer is valid.
604*
605* @param recognizer Indicates the pointer to a gesture recognizer.
606* @return Returns <b>true</b> if the gesture recognizer is valid.
607*         Returns <b>false</b> if the gesture recognizer is invalid.
608* @since 12
609*/
610bool OH_ArkUI_IsGestureRecognizerValid(ArkUI_GestureRecognizer* recognizer);
611
612/**
613* @brief Obtains custom data in the parallel internal gesture event.
614*
615* @param event Indicates the pointer to a parallel internal gesture event.
616* @return Returns the pointer to custom data.
617* @since 12
618*/
619void* OH_ArkUI_ParallelInnerGestureEvent_GetUserData(ArkUI_ParallelInnerGestureEvent* event);
620
621/**
622* @brief Obtains the current gesture recognizer in a parallel internal gesture event.
623*
624* @param event Indicates the pointer to a parallel internal gesture event.
625* @return Returns the pointer to the current gesture recognizer.
626* @since 12
627*/
628ArkUI_GestureRecognizer* OH_ArkUI_ParallelInnerGestureEvent_GetCurrentRecognizer(
629    ArkUI_ParallelInnerGestureEvent* event);
630
631/**
632* @brief Obtains the conflicting gesture recognizers in a parallel internal gesture event.
633*
634* @param event Indicates the pointer to a parallel internal gesture event.
635* @param array Indicates the pointer to the array of conflicting gesture recognizers.
636* @param size Indicates the size of the array of conflicting gesture recognizers.
637* @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success.
638*         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs.
639* @since 12
640*/
641int32_t OH_ArkUI_ParallelInnerGestureEvent_GetConflictRecognizers(ArkUI_ParallelInnerGestureEvent* event,
642    ArkUI_GestureRecognizerHandleArray* array, int32_t* size);
643
644/**
645* @brief Sets a callback function for notifying gesture recognizer destruction.
646*
647* @param recognizer Indicates the pointer to a gesture recognizer.
648* @param callback Indicates the callback function for notifying gesture recognizer destruction.
649* @param userData Indicates the custom data.
650* @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success.
651*         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs.
652*/
653int32_t OH_ArkUI_SetArkUIGestureRecognizerDisposeNotify(ArkUI_GestureRecognizer* recognizer,
654    ArkUI_GestureRecognizerDisposeNotifyCallback callback, void* userData);
655
656/**
657 * @brief Defines the gesture APIs.
658 *
659 * @since 12
660 */
661typedef struct {
662    /** The struct version is 1. */
663    int32_t version;
664
665    /**
666    * @brief Creates a tap gesture.
667    *
668    *        1. This API is used to trigger a tap gesture with one, two, or more taps. \n
669    *        2. If multi-tap is configured, the timeout interval between a lift and the next tap is 300 ms. \n
670    *        3. If the distance between the last tapped position and the current tapped position exceeds 60 vp,
671    *           gesture recognition fails. \n
672    *        4. If the value is greater than 1, the tap gesture will fail to be recognized when the number of fingers
673    *           touching the screen within 300 ms of the first finger touch is less than the required number, \n
674    *           or when the number of fingers lifted from the screen within 300 ms of the first finger's being lifted
675    *           is less than the required number. \n
676    *        5. When the number of fingers touching the screen exceeds the set value, the gesture can be recognized. \n
677    *
678    * @param countNum Indicates the number of consecutive taps. If the value is less than 1 or is not set,
679    *        the default value <b>1</b> is used.
680    * @param fingersNum Indicates the number of fingers required to trigger a tap. The value ranges
681    *        from 1 to 10. If the value is less than 1 or is not set, the default value <b>1</b> is used.
682    * @return Returns the pointer to the created gesture.
683    */
684    ArkUI_GestureRecognizer* (*createTapGesture)(int32_t countNum, int32_t fingersNum);
685
686    /**
687    * @brief Creates a long press gesture.
688    *
689    *        1. This API is used to trigger a long press gesture, which requires one or more fingers with a minimum
690    *           The value ranges 500 ms hold-down time. \n
691    *        2. In components that support drag actions by default, such as <b><Text></b>, <b><TextInput></b>,
692    *           <b><TextArea></b>, <b><Hyperlink></b>, <b><Image></b>, and <b>RichEditor></b>, the long press gesture \n
693    *           may conflict with the drag action. If this occurs, they are handled as follows: \n
694    *           If the minimum duration of the long press gesture is less than 500 ms, the long press gesture receives
695    *           a higher response priority than the drag action. \n
696    *           If the minimum duration of the long press gesture is greater than or equal to 500 ms,
697    *           the drag action receives a higher response priority than the long press gesture. \n
698    *        3. If a finger moves more than 15 px after being pressed, the gesture recognition fails. \n
699    *
700    * @param fingersNum Indicates the minimum number of fingers to trigger a long press gesture.
701    *        The value ranges from 1 to 10.
702    * @param repeatResult Indicates whether to continuously trigger the event callback.
703    * @param durationNum Indicates the minimum hold-down time, in ms.
704    *        If the value is less than or equal to 0, the default value <b>500</b> is used.
705    * @return Returns the pointer to the created gesture.
706    */
707    ArkUI_GestureRecognizer* (*createLongPressGesture)(int32_t fingersNum, bool repeatResult, int32_t durationNum);
708
709    /**
710    * @brief Creates a pan gesture.
711    *
712    *        1. This API is used to trigger a pan gesture when the movement distance of a finger on the screen exceeds
713    *           the minimum value. \n
714    *        2. If a pan gesture and a tab swipe occur at the same time, set <b>distanceNum</b> to <b>1</b>
715    *           so that the gesture can be more easily recognized. \n
716    *
717    * @param fingersNum Indicates the minimum number of fingers to trigger a pan gesture. The value ranges from 1 to 10.
718    *        If the value is less than 1 or is not set, the default value <b>1</b> is used.
719    * @param directions Indicates the pan direction. The value supports the AND (&amp;) and OR (\|) operations.
720    * @param distanceNum Indicates the minimum pan distance to trigger the gesture, in vp. If this parameter is
721    *        set to a value less than or equal to 0, the default value <b>5</b> is used.
722    * @return Returns the pointer to the created gesture.
723    */
724    ArkUI_GestureRecognizer* (*createPanGesture)(
725        int32_t fingersNum, ArkUI_GestureDirectionMask directions, double distanceNum);
726
727    /**
728    * @brief Creates a pinch gesture.
729    *
730    *        1. This API is used to trigger a pinch gesture, which requires two to five fingers with a minimum 5 vp
731    *           distance between the fingers. \n
732    *        2. While more fingers than the minimum number can be pressed to trigger the gesture, only the first
733    *           fingers of the minimum number participate in gesture calculation. \n
734    *
735    * @param fingersNum Indicates the minimum number of fingers to trigger a pinch. The value ranges from 2 to 5.
736    *        Default value: <b>2</b>
737    * @param distanceNum Indicates the minimum recognition distance, in px. If this parameter is set to a value less
738    *        than or equal to 0, the default value <b>5</b> is used.
739    * @return Returns the pointer to the created gesture.
740    */
741    ArkUI_GestureRecognizer* (*createPinchGesture)(int32_t fingersNum, double distanceNum);
742
743    /**
744    * @brief Creates a rotation gesture.
745    *
746    *        1. This API is used to trigger a rotation gesture, which requires two to five fingers with a
747    *           minimum 1-degree rotation angle. \n
748    *        2. While more fingers than the minimum number can be pressed to trigger the gesture, only the first
749    *           two fingers participate in gesture calculation. \n
750    *
751    * @param fingersNum Indicates the minimum number of fingers to trigger a rotation. The value ranges from 2 to 5.
752    *        Default value: <b>2</b>
753    * @param angleNum Indicates the minimum degree that can trigger the rotation gesture. Default value: <b>1</b>
754    *        If this parameter is set to a value less than or equal to 0 or greater than 360,
755    *        the default value <b>1</b> is used.
756    * @return Returns the pointer to the created gesture.
757    */
758    ArkUI_GestureRecognizer* (*createRotationGesture)(int32_t fingersNum, double angleNum);
759
760    /**
761    * @brief Creates a swipe gesture.
762    *
763    *        This API is used to implement a swipe gesture, which can be recognized when the swipe speed is 100
764    *        vp/s or higher. \n
765    *
766    * @param fingersNum Indicates the minimum number of fingers to trigger a swipe gesture.
767    *        The value ranges from 1 to 10.
768    * @param directions Indicates the swipe direction.
769    * @param speedNum Indicates the minimum speed of the swipe gesture, in px/s.
770    *        If this parameter is set to a value less than or equal to 0, the default value <b>100</b> is used.
771    * @return Returns the pointer to the created gesture.
772    */
773    ArkUI_GestureRecognizer* (*createSwipeGesture)(
774        int32_t fingersNum, ArkUI_GestureDirectionMask directions, double speedNum);
775
776    /**
777    * @brief Creates a gesture group.
778    *
779    * @param gestureMode Indicates the gesture group mode.
780    * @return Returns the pointer to the created gesture group.
781    */
782    ArkUI_GestureRecognizer* (*createGroupGesture)(ArkUI_GroupGestureMode gestureMode);
783
784    /**
785    * @brief Disposes a gesture to release resources.
786    *
787    * @param recognizer Indicates the pointer to the gesture to dispose.
788    */
789    void (*dispose)(ArkUI_GestureRecognizer* recognizer);
790
791    /**
792    * @brief Adds a gesture to a gesture group.
793    *
794    * @param group Indicates the pointer to the gesture group.
795    * @param child Indicates the gesture to be added to the gesture group.
796    * @return Returns <b>0</b> if success.
797    *         Returns <b>401</b> if a parameter exception occurs. Returns 401 if a parameter exception occurs.
798    */
799    int32_t (*addChildGesture)(ArkUI_GestureRecognizer* group, ArkUI_GestureRecognizer* child);
800
801    /**
802    * @brief Removes a gesture to a gesture group.
803    *
804    * @param group Indicates the pointer to the gesture group.
805    * @param child Indicates the gesture to be removed to the gesture group.
806    * @return Returns <b>0</b> if success.
807    *         Returns <b>401</b> if a parameter exception occurs.
808    */
809    int32_t (*removeChildGesture)(ArkUI_GestureRecognizer* group, ArkUI_GestureRecognizer* child);
810
811    /**
812    * @brief Registers a callback for gestures.
813    *
814    * @param recognizer Indicates the pointer to the gesture recognizer.
815    * @param actionTypeMask Indicates the set of gesture event types. Multiple callbacks can be registered at once,
816    *        with the callback event types distinguished in the callbacks.
817    *        Example: actionTypeMask = GESTURE_EVENT_ACTION_ACCEPT | GESTURE_EVENT_ACTION_UPDATE;
818    * @param extraParams Indicates the context passed in the <b>targetReceiver</b> callback.
819    * @param targetReceiver Indicates the callback to register for processing the gesture event types.
820    *        <b>event</b> indicates the gesture callback data.
821    * @return Returns <b>0</b> if success.
822    *         Returns <b>401</b> if a parameter exception occurs.
823    */
824    int32_t (*setGestureEventTarget)(
825        ArkUI_GestureRecognizer* recognizer, ArkUI_GestureEventActionTypeMask actionTypeMask, void* extraParams,
826        void (*targetReceiver)(ArkUI_GestureEvent* event, void* extraParams));
827
828    /**
829    * @brief Adds a gesture to a UI component.
830    *
831    * @param node Indicates the UI component to which you want to add the gesture.
832    * @param recognizer Indicates the gesture to be added to the UI component.
833    * @param mode Indicates the gesture event mode. Available options are <b>NORMAL_GESTURE</b>,
834    *        <b>PARALLEL_GESTURE</b>, and <b>PRIORITY_GESTURE</b>.
835    * @param mask Indicates the gesture masking mode.
836    * @return Returns <b>0</b> if success.
837    *         Returns <b>401</b> if a parameter exception occurs.
838    */
839    int32_t (*addGestureToNode)(
840        ArkUI_NodeHandle node, ArkUI_GestureRecognizer* recognizer, ArkUI_GesturePriority mode, ArkUI_GestureMask mask);
841
842    /**
843    * @brief Removes a gesture from a node.
844    *
845    * @param node Indicates the node from which you want to remove the gesture.
846    * @param recognizer Indicates the gesture to be removed.
847    * @return Returns <b>0</b> if success.
848    * Returns <b>401</b> if a parameter exception occurs.
849    */
850    int32_t (*removeGestureFromNode)(ArkUI_NodeHandle node, ArkUI_GestureRecognizer* recognizer);
851
852    /**
853    * @brief Sets a gesture interruption callback for a node.
854    *
855    * @param node Indicates the node for which you want to set a gesture interruption callback.
856    * @param interrupter Indicates the gesture interruption callback to set.
857    *        <b>info</b> indicates the gesture interruption data. If <b>interrupter</b> returns
858    *        <b>GESTURE_INTERRUPT_RESULT_CONTINUE</b>, the gesture recognition process continues. If it returns
859    *        <b>GESTURE_INTERRUPT_RESULT_REJECT</b>, the gesture recognition process is paused.
860    * @return Returns <b>0</b> if success.
861    * Returns <b>401</b> if a parameter exception occurs.
862    */
863    int32_t (*setGestureInterrupterToNode)(
864        ArkUI_NodeHandle node, ArkUI_GestureInterruptResult (*interrupter)(ArkUI_GestureInterruptInfo* info));
865
866    /**
867    * @brief Obtains the type of a gesture.
868    *
869    * @param recognizer Indicates the pointer to the gesture.
870    * @return Returns the gesture type.
871    */
872    ArkUI_GestureRecognizerType (*getGestureType)(ArkUI_GestureRecognizer* recognizer);
873
874    /**
875    * @brief Sets the callback function for a parallel internal gesture event.
876    *
877    * @param node Indicates the ArkUI node for which the callback of a parallel internal gesture event is to be set.
878    * @param userData Indicates the custom data.
879    * @param parallelInnerGesture Indicates the parallel internal gesture event. <b>event</b> returns the data of the
880    *        parallel internal gesture event; <b>parallelInnerGesture</b> returns the pointer to the gesture recognizer
881    *        that requires parallel recognition.
882    * @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success.
883    *         Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs.
884    */
885    int32_t (*setInnerGestureParallelTo)(
886        ArkUI_NodeHandle node, void* userData, ArkUI_GestureRecognizer* (*parallelInnerGesture)(
887            ArkUI_ParallelInnerGestureEvent* event));
888
889    /**
890    * @brief Creates a tap gesture that is subject to distance restrictions.
891    *
892    *        1. This API is used to trigger a tap gesture with one, two, or more taps. \n
893    *        2. If multi-tap is configured, the timeout interval between a lift and the next tap is 300 ms. \n
894    *        3. If the distance between the last tapped position and the current tapped position exceeds 60 vp,
895    *           gesture recognition fails. \n
896    *        4. If the value is greater than 1, the tap gesture will fail to be recognized when the number of fingers
897    *           touching the screen within 300 ms of the first finger touch is less than the required number,
898    *           or when the number of fingers lifted from the screen within 300 ms of the first finger's being lifted
899    *           is less than the required number. \n
900    *        5. When the number of fingers touching the screen exceeds the set value, the gesture can be recognized. \n
901    *        6. If the finger moves beyond the preset distance limit, gesture recognition fails. \n
902    *
903    * @param countNum Indicates the number of consecutive taps. If the value is less than 1 or is not set, the default
904    *        value <b>1</b> is used.
905    * @param fingersNum Indicates the number of fingers required to trigger a tap. The value ranges from 1 to 10.
906    *        If the value is less than 1 or is not set, the default value <b>1</b> is used.
907    * @param distanceThreshold Indicates the allowed moving distance of a finger.
908    *        If the value is less than 0 or is not set, it will be converted to the default value of infinity.
909    * @return Returns the pointer to the created gesture.
910    */
911    ArkUI_GestureRecognizer* (*createTapGestureWithDistanceThreshold)(
912        int32_t countNum, int32_t fingersNum, double distanceThreshold);
913} ArkUI_NativeGestureAPI_1;
914
915#ifdef __cplusplus
916};
917#endif
918
919#endif // ARKUI_NATIVE_GESTTURE_H
920/** @} */
921