diff --git a/arkui/ace_engine/native/native_gesture.h b/arkui/ace_engine/native/native_gesture.h new file mode 100644 index 0000000000000000000000000000000000000000..984df2c2c424699bbbcdbf8e1fd0645944184e50 --- /dev/null +++ b/arkui/ace_engine/native/native_gesture.h @@ -0,0 +1,616 @@ +/* + * Copyright (c) 2024 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup ArkUI_NativeModule + * @{ + * + * @brief Defines APIs for ArkUI to register gesture callbacks on the native side. + * + * @since 12 + */ + +/** + * @file native_gesture.h + * + * @brief Provides type definitions for NativeGesture APIs. + * + * @library libace_ndk.z.so + * @syscap SystemCapability.ArkUI.ArkUI.Full + * @since 12 + */ + +#ifndef ARKUI_NATIVE_GESTTURE_H +#define ARKUI_NATIVE_GESTTURE_H + +#include "ui_input_event.h" +#include "native_type.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Defines a gesture recognizer. + * + * @since 12 + */ +struct ArkUI_GestureRecognizer; + +/** + * @brief Defines the gesture interruption information. + * + * @since 12 + */ +struct ArkUI_GestureInterruptInfo; + +/** + * @brief Defines the gesture event. + * + * @since 12 + */ +struct ArkUI_GestureEvent; + +/** + * @brief Enumerates gesture event types. + * + * @since 12 + */ +typedef enum { + /** Triggered. */ + GESTURE_EVENT_ACTION_ACCEPT = 0x01, + + /** Updated. */ + GESTURE_EVENT_ACTION_UPDATE = 0x02, + + /** Ended. */ + GESTURE_EVENT_ACTION_END = 0x04, + + /** Canceled. */ + GESTURE_EVENT_ACTION_CANCEL = 0x08, +} ArkUI_GestureEventActionType; + +/** + * @brief Defines a set of gesture event types. + * + * Example: ArkUI_GestureEventActionTypeMask actions = GESTURE_EVENT_ACTION_ACCEPT | GESTURE_EVENT_ACTION_UPDATE;\n + * + * @since 12 + */ +typedef uint32_t ArkUI_GestureEventActionTypeMask; + +/** + * @brief Enumerates gesture event modes. + * + * @since 12 + */ +typedef enum { + /** Normal. */ + NORMAL = 0, + + /** High-priority. */ + PRIORITY = 1, + + /** Parallel. */ + PARALLEL = 2, +} ArkUI_GesturePriority; + +/** + * @brief Enumerates gesture group modes. + * + * @since 12 + */ +typedef enum { + /* Sequential recognition. Gestures are recognized in the registration sequence until all gestures are recognized + * successfully. Once one gesture fails to be recognized, all subsequent gestures fail to be recognized. + * Only the last gesture in the gesture group can respond to the end event. */ + SEQUENTIAL_GROUP = 0, + + /** Parallel recognition. Registered gestures are recognized concurrently until all gestures are recognized. + * The recognition result of each gesture does not affect each other. */ + PARALLEL_GROUP = 1, + + /** Exclusive recognition. Registered gestures are identified concurrently. + * If one gesture is successfully recognized, gesture recognition ends. */ + EXCLUSIVE_GROUP = 2, +} ArkUI_GroupGestureMode; + +/** + * @brief Enumerates gesture directions. + * + * @since 12 + */ +typedef enum { + /** All directions. */ + GESTURE_DIRECTION_ALL = 0b1111, + + /** Horizontal direction. */ + GESTURE_DIRECTION_HORIZONTAL = 0b0011, + + /** Vertical direction. */ + GESTURE_DIRECTION_VERTICAL = 0b1100, + + /** Leftward. */ + GESTURE_DIRECTION_LEFT = 0b0001, + + /** Rightward. */ + GESTURE_DIRECTION_RIGHT = 0b0010, + + /** Upward. */ + GESTURE_DIRECTION_UP = 0b0100, + + /** Downward. */ + GESTURE_DIRECTION_DOWN = 0b1000, + + /** None. */ + GESTURE_DIRECTION_NONE = 0, +} ArkUI_GestureDirection; + +/** + * @brief Defines a set of gesture directions. + * + * Example: ArkUI_GestureDirectionMask directions = GESTURE_DIRECTION_LEFT | GESTURE_DIRECTION_RIGHT \n + * This example indicates that the leftward and rightward directions are supported. \n + * + * @since 12 + */ +typedef uint32_t ArkUI_GestureDirectionMask; + +/** + * @brief Enumerates gesture masking modes. + * + * @since 12 + */ +typedef enum { + /** The gestures of child components are enabled and recognized based on the default gesture recognition sequence.*/ + NORMAL_GESTURE_MASK = 0, + + /** The gestures of child components are disabled, including the built-in gestures. */ + IGNORE_INTERNAL_GESTURE_MASK, +} ArkUI_GestureMask; + +/** + * @brief Enumerates gesture types. + * + * @since 12 + */ +typedef enum { + /** Tap. */ + TAP_GESTURE = 0, + + /** Long press. */ + LONG_PRESS_GESTURE, + + /** Pan. */ + PAN_GESTURE, + + /** Pinch. */ + PINCH_GESTURE, + + /** Rotate. */ + ROTATION_GESTURE, + + /** Swipe. */ + SWIPE_GESTURE, + + /** A group of gestures. */ + GROUP_GESTURE, +} ArkUI_GestureRecognizerType; + +/** + * @brief Enumerates gesture interruption results. + * + * @since 12 + */ +typedef enum { + /** The gesture recognition process continues. */ + GESTURE_INTERRUPT_RESULT_CONTINUE = 0, + + /** The gesture recognition process is paused. */ + GESTURE_INTERRUPT_RESULT_REJECT, +} ArkUI_GestureInterruptResult; + +/** +* @brief Checks whether a gesture is a built-in gesture of the component. +* +* @param event Indicates the pointer to the gesture interruption information. +* @return Returns true if the gesture is a built-in gesture; returns false otherwise. + +* @since 12 +*/ +bool OH_ArkUI_GestureInterruptInfo_GetSystemFlag(const ArkUI_GestureInterruptInfo* event); + +/** +* @brief Obtains the pointer to interrupted gesture recognizer. +* +* @param event Indicates the pointer to the gesture interruption information. +* @return Returns the pointer to interrupted gesture recognizer. +* @since 12 +*/ +ArkUI_GestureRecognizer* OH_ArkUI_GestureInterruptInfo_GetRecognizer(const ArkUI_GestureInterruptInfo* event); + +/** +* @brief Obtains the pointer to the interrupted gesture event. +* +* @param event Indicates the pointer to the gesture interruption information. +* @return Returns the pointer to the interrupted gesture event. +* @since 12 +*/ +ArkUI_GestureEvent* OH_ArkUI_GestureInterruptInfo_GetGestureEvent(const ArkUI_GestureInterruptInfo* event); + +/** +* @brief Obtains the gesture event type. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the gesture event type. +* @since 12 +*/ +ArkUI_GestureEventActionType OH_ArkUI_GestureEvent_GetActionType(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains gesture input. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the pointer to the input event of the gesture event. +* @since 12 +*/ +const ArkUI_UIInputEvent* OH_ArkUI_GestureEvent_GetRawInputEvent(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains the number of times that a long press gesture is triggered periodically. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the number of times that the long press gesture is triggered periodically. +* @since 12 +*/ +int32_t OH_ArkUI_LongPress_GetRepeatCount(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains the velocity of a pan gesture along the main axis. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the velocity of the pan gesture along the main axis, in px/s. +* The value is the square root of the sum of the squares of the velocity on the x-axis and y-axis. +* @since 12 +*/ +float OH_ArkUI_PanGesture_GetVelocity(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains the velocity of a pan gesture along the x-axis. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the velocity of the pan gesture along the x-axis, in px/s. +* @since 12 +*/ +float OH_ArkUI_PanGesture_GetVelocityX(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains the velocity of a pan gesture along the y-axis. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the velocity of the pan gesture along the y-axis, in px/s. +* @since 12 +*/ +float OH_ArkUI_PanGesture_GetVelocityY(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains the relative offset of a pan gesture along the x-axis. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the relative offset of the gesture along the x-axis, in px. +* @since 12 +*/ +float OH_ArkUI_PanGesture_GetOffsetX(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains the relative offset of a pan gesture along the y-axis. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the relative offset of the gesture along the y-axis, in px. +* @since 12 +*/ +float OH_ArkUI_PanGesture_GetOffsetY(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains the angle information of the swipe gesture. +* +* 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. \n +* Based on the coordinates of the initial line's and current line's end points, the arc tangent function is used to +* calculate the respective included angle of the points relative to the horizontal direction \n +* by using the following formula: Rotation angle = arctan2(cy2-cy1,cx2-cx1) - arctan2(y2-y1,x2-x1). \n +* The initial line is used as the coordinate system. Values from 0 to 180 degrees represent clockwise rotation, +* while values from –180 to 0 degrees represent counterclockwise rotation. \n +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the angle of the swipe gesture, which is the result obtained based on the aforementioned formula. +* @since 12 +*/ +float OH_ArkUI_SwipeGesture_GetAngle(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains the average velocity of all fingers used in the swipe gesture. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the average velocity of all fingers used in the swipe gesture, in px/s. +* @since 12 +*/ +float OH_ArkUI_SwipeGesture_GetVelocity(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains the angle information of a rotation gesture. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the rotation angle. +* @since 12 +*/ +float OH_ArkUI_RotationGesture_GetAngle(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains the scale ratio of a pinch gesture. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the scale ratio. +* @since 12 +*/ +float OH_ArkUI_PinchGesture_GetScale(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains the X coordinate of the center of the pinch gesture, in vp, +* relative to the upper left corner of the current component. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the X coordinate of the center of the pinch gesture, in vp, +* relative to the upper left corner of the current component. +* @since 12 +*/ +float OH_ArkUI_PinchGesture_GetCenterX(const ArkUI_GestureEvent* event); + +/** +* @brief Obtains the Y coordinate of the center of the pinch gesture, in vp, +* relative to the upper left corner of the current component. +* +* @param event Indicates the pointer to the gesture event. +* @return Returns the Y coordinate of the center of the pinch gesture, in vp, +* relative to the upper left corner of the current component. +* @since 12 +*/ +float OH_ArkUI_PinchGesture_GetCenterY(const ArkUI_GestureEvent* event); + +/** + * @brief Defines the gesture APIs. + * + * @since 12 + */ +typedef struct { + /** The struct version is 1. */ + int32_t version; + + /** + * @brief Creates a tap gesture. + * + * 1. This API is used to trigger a tap gesture with one, two, or more taps. \n + * 2. If multi-tap is configured, the timeout interval between a lift and the next tap is 300 ms. \n + * 3. If the distance between the last tapped position and the current tapped position exceeds 60 vp, + * gesture recognition fails. \n + * 4. If the value is greater than 1, the tap gesture will fail to be recognized when the number of fingers + * touching the screen within 300 ms of the first finger touch is less than the required number, \n + * or when the number of fingers lifted from the screen within 300 ms of the first finger's being lifted + * is less than the required number. \n + * 5. When the number of fingers touching the screen exceeds the set value, the gesture can be recognized. \n + * + * @param countNum Indicates the number of consecutive taps. If the value is less than 1 or is not set, + * the default value 1 is used. + * @param fingersNum Indicates the number of fingers required to trigger a tap. The value ranges + * from 1 to 10. If the value is less than 1 or is not set, the default value 1 is used. + * @return Returns the pointer to the created gesture. + */ + ArkUI_GestureRecognizer* (*createTapGesture)(int32_t countNum, int32_t fingersNum); + + /** + * @brief Creates a long press gesture. + * + * 1. This API is used to trigger a long press gesture, which requires one or more fingers with a minimum + * The value ranges 500 ms hold-down time. \n + * 2. In components that support drag actions by default, such as , , + *