1 /* 2 * Copyright (c) 2021-2022 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 OH_NativeXComponent Native XComponent 18 * @{ 19 * 20 * @brief Describes the surface and touch event held by the ArkUI XComponent, which can be used for the EGL/OpenGL ES\n 21 * and media data input and displayed on the ArkUI XComponent. 22 * 23 * @since 8 24 * @version 1.0 25 */ 26 27 /** 28 * @file native_interface_xcomponent.h 29 * 30 * @brief Declares APIs for accessing a Native XComponent. 31 * 32 * @since 8 33 * @version 1.0 34 */ 35 36 #ifndef _NATIVE_INTERFACE_XCOMPONENT_H_ 37 #define _NATIVE_INTERFACE_XCOMPONENT_H_ 38 39 #include <stdint.h> 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 /** 46 * @brief Enumerates the API access states. 47 * 48 * @since 8 49 * @version 1.0 50 */ 51 enum { 52 /** Successful. */ 53 OH_NATIVEXCOMPONENT_RESULT_SUCCESS = 0, 54 /** Failed. */ 55 OH_NATIVEXCOMPONENT_RESULT_FAILED = -1, 56 /** Invalid parameters. */ 57 OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER = -2, 58 }; 59 60 enum OH_NativeXComponent_TouchEventType { 61 /** Trigger a touch event when a finger is pressed. */ 62 OH_NATIVEXCOMPONENT_DOWN = 0, 63 /** Trigger a touch event when a finger is lifted. */ 64 OH_NATIVEXCOMPONENT_UP, 65 /** Trigger a touch event when a finger moves on the screen in pressed state. */ 66 OH_NATIVEXCOMPONENT_MOVE, 67 /** Trigger an event when a touch event is canceled. */ 68 OH_NATIVEXCOMPONENT_CANCEL, 69 /** Invalid touch type. */ 70 OH_NATIVEXCOMPONENT_UNKNOWN, 71 }; 72 73 #define OH_NATIVE_XCOMPONENT_OBJ ("__NATIVE_XCOMPONENT_OBJ__") 74 const uint32_t OH_XCOMPONENT_ID_LEN_MAX = 128; 75 const uint32_t OH_MAX_TOUCH_POINTS_NUMBER = 10; 76 77 struct OH_NativeXComponent_TouchPoint { 78 /** Unique identifier of a finger. */ 79 int32_t id = 0; 80 /** X coordinate of the touch point relative to the left edge of the screen. */ 81 float screenX = 0.0; 82 /** Y coordinate of the touch point relative to the upper edge of the screen. */ 83 float screenY = 0.0; 84 /** X coordinate of the touch point relative to the left edge of the element to touch. */ 85 float x = 0.0; 86 /** Y coordinate of the touch point relative to the upper edge of the element to touch. */ 87 float y = 0.0; 88 /** Touch type of the touch event. */ 89 OH_NativeXComponent_TouchEventType type = OH_NativeXComponent_TouchEventType::OH_NATIVEXCOMPONENT_UNKNOWN; 90 /** Contact area between the finger pad and the screen. */ 91 double size = 0.0; 92 /** Pressure of the current touch event. */ 93 float force = 0.0; 94 /** Timestamp of the current touch event. */ 95 long long timeStamp = 0; 96 /** Whether the current point is pressed. */ 97 bool isPressed = false; 98 }; 99 100 // Represents the touch point information. 101 struct OH_NativeXComponent_TouchEvent { 102 /** Unique identifier of a finger. */ 103 int32_t id = 0; 104 /** X coordinate of the touch point relative to the left edge of the screen. */ 105 float screenX = 0.0; 106 /** Y coordinate of the touch point relative to the upper edge of the screen. */ 107 float screenY = 0.0; 108 /** X coordinate of the touch point relative to the left edge of the element to touch. */ 109 float x = 0.0; 110 /** Y coordinate of the touch point relative to the upper edge of the element to touch. */ 111 float y = 0.0; 112 /** Touch type of the touch event. */ 113 OH_NativeXComponent_TouchEventType type = OH_NativeXComponent_TouchEventType::OH_NATIVEXCOMPONENT_UNKNOWN; 114 /** Contact area between the finger pad and the screen. */ 115 double size = 0.0; 116 /** Pressure of the current touch event. */ 117 float force = 0.0; 118 /** ID of the device where the current touch event is generated. */ 119 int64_t deviceId = 0; 120 /** Timestamp of the current touch event. */ 121 long long timeStamp = 0; 122 /** Array of the current touch points. */ 123 OH_NativeXComponent_TouchPoint touchPoints[OH_MAX_TOUCH_POINTS_NUMBER]; 124 /** Number of current touch points. */ 125 uint32_t numPoints = 0; 126 }; 127 128 /** 129 * @brief Provides an encapsulated <b>OH_NativeXComponent</b> instance. 130 * 131 * @since 8 132 * @version 1.0 133 */ 134 typedef struct OH_NativeXComponent OH_NativeXComponent; 135 136 /** 137 * @brief Registers the surface lifecycle and touch event callbacks. 138 * 139 * @since 8 140 * @version 1.0 141 */ 142 typedef struct OH_NativeXComponent_Callback { 143 /** Called when the surface is created. */ 144 void (*OnSurfaceCreated)(OH_NativeXComponent* component, void* window); 145 /** Called when the surface is changed. */ 146 void (*OnSurfaceChanged)(OH_NativeXComponent* component, void* window); 147 /** Called when the surface is destroyed. */ 148 void (*OnSurfaceDestroyed)(OH_NativeXComponent* component, void* window); 149 /** Called when a touch event is triggered. */ 150 void (*DispatchTouchEvent)(OH_NativeXComponent* component, void* window); 151 } OH_NativeXComponent_Callback; 152 153 /** 154 * @brief Obtains the ID of the ArkUI XComponent. 155 * 156 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 157 * @param id Indicates the char buffer to keep the ID of this <b>OH_NativeXComponent</b> instance.\n 158 * Notice that a null-terminator will be appended to the char buffer, so the size of the\n 159 * char buffer should be at least as large as the size of the real id length plus 1.\n 160 * It is recommended that the size of the char buffer be [OH_XCOMPONENT_ID_LEN_MAX + 1]. 161 * @param size Indicates the pointer to the length of <b>id</b>, which you can set and receive. 162 * @return Returns the status code of the execution. 163 * @since 8 164 * @version 1.0 165 */ 166 int32_t OH_NativeXComponent_GetXComponentId(OH_NativeXComponent* component, char* id, uint64_t* size); 167 168 /** 169 * @brief Obtains the size of the surface held by the ArkUI XComponent. 170 * 171 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 172 * @param window Indicates the native window handler. 173 * @param width Indicates the pointer to the width of the current surface. 174 * @param height Indicates the pointer to the height of the current surface. 175 * @return Returns the status code of the execution. 176 * @since 8 177 * @version 1.0 178 */ 179 int32_t OH_NativeXComponent_GetXComponentSize( 180 OH_NativeXComponent* component, const void* window, uint64_t* width, uint64_t* height); 181 182 /** 183 * @brief Obtains the offset of the surface held by the ArkUI XComponent. 184 * 185 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 186 * @param window Indicates the native window handler. 187 * @param x Indicates the pointer to the x coordinate of the current surface. 188 * @param y Indicates the pointer to the y coordinate of the current surface. 189 * @return Returns the status code of the execution. 190 * @since 8 191 * @version 1.0 192 */ 193 int32_t OH_NativeXComponent_GetXComponentOffset( 194 OH_NativeXComponent* component, const void* window, double* x, double* y); 195 196 /** 197 * @brief Obtains the touch event dispatched by the ArkUI XComponent. 198 * 199 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 200 * @param window Indicates the native window handler. 201 * @param touchEvent Indicates the pointer to the current touch event. 202 * @return Returns the status code of the execution. 203 * @since 8 204 * @version 1.0 205 */ 206 int32_t OH_NativeXComponent_GetTouchEvent( 207 OH_NativeXComponent* component, const void* window, OH_NativeXComponent_TouchEvent* touchEvent); 208 209 /** 210 * @brief Registers a callback for this <b>OH_NativeXComponent</b> instance. 211 * 212 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 213 * @param callback Indicates the pointer to a surface lifecycle and touch event callback. 214 * @return Returns the status code of the execution. 215 * @since 8 216 * @version 1.0 217 */ 218 int32_t OH_NativeXComponent_RegisterCallback(OH_NativeXComponent* component, OH_NativeXComponent_Callback* callback); 219 220 #ifdef __cplusplus 221 }; 222 #endif 223 #endif // _NATIVE_INTERFACE_XCOMPONENT_H_ 224