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 #include <stdbool.h> 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 #define OH_NATIVE_XCOMPONENT_OBJ ("__NATIVE_XCOMPONENT_OBJ__") 47 48 const uint32_t OH_XCOMPONENT_ID_LEN_MAX = 128; 49 const uint32_t OH_MAX_TOUCH_POINTS_NUMBER = 10; 50 51 /** 52 * @brief Enumerates the API access states. 53 * 54 * @since 8 55 * @version 1.0 56 */ 57 enum { 58 /** Successful. */ 59 OH_NATIVEXCOMPONENT_RESULT_SUCCESS = 0, 60 /** Failed. */ 61 OH_NATIVEXCOMPONENT_RESULT_FAILED = -1, 62 /** Invalid parameters. */ 63 OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER = -2, 64 }; 65 66 typedef enum { 67 /** Trigger a touch event when a finger is pressed. */ 68 OH_NATIVEXCOMPONENT_DOWN = 0, 69 /** Trigger a touch event when a finger is lifted. */ 70 OH_NATIVEXCOMPONENT_UP, 71 /** Trigger a touch event when a finger moves on the screen in pressed state. */ 72 OH_NATIVEXCOMPONENT_MOVE, 73 /** Trigger an event when a touch event is canceled. */ 74 OH_NATIVEXCOMPONENT_CANCEL, 75 /** Invalid touch type. */ 76 OH_NATIVEXCOMPONENT_UNKNOWN, 77 } OH_NativeXComponent_TouchEventType; 78 79 /** 80 * @brief Represents the touch point tool type. 81 * 82 * @since 9 83 * @version 1.0 84 */ 85 typedef enum { 86 /** Indicates invalid tool type. */ 87 OH_NATIVEXCOMPONENT_TOOL_TYPE_UNKNOWN = 0, 88 /** Indicates a finger. */ 89 OH_NATIVEXCOMPONENT_TOOL_TYPE_FINGER, 90 /** Indicates a stylus. */ 91 OH_NATIVEXCOMPONENT_TOOL_TYPE_PEN, 92 /** Indicates a eraser. */ 93 OH_NATIVEXCOMPONENT_TOOL_TYPE_RUBBER, 94 /** Indicates a brush. */ 95 OH_NATIVEXCOMPONENT_TOOL_TYPE_BRUSH, 96 /** Indicates a pencil. */ 97 OH_NATIVEXCOMPONENT_TOOL_TYPE_PENCIL, 98 /** Indicates a brush. */ 99 OH_NATIVEXCOMPONENT_TOOL_TYPE_AIRBRUSH, 100 /** Indicates a mouse. */ 101 OH_NATIVEXCOMPONENT_TOOL_TYPE_MOUSE, 102 /** Indicates a lens. */ 103 OH_NATIVEXCOMPONENT_TOOL_TYPE_LENS, 104 } OH_NativeXComponent_TouchPointToolType; 105 106 /** 107 * @brief Represents the touch event source type. 108 * 109 * @since 9 110 * @version 1.0 111 */ 112 typedef enum { 113 /** Indicates an unknown input source type. */ 114 OH_NATIVEXCOMPONENT_SOURCE_TYPE_UNKNOWN = 0, 115 /** Indicates that the input source generates a mouse multi-touch event. */ 116 OH_NATIVEXCOMPONENT_SOURCE_TYPE_MOUSE, 117 /** Indicates that the input source generates a touchscreen multi-touch event. */ 118 OH_NATIVEXCOMPONENT_SOURCE_TYPE_TOUCHSCREEN, 119 /** Indicates that the input source generates a touchpad multi-touch event. */ 120 OH_NATIVEXCOMPONENT_SOURCE_TYPE_TOUCHPAD, 121 /** Indicates that the input source generates a joystick multi-touch event. */ 122 OH_NATIVEXCOMPONENT_SOURCE_TYPE_JOYSTICK, 123 } OH_NativeXComponent_EventSourceType; 124 125 /** 126 * @brief Represents the mouse event action. 127 * 128 * @since 9 129 * @version 1.0 130 */ 131 typedef enum { 132 OH_NATIVEXCOMPONENT_MOUSE_NONE = 0, 133 OH_NATIVEXCOMPONENT_MOUSE_PRESS, 134 OH_NATIVEXCOMPONENT_MOUSE_RELEASE, 135 OH_NATIVEXCOMPONENT_MOUSE_MOVE, 136 } OH_NativeXComponent_MouseEventAction; 137 138 /** 139 * @brief Represents the mouse event button. 140 * 141 * @since 9 142 * @version 1.0 143 */ 144 typedef enum { 145 OH_NATIVEXCOMPONENT_NONE_BUTTON = 0, 146 OH_NATIVEXCOMPONENT_LEFT_BUTTON = 0x01, 147 OH_NATIVEXCOMPONENT_RIGHT_BUTTON = 0x02, 148 OH_NATIVEXCOMPONENT_MIDDLE_BUTTON = 0x04, 149 OH_NATIVEXCOMPONENT_BACK_BUTTON = 0x08, 150 OH_NATIVEXCOMPONENT_FORWARD_BUTTON = 0x10, 151 } OH_NativeXComponent_MouseEventButton; 152 153 typedef struct { 154 /** Unique identifier of a finger. */ 155 int32_t id; 156 /** X coordinate of the touch point relative to the left edge of the screen. */ 157 float screenX; 158 /** Y coordinate of the touch point relative to the upper edge of the screen. */ 159 float screenY; 160 /** X coordinate of the touch point relative to the left edge of the element to touch. */ 161 float x; 162 /** Y coordinate of the touch point relative to the upper edge of the element to touch. */ 163 float y; 164 /** Touch type of the touch event. */ 165 OH_NativeXComponent_TouchEventType type; 166 /** Contact area between the finger pad and the screen. */ 167 double size; 168 /** Pressure of the current touch event. */ 169 float force; 170 /** Timestamp of the current touch event. */ 171 int64_t timeStamp; 172 /** Whether the current point is pressed. */ 173 bool isPressed; 174 } OH_NativeXComponent_TouchPoint; 175 176 // Represents the touch point information. 177 typedef struct { 178 /** Unique identifier of a finger. */ 179 int32_t id; 180 /** X coordinate of the touch point relative to the left edge of the screen. */ 181 float screenX; 182 /** Y coordinate of the touch point relative to the upper edge of the screen. */ 183 float screenY; 184 /** X coordinate of the touch point relative to the left edge of the element to touch. */ 185 float x; 186 /** Y coordinate of the touch point relative to the upper edge of the element to touch. */ 187 float y; 188 /** Touch type of the touch event. */ 189 OH_NativeXComponent_TouchEventType type; 190 /** Contact area between the finger pad and the screen. */ 191 double size; 192 /** Pressure of the current touch event. */ 193 float force; 194 /** ID of the device where the current touch event is generated. */ 195 int64_t deviceId; 196 /** Timestamp of the current touch event. */ 197 int64_t timeStamp; 198 /** Array of the current touch points. */ 199 OH_NativeXComponent_TouchPoint touchPoints[OH_MAX_TOUCH_POINTS_NUMBER]; 200 /** Number of current touch points. */ 201 uint32_t numPoints; 202 } OH_NativeXComponent_TouchEvent; 203 204 /** 205 * @brief Represents the mouse event information. 206 * 207 * @since 9 208 * @version 1.0 209 */ 210 typedef struct { 211 /** X coordinate of the mouse point relative to the left edge of the element to mouse. */ 212 float x; 213 /** Y coordinate of the mouse point relative to the upper edge of the element to mouse. */ 214 float y; 215 /** X coordinate of the mouse point relative to the left edge of the screen. */ 216 float screenX; 217 /** Y coordinate of the mouse point relative to the upper edge of the screen. */ 218 float screenY; 219 /** Timestamp of the current mouse event. */ 220 int64_t timestamp; 221 /** Mouse event action. */ 222 OH_NativeXComponent_MouseEventAction action; 223 /** Mouse event button. */ 224 OH_NativeXComponent_MouseEventButton button; 225 } OH_NativeXComponent_MouseEvent; 226 227 /** 228 * @brief Provides an encapsulated <b>OH_NativeXComponent</b> instance. 229 * 230 * @since 8 231 * @version 1.0 232 */ 233 typedef struct OH_NativeXComponent OH_NativeXComponent; 234 235 /** 236 * @brief Registers the surface lifecycle and touch event callbacks. 237 * 238 * @since 8 239 * @version 1.0 240 */ 241 typedef struct OH_NativeXComponent_Callback { 242 /** Called when the surface is created. */ 243 void (*OnSurfaceCreated)(OH_NativeXComponent* component, void* window); 244 /** Called when the surface is changed. */ 245 void (*OnSurfaceChanged)(OH_NativeXComponent* component, void* window); 246 /** Called when the surface is destroyed. */ 247 void (*OnSurfaceDestroyed)(OH_NativeXComponent* component, void* window); 248 /** Called when a touch event is triggered. */ 249 void (*DispatchTouchEvent)(OH_NativeXComponent* component, void* window); 250 } OH_NativeXComponent_Callback; 251 252 /** 253 * @brief Registers the mouse event callbacks. 254 * 255 * @since 9 256 * @version 1.0 257 */ 258 typedef struct OH_NativeXComponent_MouseEvent_Callback { 259 /** Called when a mouse event is triggered. */ 260 void (*DispatchMouseEvent)(OH_NativeXComponent* component, void* window); 261 /** Called when a hover event is triggered. */ 262 void (*DispatchHoverEvent)(OH_NativeXComponent* component, bool isHover); 263 } OH_NativeXComponent_MouseEvent_Callback; 264 265 /** 266 * @brief Obtains the ID of the ArkUI XComponent. 267 * 268 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 269 * @param id Indicates the char buffer to keep the ID of this <b>OH_NativeXComponent</b> instance.\n 270 * Notice that a null-terminator will be appended to the char buffer, so the size of the\n 271 * char buffer should be at least as large as the size of the real id length plus 1.\n 272 * It is recommended that the size of the char buffer be [OH_XCOMPONENT_ID_LEN_MAX + 1]. 273 * @param size Indicates the pointer to the length of <b>id</b>, which you can set and receive. 274 * @return Returns the status code of the execution. 275 * @since 8 276 * @version 1.0 277 */ 278 int32_t OH_NativeXComponent_GetXComponentId(OH_NativeXComponent* component, char* id, uint64_t* size); 279 280 /** 281 * @brief Obtains the size of the surface held by the ArkUI XComponent. 282 * 283 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 284 * @param window Indicates the native window handler. 285 * @param width Indicates the pointer to the width of the current surface. 286 * @param height Indicates the pointer to the height of the current surface. 287 * @return Returns the status code of the execution. 288 * @since 8 289 * @version 1.0 290 */ 291 int32_t OH_NativeXComponent_GetXComponentSize( 292 OH_NativeXComponent* component, const void* window, uint64_t* width, uint64_t* height); 293 294 /** 295 * @brief Obtains the offset of the surface held by the ArkUI XComponent. 296 * 297 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 298 * @param window Indicates the native window handler. 299 * @param x Indicates the pointer to the x coordinate of the current surface. 300 * @param y Indicates the pointer to the y coordinate of the current surface. 301 * @return Returns the status code of the execution. 302 * @since 8 303 * @version 1.0 304 */ 305 int32_t OH_NativeXComponent_GetXComponentOffset( 306 OH_NativeXComponent* component, const void* window, double* x, double* y); 307 308 /** 309 * @brief Obtains the touch event dispatched by the ArkUI XComponent. 310 * 311 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 312 * @param window Indicates the native window handler. 313 * @param touchEvent Indicates the pointer to the current touch event. 314 * @return Returns the status code of the execution. 315 * @since 8 316 * @version 1.0 317 */ 318 int32_t OH_NativeXComponent_GetTouchEvent( 319 OH_NativeXComponent* component, const void* window, OH_NativeXComponent_TouchEvent* touchEvent); 320 321 /** 322 * @brief Obtains the touch pointer tool type by the ArkUI XComponent. 323 * 324 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 325 * @param pointIndex Indicates the pointer index in the touchPoints. 326 * @param toolType Indicates the tool Type of the pointer. 327 * @return Returns the status code of the execution. 328 * @since 9 329 * @version 1.0 330 */ 331 int32_t OH_NativeXComponent_GetTouchPointToolType(OH_NativeXComponent* component, uint32_t pointIndex, 332 OH_NativeXComponent_TouchPointToolType* toolType); 333 334 /** 335 * @brief Obtains the touch pointer tiltX by the ArkUI XComponent. 336 * 337 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 338 * @param pointIndex Indicates the pointer index in the touchPoints. 339 * @param tiltX Indicates the x tilt of the pointer. 340 * @return Returns the status code of the execution. 341 * @since 9 342 * @version 1.0 343 */ 344 int32_t OH_NativeXComponent_GetTouchPointTiltX(OH_NativeXComponent* component, uint32_t pointIndex, float* tiltX); 345 346 /** 347 * @brief Obtains the touch pointer tiltX by the ArkUI XComponent. 348 * 349 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 350 * @param pointIndex Indicates the pointer index in the touchPoints. 351 * @param tiltY Indicates the y tilt of the pointer. 352 * @return Returns the status code of the execution. 353 * @since 9 354 * @version 1.0 355 */ 356 int32_t OH_NativeXComponent_GetTouchPointTiltY(OH_NativeXComponent* component, uint32_t pointIndex, float* tiltY); 357 358 /** 359 * @brief Obtains the mouse event dispatched by the ArkUI XComponent. 360 * 361 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 362 * @param window Indicates the native window handler. 363 * @param mouseEvent Indicates the pointer to the current mouse event. 364 * @return Returns the status code of the execution. 365 * @since 9 366 * @version 1.0 367 */ 368 int32_t OH_NativeXComponent_GetMouseEvent( 369 OH_NativeXComponent* component, const void* window, OH_NativeXComponent_MouseEvent* mouseEvent); 370 371 /** 372 * @brief Registers a callback for this <b>OH_NativeXComponent</b> instance. 373 * 374 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 375 * @param callback Indicates the pointer to a surface lifecycle and touch event callback. 376 * @return Returns the status code of the execution. 377 * @since 8 378 * @version 1.0 379 */ 380 int32_t OH_NativeXComponent_RegisterCallback(OH_NativeXComponent* component, OH_NativeXComponent_Callback* callback); 381 382 /** 383 * @brief Registers a callback for this <b>OH_NativeXComponent</b> instance. 384 * 385 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 386 * @param callback Indicates the pointer to a mouse event callback. 387 * @return Returns the status code of the execution. 388 * @since 9 389 * @version 1.0 390 */ 391 int32_t OH_NativeXComponent_RegisterMouseEventCallback( 392 OH_NativeXComponent* component, OH_NativeXComponent_MouseEvent_Callback* callback); 393 394 #ifdef __cplusplus 395 }; 396 #endif 397 #endif // _NATIVE_INTERFACE_XCOMPONENT_H_ 398