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 44 extern "C" { 45 #endif 46 47 /** 48 * @brief Defines a gesture recognizer. 49 * 50 * @since 12 51 */ 52 typedef struct ArkUI_GestureRecognizer ArkUI_GestureRecognizer; 53 54 /** 55 * @brief Defines the gesture interruption information. 56 * 57 * @since 12 58 */ 59 typedef struct ArkUI_GestureInterruptInfo ArkUI_GestureInterruptInfo; 60 61 /** 62 * @brief Defines the gesture event. 63 * 64 * @since 12 65 */ 66 typedef struct ArkUI_GestureEvent ArkUI_GestureEvent; 67 68 /** 69 * @brief Enumerates gesture event types. 70 * 71 * @since 12 72 */ 73 typedef 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 */ 94 typedef uint32_t ArkUI_GestureEventActionTypeMask; 95 96 /** 97 * @brief Enumerates gesture event modes. 98 * 99 * @since 12 100 */ 101 typedef 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 */ 117 typedef 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 */ 137 typedef 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 */ 171 typedef uint32_t ArkUI_GestureDirectionMask; 172 173 /** 174 * @brief Enumerates gesture masking modes. 175 * 176 * @since 12 177 */ 178 typedef 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 */ 191 typedef 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 */ 219 typedef 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 */ 232 typedef 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 */ 257 typedef ArkUI_GestureRecognizer* ArkUI_GestureRecognizerHandle; 258 259 /** 260 * @brief Defines the gesture recognizer handle array. 261 * 262 * @since 12 263 */ 264 typedef 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 */ 271 typedef struct ArkUI_GestureEventTargetInfo ArkUI_GestureEventTargetInfo; 272 273 /** 274 * @brief Defines a parallel internal gesture event. 275 * 276 * @since 12 277 */ 278 typedef struct ArkUI_ParallelInnerGestureEvent ArkUI_ParallelInnerGestureEvent; 279 280 /** 281 * @brief Defines a touch recognizer. 282 * 283 * @since 15 284 */ 285 typedef struct ArkUI_TouchRecognizer ArkUI_TouchRecognizer; 286 287 /** 288 * @brief Defines a touch recognizer handle. 289 * 290 * @since 15 291 */ 292 typedef ArkUI_TouchRecognizer* ArkUI_TouchRecognizerHandle; 293 294 /** 295 * @brief Defines an array of touch recognizer handle. 296 * 297 * @since 15 298 */ 299 typedef ArkUI_TouchRecognizerHandle* ArkUI_TouchRecognizerHandleArray; 300 301 /** 302 * @brief Defines a callback function for notifying gesture recognizer destruction. 303 * @since 12 304 */ 305 typedef void (*ArkUI_GestureRecognizerDisposeNotifyCallback)(ArkUI_GestureRecognizer* recognizer, void* userData); 306 307 /** 308 * @brief Checks whether a gesture is a built-in gesture of the component. 309 * 310 * @param event Indicates the pointer to the gesture interruption information. 311 * @return Returns <b>true</b> if the gesture is a built-in gesture; returns <b>false</b> otherwise. 312 313 * @since 12 314 */ 315 bool OH_ArkUI_GestureInterruptInfo_GetSystemFlag(const ArkUI_GestureInterruptInfo* event); 316 317 /** 318 * @brief Obtains the pointer to interrupted gesture recognizer. 319 * 320 * @param event Indicates the pointer to the gesture interruption information. 321 * @return Returns the pointer to interrupted gesture recognizer. 322 * @since 12 323 */ 324 ArkUI_GestureRecognizer* OH_ArkUI_GestureInterruptInfo_GetRecognizer(const ArkUI_GestureInterruptInfo* event); 325 326 /** 327 * @brief Obtains the pointer to the interrupted gesture event. 328 * 329 * @param event Indicates the pointer to the gesture interruption information. 330 * @return Returns the pointer to the interrupted gesture event. 331 * @since 12 332 */ 333 ArkUI_GestureEvent* OH_ArkUI_GestureInterruptInfo_GetGestureEvent(const ArkUI_GestureInterruptInfo* event); 334 335 /** 336 * @brief Obtains the type of the system gesture to trigger. 337 * 338 * @param event Indicates the pointer to the gesture interruption information. 339 * @return Returns the type of the system gesture to trigger. If the gesture to trigger is not a system gesture, 340 * <b>-1</b> is returned. 341 * @since 12 342 */ 343 int32_t OH_ArkUI_GestureInterruptInfo_GetSystemRecognizerType(const ArkUI_GestureInterruptInfo* event); 344 345 /** 346 * @brief Get the touch recognizer handles from the gesture interrupt info. 347 * 348 * @param info Indicates the pointer to a gesture interrupt info. 349 * @param recognizers Indicates the pointer to an array of touch recognizer handles. 350 * @param size Indicates the size of recognizers. 351 * @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success. 352 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs. 353 * @since 15 354 */ 355 int32_t OH_ArkUI_GestureInterruptInfo_GetTouchRecognizers(const ArkUI_GestureInterruptInfo* info, 356 ArkUI_TouchRecognizerHandleArray* recognizers, int32_t* size); 357 358 /** 359 * @brief Get component object of the specific touch recognizer. 360 * 361 * @param recognizer Indicates the pointer to the TouchRecognizer. 362 * @return Get component object of the specific touch recognizer. 363 * @since 15 364 */ 365 ArkUI_NodeHandle OH_ArkUI_TouchRecognizer_GetNodeHandle(const ArkUI_TouchRecognizerHandle recognizer); 366 367 /** 368 * @brief Send touch-cancel event to the touch recognizer in a gesture interruption callback. 369 * 370 * @param recognizer Indicates the touch recognizer handle. 371 * @param info Indicates the pointer to a gesture interrupt info. 372 * @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success. 373 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs. 374 * @since 15 375 */ 376 int32_t OH_ArkUI_TouchRecognizer_CancelTouch(ArkUI_TouchRecognizerHandle recognizer, ArkUI_GestureInterruptInfo* info); 377 378 /** 379 * @brief Obtains the gesture event type. 380 * 381 * @param event Indicates the pointer to the gesture event. 382 * @return Returns the gesture event type. 383 * @since 12 384 */ 385 ArkUI_GestureEventActionType OH_ArkUI_GestureEvent_GetActionType(const ArkUI_GestureEvent* event); 386 387 /** 388 * @brief Obtains gesture input. 389 * 390 * @param event Indicates the pointer to the gesture event. 391 * @return Returns the pointer to the input event of the gesture event. 392 * @since 12 393 */ 394 const ArkUI_UIInputEvent* OH_ArkUI_GestureEvent_GetRawInputEvent(const ArkUI_GestureEvent* event); 395 396 /** 397 * @brief Obtains the number of times that a long press gesture is triggered periodically. 398 * 399 * @param event Indicates the pointer to the gesture event. 400 * @return Returns the number of times that the long press gesture is triggered periodically. 401 * @since 12 402 */ 403 int32_t OH_ArkUI_LongPress_GetRepeatCount(const ArkUI_GestureEvent* event); 404 405 /** 406 * @brief Obtains the velocity of a pan gesture along the main axis. 407 * 408 * @param event Indicates the pointer to the gesture event. 409 * @return Returns the velocity of the pan gesture along the main axis, in px/s. 410 * The value is the square root of the sum of the squares of the velocity on the x-axis and y-axis. 411 * @since 12 412 */ 413 float OH_ArkUI_PanGesture_GetVelocity(const ArkUI_GestureEvent* event); 414 415 /** 416 * @brief Obtains the velocity of a pan gesture along the x-axis. 417 * 418 * @param event Indicates the pointer to the gesture event. 419 * @return Returns the velocity of the pan gesture along the x-axis, in px/s. 420 * @since 12 421 */ 422 float OH_ArkUI_PanGesture_GetVelocityX(const ArkUI_GestureEvent* event); 423 424 /** 425 * @brief Obtains the velocity of a pan gesture along the y-axis. 426 * 427 * @param event Indicates the pointer to the gesture event. 428 * @return Returns the velocity of the pan gesture along the y-axis, in px/s. 429 * @since 12 430 */ 431 float OH_ArkUI_PanGesture_GetVelocityY(const ArkUI_GestureEvent* event); 432 433 /** 434 * @brief Obtains the relative offset of a pan gesture along the x-axis. 435 * 436 * @param event Indicates the pointer to the gesture event. 437 * @return Returns the relative offset of the gesture along the x-axis, in px. 438 * @since 12 439 */ 440 float OH_ArkUI_PanGesture_GetOffsetX(const ArkUI_GestureEvent* event); 441 442 /** 443 * @brief Obtains the relative offset of a pan gesture along the y-axis. 444 * 445 * @param event Indicates the pointer to the gesture event. 446 * @return Returns the relative offset of the gesture along the y-axis, in px. 447 * @since 12 448 */ 449 float OH_ArkUI_PanGesture_GetOffsetY(const ArkUI_GestureEvent* event); 450 451 /** 452 * @brief Obtains the angle information of the swipe gesture. 453 * 454 * After a swipe gesture is recognized, a line connecting the two fingers is identified as the initial line. 455 * As the fingers swipe, the line between the fingers rotates. \n 456 * Based on the coordinates of the initial line's and current line's end points, the arc tangent function is used to 457 * calculate the respective included angle of the points relative to the horizontal direction \n 458 * by using the following formula: Rotation angle = arctan2(cy2-cy1,cx2-cx1) - arctan2(y2-y1,x2-x1). \n 459 * The initial line is used as the coordinate system. Values from 0 to 180 degrees represent clockwise rotation, 460 * while values from –180 to 0 degrees represent counterclockwise rotation. \n 461 * 462 * @param event Indicates the pointer to the gesture event. 463 * @return Returns the angle of the swipe gesture, which is the result obtained based on the aforementioned formula. 464 * @since 12 465 */ 466 float OH_ArkUI_SwipeGesture_GetAngle(const ArkUI_GestureEvent* event); 467 468 /** 469 * @brief Obtains the average velocity of all fingers used in the swipe gesture. 470 * 471 * @param event Indicates the pointer to the gesture event. 472 * @return Returns the average velocity of all fingers used in the swipe gesture, in px/s. 473 * @since 12 474 */ 475 float OH_ArkUI_SwipeGesture_GetVelocity(const ArkUI_GestureEvent* event); 476 477 /** 478 * @brief Obtains the angle information of a rotation gesture. 479 * 480 * @param event Indicates the pointer to the gesture event. 481 * @return Returns the rotation angle. 482 * @since 12 483 */ 484 float OH_ArkUI_RotationGesture_GetAngle(const ArkUI_GestureEvent* event); 485 486 /** 487 * @brief Obtains the scale ratio of a pinch gesture. 488 * 489 * @param event Indicates the pointer to the gesture event. 490 * @return Returns the scale ratio. 491 * @since 12 492 */ 493 float OH_ArkUI_PinchGesture_GetScale(const ArkUI_GestureEvent* event); 494 495 /** 496 * @brief Obtains the X coordinate of the center of the pinch gesture, in vp, 497 * relative to the upper left corner of the current component. 498 * 499 * @param event Indicates the pointer to the gesture event. 500 * @return Returns the X coordinate of the center of the pinch gesture, in vp, 501 * relative to the upper left corner of the current component. 502 * @since 12 503 */ 504 float OH_ArkUI_PinchGesture_GetCenterX(const ArkUI_GestureEvent* event); 505 506 /** 507 * @brief Obtains the Y coordinate of the center of the pinch gesture, in vp, 508 * relative to the upper left corner of the current component. 509 * 510 * @param event Indicates the pointer to the gesture event. 511 * @return Returns the Y coordinate of the center of the pinch gesture, in vp, 512 * relative to the upper left corner of the current component. 513 * @since 12 514 */ 515 float OH_ArkUI_PinchGesture_GetCenterY(const ArkUI_GestureEvent* event); 516 517 /** 518 * @brief Get the ARKUI component bound to the gesture. 519 * 520 * @param event gesture event. 521 * @return ARKUI component bound to the gesture.If Null is returned, it means event is an invalid value. 522 * @since 12 523 */ 524 ArkUI_NodeHandle OH_ArkUI_GestureEvent_GetNode(const ArkUI_GestureEvent* event); 525 526 /** 527 * @brief Obtains information about a gesture response chain. 528 * 529 * @param event Indicates the pointer to the gesture interruption information. 530 * @param responseChain Indicates the pointer to an array of gesture recognizers on the response chain. 531 * @param count Indicates the pointer to the number of gesture recognizers on the response chain. 532 * @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success. 533 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs. 534 * @since 12 535 */ 536 int32_t OH_ArkUI_GetResponseRecognizersFromInterruptInfo(const ArkUI_GestureInterruptInfo* event, 537 ArkUI_GestureRecognizerHandleArray* responseChain, int32_t* count); 538 539 /** 540 * @brief Sets the enabled state of a gesture recognizer. 541 * 542 * @param recognizer Indicates the pointer to a gesture recognizer. 543 * @param enabled Indicates the enabled state. 544 * @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success. 545 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs. 546 * @since 12 547 */ 548 int32_t OH_ArkUI_SetGestureRecognizerEnabled(ArkUI_GestureRecognizer* recognizer, bool enabled); 549 550 /** 551 * @brief Sets whether to enable strict finger count checking. If this feature is enabled and the actual number of touch 552 * fingers does not match the set number, the gesture recognition fails. 553 * 554 * @param recognizer Indicates the pointer to a gesture recognizer. 555 * @param limitFingerCount Indicates whether to enable strict finger count checking. 556 * @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success. 557 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 558 * @since 15 559 */ 560 int32_t OH_ArkUI_SetGestureRecognizerLimitFingerCount(ArkUI_GestureRecognizer* recognizer, bool limitFingerCount); 561 562 /** 563 * @brief Obtains the enabled state of a gesture recognizer. 564 * 565 * @param recognizer Indicates the pointer to a gesture recognizer. 566 * @return Returns <b>true</b> if the gesture recognizer is enabled. 567 * Returns <b>false</b> if the gesture recognizer is disabled. 568 * @since 12 569 */ 570 bool OH_ArkUI_GetGestureRecognizerEnabled(ArkUI_GestureRecognizer* recognizer); 571 572 /** 573 * @brief Obtains the state of a gesture recognizer. 574 * 575 * @param recognizer Indicates the pointer to a gesture recognizer. 576 * @param state Indicates the pointer to the state of the gesture recognizer. 577 * @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success. 578 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs. 579 * @since 12 580 */ 581 int32_t OH_ArkUI_GetGestureRecognizerState(ArkUI_GestureRecognizer* recognizer, ArkUI_GestureRecognizerState* state); 582 583 /** 584 * @brief Obtains the information about a gesture event target. 585 * 586 * @param recognizer Indicates the pointer to a gesture recognizer. 587 * @param info Indicates the information about a gesture event target. 588 * @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success. 589 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs. 590 * @since 12 591 */ 592 int32_t OH_ArkUI_GetGestureEventTargetInfo(ArkUI_GestureRecognizer* recognizer, ArkUI_GestureEventTargetInfo** info); 593 594 /** 595 * @brief Obtains whether this scroll container is scrolled to the top. 596 * 597 * @param info Indicates the information about a gesture event target. 598 * @param ret Indicates whether the scroll container is scrolled to the top. 599 * @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success. 600 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs. 601 * Returns {@link ARKUI_ERROR_CODE_NON_SCROLLABLE_CONTAINER} if the component is not a scroll container. 602 * @since 12 603 */ 604 int32_t OH_ArkUI_GestureEventTargetInfo_IsScrollBegin(ArkUI_GestureEventTargetInfo* info, bool* ret); 605 606 /** 607 * @brief Obtains whether this scroll container is scrolled to the bottom. 608 * 609 * @param info Indicates the information about a gesture event target. 610 * @param ret Indicates whether the scroll container is scrolled to the bottom. 611 * @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success. 612 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs. 613 * Returns {@link ARKUI_ERROR_CODE_NON_SCROLLABLE_CONTAINER} if the component is not a scroll container. 614 * @since 12 615 */ 616 int32_t OH_ArkUI_GestureEventTargetInfo_IsScrollEnd(ArkUI_GestureEventTargetInfo* info, bool* ret); 617 618 /** 619 * @brief Obtains the direction of a pan gesture. 620 * 621 * @param recognizer Indicates the pointer to a gesture recognizer. 622 * @param directionMask Indicates the pan direction. 623 * @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success. 624 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs. 625 * @since 12 626 */ 627 int32_t OH_ArkUI_GetPanGestureDirectionMask(ArkUI_GestureRecognizer* recognizer, 628 ArkUI_GestureDirectionMask* directionMask); 629 630 /** 631 * @brief Obtains whether a gesture is a built-in gesture. 632 * 633 * @param recognizer Indicates the pointer to a gesture recognizer. 634 * @return Returns <b>true</b> if the gesture is a built-in gesture; returns <b>false</b> otherwise. 635 * @since 12 636 */ 637 bool OH_ArkUI_IsBuiltInGesture(ArkUI_GestureRecognizer* recognizer); 638 639 /** 640 * @brief Obtains the tag of a gesture recognizer. 641 * 642 * @param recognizer Indicates the pointer to a gesture recognizer. 643 * @param buffer Indicates the buffer. 644 * @param bufferSize Indicates the buffer size. 645 * @param result Indicates the length of the string to be written to the buffer. 646 * @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success. 647 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs. 648 * Returns {@link ARKUI_ERROR_CODE_BUFFER_SIZE_NOT_ENOUGH} if the buffer is not large enough. 649 * @since 12 650 */ 651 int32_t OH_ArkUI_GetGestureTag(ArkUI_GestureRecognizer* recognizer, char* buffer, int32_t bufferSize, int32_t* result); 652 653 /** 654 * @brief Obtains the ID of the component linked to a gesture recognizer. 655 * 656 * @param recognizer Indicates the pointer to a gesture recognizer. 657 * @param nodeId Indicates the component ID. 658 * @param size Indicates the buffer size. 659 * @param result Indicates the length of the string to be written to the buffer. 660 * @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success. 661 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs. 662 * Returns {@link ARKUI_ERROR_CODE_BUFFER_SIZE_NOT_ENOUGH} if the buffer is not large enough. 663 * @since 12 664 */ 665 int32_t OH_ArkUI_GetGestureBindNodeId(ArkUI_GestureRecognizer* recognizer, char* nodeId, int32_t size, 666 int32_t* result); 667 668 /** 669 * @brief Obtains whether a gesture recognizer is valid. 670 * 671 * @param recognizer Indicates the pointer to a gesture recognizer. 672 * @return Returns <b>true</b> if the gesture recognizer is valid. 673 * Returns <b>false</b> if the gesture recognizer is invalid. 674 * @since 12 675 */ 676 bool OH_ArkUI_IsGestureRecognizerValid(ArkUI_GestureRecognizer* recognizer); 677 678 /** 679 * @brief Obtains custom data in the parallel internal gesture event. 680 * 681 * @param event Indicates the pointer to a parallel internal gesture event. 682 * @return Returns the pointer to custom data. 683 * @since 12 684 */ 685 void* OH_ArkUI_ParallelInnerGestureEvent_GetUserData(ArkUI_ParallelInnerGestureEvent* event); 686 687 /** 688 * @brief Obtains the current gesture recognizer in a parallel internal gesture event. 689 * 690 * @param event Indicates the pointer to a parallel internal gesture event. 691 * @return Returns the pointer to the current gesture recognizer. 692 * @since 12 693 */ 694 ArkUI_GestureRecognizer* OH_ArkUI_ParallelInnerGestureEvent_GetCurrentRecognizer( 695 ArkUI_ParallelInnerGestureEvent* event); 696 697 /** 698 * @brief Obtains the conflicting gesture recognizers in a parallel internal gesture event. 699 * 700 * @param event Indicates the pointer to a parallel internal gesture event. 701 * @param array Indicates the pointer to the array of conflicting gesture recognizers. 702 * @param size Indicates the size of the array of conflicting gesture recognizers. 703 * @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success. 704 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs. 705 * @since 12 706 */ 707 int32_t OH_ArkUI_ParallelInnerGestureEvent_GetConflictRecognizers(ArkUI_ParallelInnerGestureEvent* event, 708 ArkUI_GestureRecognizerHandleArray* array, int32_t* size); 709 710 /** 711 * @brief Sets a callback function for notifying gesture recognizer destruction. 712 * 713 * @param recognizer Indicates the pointer to a gesture recognizer. 714 * @param callback Indicates the callback function for notifying gesture recognizer destruction. 715 * @param userData Indicates the custom data. 716 * @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success. 717 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs. 718 * @since 12 719 */ 720 int32_t OH_ArkUI_SetArkUIGestureRecognizerDisposeNotify(ArkUI_GestureRecognizer* recognizer, 721 ArkUI_GestureRecognizerDisposeNotifyCallback callback, void* userData); 722 723 /** 724 * @brief Defines the gesture APIs. 725 * 726 * @since 12 727 */ 728 typedef struct { 729 /** The struct version is 1. */ 730 int32_t version; 731 732 /** 733 * @brief Creates a tap gesture. 734 * 735 * 1. This API is used to trigger a tap gesture with one, two, or more taps. \n 736 * 2. If multi-tap is configured, the timeout interval between a lift and the next tap is 300 ms. \n 737 * 3. If the distance between the last tapped position and the current tapped position exceeds 60 vp, 738 * gesture recognition fails. \n 739 * 4. If the value is greater than 1, the tap gesture will fail to be recognized when the number of fingers 740 * touching the screen within 300 ms of the first finger touch is less than the required number, \n 741 * or when the number of fingers lifted from the screen within 300 ms of the first finger's being lifted 742 * is less than the required number. \n 743 * 5. When the number of fingers touching the screen exceeds the set value, the gesture can be recognized. \n 744 * 745 * @param countNum Indicates the number of consecutive taps. If the value is less than 1 or is not set, 746 * the default value <b>1</b> is used. 747 * @param fingersNum Indicates the number of fingers required to trigger a tap. The value ranges 748 * from 1 to 10. If the value is less than 1 or is not set, the default value <b>1</b> is used. 749 * @return Returns the pointer to the created gesture. 750 */ 751 ArkUI_GestureRecognizer* (*createTapGesture)(int32_t countNum, int32_t fingersNum); 752 753 /** 754 * @brief Creates a long press gesture. 755 * 756 * 1. This API is used to trigger a long press gesture, which requires one or more fingers with a minimum 757 * The value ranges 500 ms hold-down time. \n 758 * 2. In components that support drag actions by default, such as <b><Text></b>, <b><TextInput></b>, 759 * <b><TextArea></b>, <b><Hyperlink></b>, <b><Image></b>, and <b>RichEditor></b>, the long press gesture \n 760 * may conflict with the drag action. If this occurs, they are handled as follows: \n 761 * If the minimum duration of the long press gesture is less than 500 ms, the long press gesture receives 762 * a higher response priority than the drag action. \n 763 * If the minimum duration of the long press gesture is greater than or equal to 500 ms, 764 * the drag action receives a higher response priority than the long press gesture. \n 765 * 3. If a finger moves more than 15 px after being pressed, the gesture recognition fails. \n 766 * 767 * @param fingersNum Indicates the minimum number of fingers to trigger a long press gesture. 768 * The value ranges from 1 to 10. 769 * @param repeatResult Indicates whether to continuously trigger the event callback. 770 * @param durationNum Indicates the minimum hold-down time, in ms. 771 * If the value is less than or equal to 0, the default value <b>500</b> is used. 772 * @return Returns the pointer to the created gesture. 773 */ 774 ArkUI_GestureRecognizer* (*createLongPressGesture)(int32_t fingersNum, bool repeatResult, int32_t durationNum); 775 776 /** 777 * @brief Creates a pan gesture. 778 * 779 * 1. This API is used to trigger a pan gesture when the movement distance of a finger on the screen exceeds 780 * the minimum value. \n 781 * 2. If a pan gesture and a tab swipe occur at the same time, set <b>distanceNum</b> to <b>1</b> 782 * so that the gesture can be more easily recognized. \n 783 * 784 * @param fingersNum Indicates the minimum number of fingers to trigger a pan gesture. The value ranges from 1 to 10. 785 * If the value is less than 1 or is not set, the default value <b>1</b> is used. 786 * @param directions Indicates the pan direction. The value supports the AND (&) and OR (\|) operations. 787 * @param distanceNum Indicates the minimum pan distance to trigger the gesture, in vp. If this parameter is 788 * set to a value less than or equal to 0, the default value <b>5</b> is used. 789 * @return Returns the pointer to the created gesture. 790 */ 791 ArkUI_GestureRecognizer* (*createPanGesture)( 792 int32_t fingersNum, ArkUI_GestureDirectionMask directions, double distanceNum); 793 794 /** 795 * @brief Creates a pinch gesture. 796 * 797 * 1. This API is used to trigger a pinch gesture, which requires two to five fingers with a minimum 5 vp 798 * distance between the fingers. \n 799 * 2. While more fingers than the minimum number can be pressed to trigger the gesture, only the first 800 * fingers of the minimum number participate in gesture calculation. \n 801 * 802 * @param fingersNum Indicates the minimum number of fingers to trigger a pinch. The value ranges from 2 to 5. 803 * Default value: <b>2</b> 804 * @param distanceNum Indicates the minimum recognition distance, in px. If this parameter is set to a value less 805 * than or equal to 0, the default value <b>5</b> is used. 806 * @return Returns the pointer to the created gesture. 807 */ 808 ArkUI_GestureRecognizer* (*createPinchGesture)(int32_t fingersNum, double distanceNum); 809 810 /** 811 * @brief Creates a rotation gesture. 812 * 813 * 1. This API is used to trigger a rotation gesture, which requires two to five fingers with a 814 * minimum 1-degree rotation angle. \n 815 * 2. While more fingers than the minimum number can be pressed to trigger the gesture, only the first 816 * two fingers participate in gesture calculation. \n 817 * 818 * @param fingersNum Indicates the minimum number of fingers to trigger a rotation. The value ranges from 2 to 5. 819 * Default value: <b>2</b> 820 * @param angleNum Indicates the minimum degree that can trigger the rotation gesture. Default value: <b>1</b> 821 * If this parameter is set to a value less than or equal to 0 or greater than 360, 822 * the default value <b>1</b> is used. 823 * @return Returns the pointer to the created gesture. 824 */ 825 ArkUI_GestureRecognizer* (*createRotationGesture)(int32_t fingersNum, double angleNum); 826 827 /** 828 * @brief Creates a swipe gesture. 829 * 830 * This API is used to implement a swipe gesture, which can be recognized when the swipe speed is 100 831 * vp/s or higher. \n 832 * 833 * @param fingersNum Indicates the minimum number of fingers to trigger a swipe gesture. 834 * The value ranges from 1 to 10. 835 * @param directions Indicates the swipe direction. 836 * @param speedNum Indicates the minimum speed of the swipe gesture, in px/s. 837 * If this parameter is set to a value less than or equal to 0, the default value <b>100</b> is used. 838 * @return Returns the pointer to the created gesture. 839 */ 840 ArkUI_GestureRecognizer* (*createSwipeGesture)( 841 int32_t fingersNum, ArkUI_GestureDirectionMask directions, double speedNum); 842 843 /** 844 * @brief Creates a gesture group. 845 * 846 * @param gestureMode Indicates the gesture group mode. 847 * @return Returns the pointer to the created gesture group. 848 */ 849 ArkUI_GestureRecognizer* (*createGroupGesture)(ArkUI_GroupGestureMode gestureMode); 850 851 /** 852 * @brief Disposes a gesture to release resources. 853 * 854 * @param recognizer Indicates the pointer to the gesture to dispose. 855 */ 856 void (*dispose)(ArkUI_GestureRecognizer* recognizer); 857 858 /** 859 * @brief Adds a gesture to a gesture group. 860 * 861 * @param group Indicates the pointer to the gesture group. 862 * @param child Indicates the gesture to be added to the gesture group. 863 * @return Returns <b>0</b> if success. 864 * Returns <b>401</b> if a parameter exception occurs. Returns 401 if a parameter exception occurs. 865 */ 866 int32_t (*addChildGesture)(ArkUI_GestureRecognizer* group, ArkUI_GestureRecognizer* child); 867 868 /** 869 * @brief Removes a gesture to a gesture group. 870 * 871 * @param group Indicates the pointer to the gesture group. 872 * @param child Indicates the gesture to be removed to the gesture group. 873 * @return Returns <b>0</b> if success. 874 * Returns <b>401</b> if a parameter exception occurs. 875 */ 876 int32_t (*removeChildGesture)(ArkUI_GestureRecognizer* group, ArkUI_GestureRecognizer* child); 877 878 /** 879 * @brief Registers a callback for gestures. 880 * 881 * @param recognizer Indicates the pointer to the gesture recognizer. 882 * @param actionTypeMask Indicates the set of gesture event types. Multiple callbacks can be registered at once, 883 * with the callback event types distinguished in the callbacks. 884 * Example: actionTypeMask = GESTURE_EVENT_ACTION_ACCEPT | GESTURE_EVENT_ACTION_UPDATE; 885 * @param extraParams Indicates the context passed in the <b>targetReceiver</b> callback. 886 * @param targetReceiver Indicates the callback to register for processing the gesture event types. 887 * <b>event</b> indicates the gesture callback data. 888 * @return Returns <b>0</b> if success. 889 * Returns <b>401</b> if a parameter exception occurs. 890 */ 891 int32_t (*setGestureEventTarget)( 892 ArkUI_GestureRecognizer* recognizer, ArkUI_GestureEventActionTypeMask actionTypeMask, void* extraParams, 893 void (*targetReceiver)(ArkUI_GestureEvent* event, void* extraParams)); 894 895 /** 896 * @brief Adds a gesture to a UI component. 897 * 898 * @param node Indicates the UI component to which you want to add the gesture. 899 * @param recognizer Indicates the gesture to be added to the UI component. 900 * @param mode Indicates the gesture event mode. Available options are <b>NORMAL_GESTURE</b>, 901 * <b>PARALLEL_GESTURE</b>, and <b>PRIORITY_GESTURE</b>. 902 * @param mask Indicates the gesture masking mode. 903 * @return Returns <b>0</b> if success. 904 * Returns <b>401</b> if a parameter exception occurs. 905 */ 906 int32_t (*addGestureToNode)( 907 ArkUI_NodeHandle node, ArkUI_GestureRecognizer* recognizer, ArkUI_GesturePriority mode, ArkUI_GestureMask mask); 908 909 /** 910 * @brief Removes a gesture from a node. 911 * 912 * @param node Indicates the node from which you want to remove the gesture. 913 * @param recognizer Indicates the gesture to be removed. 914 * @return Returns <b>0</b> if success. 915 * Returns <b>401</b> if a parameter exception occurs. 916 */ 917 int32_t (*removeGestureFromNode)(ArkUI_NodeHandle node, ArkUI_GestureRecognizer* recognizer); 918 919 /** 920 * @brief Sets a gesture interruption callback for a node. 921 * 922 * @param node Indicates the node for which you want to set a gesture interruption callback. 923 * @param interrupter Indicates the gesture interruption callback to set. 924 * <b>info</b> indicates the gesture interruption data. If <b>interrupter</b> returns 925 * <b>GESTURE_INTERRUPT_RESULT_CONTINUE</b>, the gesture recognition process continues. If it returns 926 * <b>GESTURE_INTERRUPT_RESULT_REJECT</b>, the gesture recognition process is paused. 927 * @return Returns <b>0</b> if success. 928 * Returns <b>401</b> if a parameter exception occurs. 929 */ 930 int32_t (*setGestureInterrupterToNode)( 931 ArkUI_NodeHandle node, ArkUI_GestureInterruptResult (*interrupter)(ArkUI_GestureInterruptInfo* info)); 932 933 /** 934 * @brief Obtains the type of a gesture. 935 * 936 * @param recognizer Indicates the pointer to the gesture. 937 * @return Returns the gesture type. 938 */ 939 ArkUI_GestureRecognizerType (*getGestureType)(ArkUI_GestureRecognizer* recognizer); 940 941 /** 942 * @brief Sets the callback function for a parallel internal gesture event. 943 * 944 * @param node Indicates the ArkUI node for which the callback of a parallel internal gesture event is to be set. 945 * @param userData Indicates the custom data. 946 * @param parallelInnerGesture Indicates the parallel internal gesture event. <b>event</b> returns the data of the 947 * parallel internal gesture event; <b>parallelInnerGesture</b> returns the pointer to the gesture recognizer 948 * that requires parallel recognition. 949 * @return Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if success. 950 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter exception occurs. 951 */ 952 int32_t (*setInnerGestureParallelTo)( 953 ArkUI_NodeHandle node, void* userData, ArkUI_GestureRecognizer* (*parallelInnerGesture)( 954 ArkUI_ParallelInnerGestureEvent* event)); 955 956 /** 957 * @brief Creates a tap gesture that is subject to distance restrictions. 958 * 959 * 1. This API is used to trigger a tap gesture with one, two, or more taps. \n 960 * 2. If multi-tap is configured, the timeout interval between a lift and the next tap is 300 ms. \n 961 * 3. If the distance between the last tapped position and the current tapped position exceeds 60 vp, 962 * gesture recognition fails. \n 963 * 4. If the value is greater than 1, the tap gesture will fail to be recognized when the number of fingers 964 * touching the screen within 300 ms of the first finger touch is less than the required number, 965 * or when the number of fingers lifted from the screen within 300 ms of the first finger's being lifted 966 * is less than the required number. \n 967 * 5. When the number of fingers touching the screen exceeds the set value, the gesture can be recognized. \n 968 * 6. If the finger moves beyond the preset distance limit, gesture recognition fails. \n 969 * 970 * @param countNum Indicates the number of consecutive taps. If the value is less than 1 or is not set, the default 971 * value <b>1</b> is used. 972 * @param fingersNum Indicates the number of fingers required to trigger a tap. The value ranges from 1 to 10. 973 * If the value is less than 1 or is not set, the default value <b>1</b> is used. 974 * @param distanceThreshold Indicates the allowed moving distance of a finger. 975 * If the value is less than 0 or is not set, it will be converted to the default value of infinity. 976 * @return Returns the pointer to the created gesture. 977 */ 978 ArkUI_GestureRecognizer* (*createTapGestureWithDistanceThreshold)( 979 int32_t countNum, int32_t fingersNum, double distanceThreshold); 980 } ArkUI_NativeGestureAPI_1; 981 982 #ifdef __cplusplus 983 }; 984 #endif 985 986 #endif // ARKUI_NATIVE_GESTTURE_H 987 /** @} */ 988