1 /* 2 * Copyright (c) 2021-2023 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 * @library libace_ndk.z.so 32 * @syscap SystemCapability.ArkUI.ArkUI.Full 33 * @kit ArkUI 34 * @since 8 35 * @version 1.0 36 */ 37 38 #ifndef _NATIVE_INTERFACE_XCOMPONENT_H_ 39 #define _NATIVE_INTERFACE_XCOMPONENT_H_ 40 41 #include <stdbool.h> 42 #include <stdint.h> 43 #ifdef __cplusplus 44 #include <vector> 45 #endif 46 47 #include "arkui/native_interface_accessibility.h" 48 #include "arkui/native_type.h" 49 #include "arkui/ui_input_event.h" 50 51 #include "native_xcomponent_key_event.h" 52 53 #ifdef __cplusplus 54 extern "C" { 55 #endif 56 57 #define OH_NATIVE_XCOMPONENT_OBJ ("__NATIVE_XCOMPONENT_OBJ__") 58 #define OH_NATIVE_XCOMPONENT_MAX_TOUCH_POINTS_NUMBER 10 59 60 const uint32_t OH_XCOMPONENT_ID_LEN_MAX = 128; 61 const uint32_t OH_MAX_TOUCH_POINTS_NUMBER = 10; 62 63 /** 64 * @brief Enumerates the API access states. 65 * 66 * @since 8 67 * @version 1.0 68 */ 69 enum { 70 /** Successful. */ 71 OH_NATIVEXCOMPONENT_RESULT_SUCCESS = 0, 72 /** Failed. */ 73 OH_NATIVEXCOMPONENT_RESULT_FAILED = -1, 74 /** Invalid parameters. */ 75 OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER = -2, 76 }; 77 78 /** 79 * @brief Status code for AI analyzer. 80 * 81 * @since 18 82 */ 83 typedef enum { 84 /** AI analyzer execution is finished. */ 85 ARKUI_XCOMPONENT_AI_ANALYSIS_FINISHED = 0, 86 /** AI analyzer is disabled. */ 87 ARKUI_XCOMPONENT_AI_ANALYSIS_DISABLED = 110000, 88 /** AI analyzer is unsupported. */ 89 ARKUI_XCOMPONENT_AI_ANALYSIS_UNSUPPORTED = 110001, 90 /** AI analyzer is ongoing. */ 91 ARKUI_XCOMPONENT_AI_ANALYSIS_ONGOING = 110002, 92 /** AI analyzer is stopped. */ 93 ARKUI_XCOMPONENT_AI_ANALYSIS_STOPPED = 110003, 94 } ArkUI_XComponent_ImageAnalyzerState; 95 96 /** 97 * @brief Represents the type of touch event. 98 * 99 * @since 8 100 * @version 1.0 101 */ 102 typedef enum { 103 /** Trigger a touch event when a finger is pressed. */ 104 OH_NATIVEXCOMPONENT_DOWN = 0, 105 /** Trigger a touch event when a finger is lifted. */ 106 OH_NATIVEXCOMPONENT_UP, 107 /** Trigger a touch event when a finger moves on the screen in pressed state. */ 108 OH_NATIVEXCOMPONENT_MOVE, 109 /** Trigger an event when a touch event is canceled. */ 110 OH_NATIVEXCOMPONENT_CANCEL, 111 /** Invalid touch type. */ 112 OH_NATIVEXCOMPONENT_UNKNOWN, 113 } OH_NativeXComponent_TouchEventType; 114 115 /** 116 * @brief Represents the touch point tool type. 117 * 118 * @since 9 119 * @version 1.0 120 */ 121 typedef enum { 122 /** Indicates invalid tool type. */ 123 OH_NATIVEXCOMPONENT_TOOL_TYPE_UNKNOWN = 0, 124 /** Indicates a finger. */ 125 OH_NATIVEXCOMPONENT_TOOL_TYPE_FINGER, 126 /** Indicates a stylus. */ 127 OH_NATIVEXCOMPONENT_TOOL_TYPE_PEN, 128 /** Indicates a eraser. */ 129 OH_NATIVEXCOMPONENT_TOOL_TYPE_RUBBER, 130 /** Indicates a brush. */ 131 OH_NATIVEXCOMPONENT_TOOL_TYPE_BRUSH, 132 /** Indicates a pencil. */ 133 OH_NATIVEXCOMPONENT_TOOL_TYPE_PENCIL, 134 /** Indicates a brush. */ 135 OH_NATIVEXCOMPONENT_TOOL_TYPE_AIRBRUSH, 136 /** Indicates a mouse. */ 137 OH_NATIVEXCOMPONENT_TOOL_TYPE_MOUSE, 138 /** Indicates a lens. */ 139 OH_NATIVEXCOMPONENT_TOOL_TYPE_LENS, 140 } OH_NativeXComponent_TouchPointToolType; 141 142 /** 143 * @brief Represents the touch event source type. 144 * 145 * @since 9 146 * @version 1.0 147 */ 148 typedef enum { 149 /** Indicates an unknown input source type. */ 150 OH_NATIVEXCOMPONENT_SOURCE_TYPE_UNKNOWN = 0, 151 /** Indicates that the input source generates a mouse multi-touch event. */ 152 OH_NATIVEXCOMPONENT_SOURCE_TYPE_MOUSE, 153 /** Indicates that the input source generates a touchscreen multi-touch event. */ 154 OH_NATIVEXCOMPONENT_SOURCE_TYPE_TOUCHSCREEN, 155 /** Indicates that the input source generates a touchpad multi-touch event. */ 156 OH_NATIVEXCOMPONENT_SOURCE_TYPE_TOUCHPAD, 157 /** Indicates that the input source generates a joystick multi-touch event. */ 158 OH_NATIVEXCOMPONENT_SOURCE_TYPE_JOYSTICK, 159 /** 160 * @brief Indicates that the input source generates a keyboard event. 161 * 162 * @since 10 163 * @version 1.0 164 */ 165 OH_NATIVEXCOMPONENT_SOURCE_TYPE_KEYBOARD, 166 } OH_NativeXComponent_EventSourceType; 167 168 /** 169 * @brief Represents the mouse event action. 170 * 171 * @since 9 172 * @version 1.0 173 */ 174 typedef enum { 175 OH_NATIVEXCOMPONENT_MOUSE_NONE = 0, 176 OH_NATIVEXCOMPONENT_MOUSE_PRESS, 177 OH_NATIVEXCOMPONENT_MOUSE_RELEASE, 178 OH_NATIVEXCOMPONENT_MOUSE_MOVE, 179 /** Triggered when the mouse event is canceled. 180 * @since 18 181 */ 182 OH_NATIVEXCOMPONENT_MOUSE_CANCEL, 183 } OH_NativeXComponent_MouseEventAction; 184 185 /** 186 * @brief Represents the mouse event button. 187 * 188 * @since 9 189 * @version 1.0 190 */ 191 typedef enum { 192 OH_NATIVEXCOMPONENT_NONE_BUTTON = 0, 193 OH_NATIVEXCOMPONENT_LEFT_BUTTON = 0x01, 194 OH_NATIVEXCOMPONENT_RIGHT_BUTTON = 0x02, 195 OH_NATIVEXCOMPONENT_MIDDLE_BUTTON = 0x04, 196 OH_NATIVEXCOMPONENT_BACK_BUTTON = 0x08, 197 OH_NATIVEXCOMPONENT_FORWARD_BUTTON = 0x10, 198 } OH_NativeXComponent_MouseEventButton; 199 200 /** 201 * @brief Represents the source tool type of TouchEvent 202 * 203 * @since 10 204 * @version 1.0 205 */ 206 typedef enum { 207 OH_NATIVEXCOMPONENT_SOURCETOOL_UNKNOWN = 0, 208 OH_NATIVEXCOMPONENT_SOURCETOOL_FINGER = 1, 209 OH_NATIVEXCOMPONENT_SOURCETOOL_PEN = 2, 210 OH_NATIVEXCOMPONENT_SOURCETOOL_RUBBER = 3, 211 OH_NATIVEXCOMPONENT_SOURCETOOL_BRUSH = 4, 212 OH_NATIVEXCOMPONENT_SOURCETOOL_PENCIL = 5, 213 OH_NATIVEXCOMPONENT_SOURCETOOL_AIRBRUSH = 6, 214 OH_NATIVEXCOMPONENT_SOURCETOOL_MOUSE = 7, 215 OH_NATIVEXCOMPONENT_SOURCETOOL_LENS = 8, 216 OH_NATIVEXCOMPONENT_SOURCETOOL_TOUCHPAD = 9, 217 } OH_NativeXComponent_TouchEvent_SourceTool; 218 219 /** 220 * @brief Represents the historical point. 221 * 222 * @since 10 223 * @version 1.0 224 */ 225 typedef struct { 226 /** Unique identifier of a finger. */ 227 int32_t id; 228 /** X coordinate of the touch point relative to the left edge of the screen. */ 229 float screenX; 230 /** Y coordinate of the touch point relative to the upper edge of the screen. */ 231 float screenY; 232 /** X coordinate of the touch point relative to the left edge of the element to touch. */ 233 float x; 234 /** Y coordinate of the touch point relative to the upper edge of the element to touch. */ 235 float y; 236 /** Touch type of the touch event. */ 237 OH_NativeXComponent_TouchEventType type; 238 /** Contact area between the finger pad and the screen. */ 239 double size; 240 /** Pressure of the current touch event. */ 241 float force; 242 /** Timestamp of the current touch event. */ 243 int64_t timeStamp; 244 /** The angle betweenprojection on plane-X-Y and axis-Z of the current touch event. */ 245 float titlX; 246 /** The angle betweenprojection on plane-Y-Z and axis-Z of the current touch event. */ 247 float titlY; 248 /** The sourceTool of the current touch event. */ 249 OH_NativeXComponent_TouchEvent_SourceTool sourceTool; 250 } OH_NativeXComponent_HistoricalPoint; 251 252 /** 253 * @brief Represents the touch point information of touch event. 254 * 255 * @since 8 256 * @version 1.0 257 */ 258 typedef struct { 259 /** Unique identifier of a finger. */ 260 int32_t id; 261 /** X coordinate of the touch point relative to the left edge of the screen. */ 262 float screenX; 263 /** Y coordinate of the touch point relative to the upper edge of the screen. */ 264 float screenY; 265 /** X coordinate of the touch point relative to the left edge of the element to touch. */ 266 float x; 267 /** Y coordinate of the touch point relative to the upper edge of the element to touch. */ 268 float y; 269 /** Touch type of the touch event. */ 270 OH_NativeXComponent_TouchEventType type; 271 /** Contact area between the finger pad and the screen. */ 272 double size; 273 /** Pressure of the current touch event. */ 274 float force; 275 /** Timestamp of the current touch event. */ 276 int64_t timeStamp; 277 /** Whether the current point is pressed. */ 278 bool isPressed; 279 } OH_NativeXComponent_TouchPoint; 280 281 /** 282 * @brief Represents the touch event. 283 * 284 * @since 8 285 * @version 1.0 286 */ 287 typedef struct { 288 /** Unique identifier of a finger. */ 289 int32_t id; 290 /** X coordinate of the touch point relative to the left edge of the screen. */ 291 float screenX; 292 /** Y coordinate of the touch point relative to the upper edge of the screen. */ 293 float screenY; 294 /** X coordinate of the touch point relative to the left edge of the element to touch. */ 295 float x; 296 /** Y coordinate of the touch point relative to the upper edge of the element to touch. */ 297 float y; 298 /** Touch type of the touch event. */ 299 OH_NativeXComponent_TouchEventType type; 300 /** Contact area between the finger pad and the screen. */ 301 double size; 302 /** Pressure of the current touch event. */ 303 float force; 304 /** ID of the device where the current touch event is generated. */ 305 int64_t deviceId; 306 /** Timestamp of the current touch event. */ 307 int64_t timeStamp; 308 /** Array of the current touch points. */ 309 OH_NativeXComponent_TouchPoint touchPoints[OH_NATIVE_XCOMPONENT_MAX_TOUCH_POINTS_NUMBER]; 310 /** Number of current touch points. */ 311 uint32_t numPoints; 312 } OH_NativeXComponent_TouchEvent; 313 314 /** 315 * @brief Represents the mouse event information. 316 * 317 * @since 9 318 * @version 1.0 319 */ 320 typedef struct { 321 /** X coordinate of the mouse point relative to the left edge of the element to mouse. */ 322 float x; 323 /** Y coordinate of the mouse point relative to the upper edge of the element to mouse. */ 324 float y; 325 /** X coordinate of the mouse point relative to the left edge of the screen. */ 326 float screenX; 327 /** Y coordinate of the mouse point relative to the upper edge of the screen. */ 328 float screenY; 329 /** Timestamp of the current mouse event. */ 330 int64_t timestamp; 331 /** Mouse event action. */ 332 OH_NativeXComponent_MouseEventAction action; 333 /** Mouse event button. */ 334 OH_NativeXComponent_MouseEventButton button; 335 } OH_NativeXComponent_MouseEvent; 336 337 /** 338 * @brief Provides an encapsulated <b>OH_NativeXComponent</b> instance. 339 * 340 * @since 8 341 * @version 1.0 342 */ 343 typedef struct OH_NativeXComponent OH_NativeXComponent; 344 345 /** 346 * @brief Registers the surface lifecycle and touch event callbacks. 347 * 348 * @since 8 349 * @version 1.0 350 */ 351 typedef struct OH_NativeXComponent_Callback { 352 /** Called when the surface is created. */ 353 void (*OnSurfaceCreated)(OH_NativeXComponent* component, void* window); 354 /** Called when the surface is changed. */ 355 void (*OnSurfaceChanged)(OH_NativeXComponent* component, void* window); 356 /** Called when the surface is destroyed. */ 357 void (*OnSurfaceDestroyed)(OH_NativeXComponent* component, void* window); 358 /** Called when a touch event is triggered. */ 359 void (*DispatchTouchEvent)(OH_NativeXComponent* component, void* window); 360 } OH_NativeXComponent_Callback; 361 362 /** 363 * @brief Registers the mouse event callbacks. 364 * 365 * @since 9 366 * @version 1.0 367 */ 368 typedef struct OH_NativeXComponent_MouseEvent_Callback { 369 /** Called when a mouse event is triggered. */ 370 void (*DispatchMouseEvent)(OH_NativeXComponent* component, void* window); 371 /** Called when a hover event is triggered. */ 372 void (*DispatchHoverEvent)(OH_NativeXComponent* component, bool isHover); 373 } OH_NativeXComponent_MouseEvent_Callback; 374 375 struct OH_NativeXComponent_KeyEvent; 376 /** 377 * @brief Provides an encapsulated <b>OH_NativeXComponent_KeyEvent</b> instance. 378 * 379 * @since 10 380 * @version 1.0 381 */ 382 typedef struct OH_NativeXComponent_KeyEvent OH_NativeXComponent_KeyEvent; 383 384 /** 385 * @brief Defines the expected frame rate range struct. 386 * 387 * @since 11 388 * @version 1.0 389 */ 390 typedef struct { 391 /** The minimum frame rate of dynamical callback rate range. */ 392 int32_t min; 393 /** The maximum frame rate of dynamical callback rate range. */ 394 int32_t max; 395 /** The expected frame rate of dynamical callback rate range. */ 396 int32_t expected; 397 } OH_NativeXComponent_ExpectedRateRange; 398 399 /** 400 * @brief Obtains the ID of the ArkUI XComponent. 401 * 402 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 403 * @param id Indicates the char buffer to keep the ID of this <b>OH_NativeXComponent</b> instance.\n 404 * Notice that a null-terminator will be appended to the char buffer, so the size of the\n 405 * char buffer should be at least as large as the size of the real id length plus 1.\n 406 * It is recommended that the size of the char buffer be [OH_XCOMPONENT_ID_LEN_MAX + 1]. 407 * @param size Indicates the pointer to the length of <b>id</b>, which you can receive. 408 * @return Returns the status code of the execution. 409 * @since 8 410 * @version 1.0 411 */ 412 int32_t OH_NativeXComponent_GetXComponentId(OH_NativeXComponent* component, char* id, uint64_t* size); 413 414 /** 415 * @brief Obtains the size of the surface held by the ArkUI XComponent. 416 * 417 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 418 * @param window Indicates the native window handler. 419 * @param width Indicates the pointer to the width of the current surface. 420 * @param height Indicates the pointer to the height of the current surface. 421 * @return Returns the status code of the execution. 422 * @since 8 423 * @version 1.0 424 */ 425 int32_t OH_NativeXComponent_GetXComponentSize( 426 OH_NativeXComponent* component, const void* window, uint64_t* width, uint64_t* height); 427 428 /** 429 * @brief Obtains the offset of the surface held by the ArkUI XComponent. 430 * 431 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 432 * @param window Indicates the native window handler. 433 * @param x Indicates the pointer to the x coordinate of the current surface. 434 * @param y Indicates the pointer to the y coordinate of the current surface. 435 * @return Returns the status code of the execution. 436 * @since 8 437 * @version 1.0 438 */ 439 int32_t OH_NativeXComponent_GetXComponentOffset( 440 OH_NativeXComponent* component, const void* window, double* x, double* y); 441 442 /** 443 * @brief Obtains the touch event dispatched by the ArkUI XComponent. 444 * 445 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 446 * @param window Indicates the native window handler. 447 * @param touchEvent Indicates the pointer to the current touch event. 448 * @return Returns the status code of the execution. 449 * @since 8 450 * @version 1.0 451 */ 452 int32_t OH_NativeXComponent_GetTouchEvent( 453 OH_NativeXComponent* component, const void* window, OH_NativeXComponent_TouchEvent* touchEvent); 454 455 /** 456 * @brief Obtains the touch pointer tool type by the ArkUI XComponent. 457 * 458 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 459 * @param pointIndex Indicates the pointer index in the touchPoints. 460 * @param toolType Indicates the tool Type of the pointer. 461 * @return Returns the status code of the execution. 462 * @since 9 463 * @version 1.0 464 */ 465 int32_t OH_NativeXComponent_GetTouchPointToolType( 466 OH_NativeXComponent* component, uint32_t pointIndex, OH_NativeXComponent_TouchPointToolType* toolType); 467 468 /** 469 * @brief Obtains the touch pointer tiltX by the ArkUI XComponent. 470 * 471 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 472 * @param pointIndex Indicates the pointer index in the touchPoints. 473 * @param tiltX Indicates the x tilt of the pointer. 474 * @return Returns the status code of the execution. 475 * @since 9 476 * @version 1.0 477 */ 478 int32_t OH_NativeXComponent_GetTouchPointTiltX(OH_NativeXComponent* component, uint32_t pointIndex, float* tiltX); 479 480 /** 481 * @brief Obtains the touch pointer tiltX by the ArkUI XComponent. 482 * 483 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 484 * @param pointIndex Indicates the pointer index in the touchPoints. 485 * @param tiltY Indicates the y tilt of the pointer. 486 * @return Returns the status code of the execution. 487 * @since 9 488 * @version 1.0 489 */ 490 int32_t OH_NativeXComponent_GetTouchPointTiltY(OH_NativeXComponent* component, uint32_t pointIndex, float* tiltY); 491 492 /** 493 * @brief Obtains the x coordinate of a specific touch point relative to the upper left corner of\n 494 * the current application window from the ArkUI XComponent. 495 * 496 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 497 * @param pointIndex Indicates the pointer index in the touchPoints. 498 * @param windowX Indicates the x coordinate relative to the upper left corner of the current\n 499 application window. 500 * @return Returns the status code of the execution. 501 * {@link OH_NATIVEXCOMPONENT_RESULT_SUCCESS} get windowX success. 502 * {@link OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER} component is NULL, windowX is NULL\n 503 * or native XComponent is NULL. 504 * @since 12 505 * @version 1.0 506 */ 507 int32_t OH_NativeXComponent_GetTouchPointWindowX(OH_NativeXComponent* component, uint32_t pointIndex, float* windowX); 508 509 /** 510 * @brief Obtains the y coordinate of a specific touch point relative to the upper left corner of\n 511 * the current application window from the ArkUI XComponent. 512 * 513 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 514 * @param pointIndex Indicates the pointer index in the touchPoints. 515 * @param windowY Indicates the y coordinate relative to the upper left corner of the current\n 516 application window. 517 * @return Returns the status code of the execution. 518 * {@link OH_NATIVEXCOMPONENT_RESULT_SUCCESS} get windowY success. 519 * {@link OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER} component is NULL, windowY is NULL\n 520 * or native XComponent is NULL. 521 * @since 12 522 * @version 1.0 523 */ 524 int32_t OH_NativeXComponent_GetTouchPointWindowY(OH_NativeXComponent* component, uint32_t pointIndex, float* windowY); 525 526 /** 527 * @brief Obtains the x coordinate of a specific touch point relative to the upper left corner of\n 528 * the current screen from the ArkUI XComponent. 529 * 530 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 531 * @param pointIndex Indicates the pointer index in the touchPoints. 532 * @param displayX Indicates the x coordinate relative to the upper left corner of the current\n 533 screen. 534 * @return Returns the status code of the execution. 535 * {@link OH_NATIVEXCOMPONENT_RESULT_SUCCESS} get displayX success. 536 * {@link OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER} component is NULL, displayX is NULL\n 537 * or native XComponent is NULL. 538 * @since 12 539 * @version 1.0 540 */ 541 int32_t OH_NativeXComponent_GetTouchPointDisplayX(OH_NativeXComponent* component, uint32_t pointIndex, float* displayX); 542 543 /** 544 * @brief Obtains the y coordinate of a specific touch point relative to the upper left corner of\n 545 * the current screen from the ArkUI XComponent. 546 * 547 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 548 * @param pointIndex Indicates the pointer index in the touchPoints. 549 * @param displayY Indicates the y coordinate relative to the upper left corner of the current\n 550 screen. 551 * @return Returns the status code of the execution. 552 * {@link OH_NATIVEXCOMPONENT_RESULT_SUCCESS} get displayY success. 553 * {@link OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER} component is NULL, displayY is NULL\n 554 * or native XComponent is NULL. 555 * @since 12 556 * @version 1.0 557 */ 558 int32_t OH_NativeXComponent_GetTouchPointDisplayY(OH_NativeXComponent* component, uint32_t pointIndex, float* displayY); 559 560 /** 561 * @brief Obtains the touch event dispatched by the ArkUI XComponent. 562 * 563 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 564 * @param window Indicates the native window handler. 565 * @param size Length of the historical touch point array. 566 * @param historicalPoints Pointer to the historical touch point array. 567 * @return Returns the status code of the execution. 568 * @since 10 569 * @version 1.0 570 */ 571 int32_t OH_NativeXComponent_GetHistoricalPoints(OH_NativeXComponent* component, const void* window, 572 int32_t* size, OH_NativeXComponent_HistoricalPoint** historicalPoints); 573 574 /** 575 * @brief Obtains the mouse event dispatched by the ArkUI XComponent. 576 * 577 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 578 * @param window Indicates the native window handler. 579 * @param mouseEvent Indicates the pointer to the current mouse event. 580 * @return Returns the status code of the execution. 581 * @since 9 582 * @version 1.0 583 */ 584 int32_t OH_NativeXComponent_GetMouseEvent( 585 OH_NativeXComponent* component, const void* window, OH_NativeXComponent_MouseEvent* mouseEvent); 586 587 /** 588 * @brief Registers a callback for this <b>OH_NativeXComponent</b> instance. 589 * 590 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 591 * @param callback Indicates the pointer to a surface lifecycle and touch event callback. 592 * @return Returns the status code of the execution. 593 * @since 8 594 * @version 1.0 595 */ 596 int32_t OH_NativeXComponent_RegisterCallback(OH_NativeXComponent* component, OH_NativeXComponent_Callback* callback); 597 598 /** 599 * @brief Registers a callback for this <b>OH_NativeXComponent</b> instance. 600 * 601 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 602 * @param callback Indicates the pointer to a mouse event callback. 603 * @return Returns the status code of the execution. 604 * @since 9 605 * @version 1.0 606 */ 607 int32_t OH_NativeXComponent_RegisterMouseEventCallback( 608 OH_NativeXComponent* component, OH_NativeXComponent_MouseEvent_Callback* callback); 609 610 /** 611 * @brief Provides an encapsulated <b>OH_NativeXComponent_ExtraMouseEventInfo</b> 612 * instance which has extra info compared to OH_NativeXComponent_MouseEvent. 613 * 614 * @since 20 615 * @version 1.0 616 */ 617 typedef struct OH_NativeXComponent_ExtraMouseEventInfo OH_NativeXComponent_ExtraMouseEventInfo; 618 619 /** 620 * @brief Obtains the extra mouse event dispatched by the ArkUI XComponent. 621 * 622 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 623 * @param extraMouseEventInfo Indicates the pointer to pointer of <b>OH_NativeXComponent_ExtraMouseEventInfo</b> instance. 624 * @return Returns the status code of the execution. 625 * {@link ARKUI_ERROR_CODE_NO_ERROR} the execution is successful. 626 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 627 * @since 20 628 * @version 1.0 629 */ 630 int32_t OH_NativeXComponent_GetExtraMouseEventInfo(OH_NativeXComponent* component, OH_NativeXComponent_ExtraMouseEventInfo** extraMouseEventInfo); 631 632 /** 633 * @brief Obtains the state of the modifier keys of the mouse event. 634 * 635 * @param extraMouseEventInfo Indicates the pointer to this <b>OH_NativeXComponent_ExtraMouseEventInfo</b> instance. 636 * @param keys Pointer to a variable where the current combination of pressed modifier keys will be returned. 637 * The application can use bitwise operations to determine the state of each modifier key. 638 * Modifier keys can be referred to {@link ArkUI_ModifierKeyName}. 639 * @return Returns the result code. 640 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 641 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 642 * @since 20 643 * @version 1.0 644 */ 645 int32_t OH_NativeXComponent_GetMouseEventModifierKeyStates( 646 OH_NativeXComponent_ExtraMouseEventInfo* extraMouseEventInfo, uint64_t* keys); 647 648 /** 649 * @brief Registers a callback for this <b>OH_NativeXComponent</b> instance. 650 * 651 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 652 * @param callback Indicates the pointer to a focus event callback. 653 * @return Returns the status code of the execution. 654 * @since 10 655 * @version 1.0 656 */ 657 int32_t OH_NativeXComponent_RegisterFocusEventCallback( 658 OH_NativeXComponent* component, void (*callback)(OH_NativeXComponent* component, void* window)); 659 660 /** 661 * @brief Registers a callback for this <b>OH_NativeXComponent</b> instance. 662 * 663 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 664 * @param callback Indicates the pointer to a key event callback. 665 * @return Returns the status code of the execution. 666 * @since 10 667 * @version 1.0 668 */ 669 int32_t OH_NativeXComponent_RegisterKeyEventCallback( 670 OH_NativeXComponent* component, void (*callback)(OH_NativeXComponent* component, void* window)); 671 672 /** 673 * @brief Registers a callback for this <b>OH_NativeXComponent</b> instance. 674 * 675 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 676 * @param callback Indicates the pointer to a blur event callback. 677 * @return Returns the status code of the execution. 678 * @since 10 679 * @version 1.0 680 */ 681 int32_t OH_NativeXComponent_RegisterBlurEventCallback( 682 OH_NativeXComponent* component, void (*callback)(OH_NativeXComponent* component, void* window)); 683 684 /** 685 * @brief Obtains the key event dispatched by the ArkUI XComponent. 686 * 687 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 688 * @param keyEvent Indicates the pointer to pointer of <b>OH_NativeXComponent_KeyEvent</b> instance. 689 * @return Returns the status code of the execution. 690 * @since 10 691 * @version 1.0 692 */ 693 int32_t OH_NativeXComponent_GetKeyEvent(OH_NativeXComponent* component, OH_NativeXComponent_KeyEvent** keyEvent); 694 695 /** 696 * @brief Obtains the action of the key event. 697 * 698 * @param keyEvent Indicates the pointer to this <b>OH_NativeXComponent_KeyEvent</b> instance. 699 * @param action Indicates the action of the <b>OH_NativeXComponent_KeyEvent</b> instance. 700 * @return Returns the status code of the execution. 701 * @since 10 702 * @version 1.0 703 */ 704 int32_t OH_NativeXComponent_GetKeyEventAction( 705 OH_NativeXComponent_KeyEvent* keyEvent, OH_NativeXComponent_KeyAction* action); 706 707 /** 708 * @brief Obtains the keyCode of the key event. 709 * 710 * @param keyEvent Indicates the pointer to this <b>OH_NativeXComponent_KeyEvent</b> instance. 711 * @param code Indicates the keyCode of the <b>OH_NativeXComponent_KeyEvent</b> instance. 712 * @return Returns the status code of the execution. 713 * @since 10 714 * @version 1.0 715 */ 716 int32_t OH_NativeXComponent_GetKeyEventCode(OH_NativeXComponent_KeyEvent* keyEvent, OH_NativeXComponent_KeyCode* code); 717 718 /** 719 * @brief Obtains the sourceType of the key event. 720 * 721 * @param keyEvent Indicates the pointer to this <b>OH_NativeXComponent_KeyEvent</b> instance. 722 * @param sourceType Indicates the sourceType of the <b>OH_NativeXComponent_KeyEvent</b> instance. 723 * @return Returns the status code of the execution. 724 * @since 10 725 * @version 1.0 726 */ 727 int32_t OH_NativeXComponent_GetKeyEventSourceType( 728 OH_NativeXComponent_KeyEvent* keyEvent, OH_NativeXComponent_EventSourceType* sourceType); 729 730 /** 731 * @brief Obtains the deviceId of the key event. 732 * 733 * @param keyEvent Indicates the pointer to this <b>OH_NativeXComponent_KeyEvent</b> instance. 734 * @param deviceId Indicates the deviceId of the <b>OH_NativeXComponent_KeyEvent</b> instance. 735 * @return Returns the status code of the execution. 736 * @since 10 737 * @version 1.0 738 */ 739 int32_t OH_NativeXComponent_GetKeyEventDeviceId(OH_NativeXComponent_KeyEvent* keyEvent, int64_t* deviceId); 740 741 /** 742 * @brief Obtains the timestamp of the key event. 743 * 744 * @param keyEvent Indicates the pointer to this <b>OH_NativeXComponent_KeyEvent</b> instance. 745 * @param timestamp Indicates the timestamp of the <b>OH_NativeXComponent_KeyEvent</b> instance. 746 * @return Returns the status code of the execution. 747 * @since 10 748 * @version 1.0 749 */ 750 int32_t OH_NativeXComponent_GetKeyEventTimestamp(OH_NativeXComponent_KeyEvent* keyEvent, int64_t* timestamp); 751 752 /** 753 * @brief Obtains the state of the modifier keys of the key event. 754 * 755 * @param keyEvent Indicates the pointer to this <b>OH_NativeXComponent_KeyEvent</b> instance. 756 * @param keys Pointer to a variable where the current combination of pressed modifier keys will be returned. 757 * The application can use bitwise operations to determine the state of each modifier key. 758 * Modifier keys can be referred to {@link ArkUI_ModifierKeyName}. 759 * @return Returns the result code. 760 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 761 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 762 * @since 20 763 * @version 1.0 764 */ 765 int32_t OH_NativeXComponent_GetKeyEventModifierKeyStates(OH_NativeXComponent_KeyEvent* keyEvent, uint64_t* keys); 766 767 /** 768 * @brief Obtains the Num Lock state of the key event. 769 * 770 * @param keyEvent Indicates the pointer to this <b>OH_NativeXComponent_KeyEvent</b> instance. 771 * @param isNumLockOn Return whether the Num Lock is on. 772 * @return Returns the result code. 773 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 774 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 775 * @since 20 776 * @version 1.0 777 */ 778 int32_t OH_NativeXComponent_GetKeyEventNumLockState(OH_NativeXComponent_KeyEvent* keyEvent, bool* isNumLockOn); 779 780 /** 781 * @brief Obtains the Caps Lock state of the key event. 782 * 783 * @param keyEvent Indicates the pointer to this <b>OH_NativeXComponent_KeyEvent</b> instance. 784 * @param isCapsLockOn Return whether the Caps Lock is on. 785 * @return Returns the result code. 786 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 787 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 788 * @since 20 789 * @version 1.0 790 */ 791 int32_t OH_NativeXComponent_GetKeyEventCapsLockState(OH_NativeXComponent_KeyEvent* keyEvent, bool* isCapsLockOn); 792 793 /** 794 * @brief Obtains the Scroll Lock state of the key event. 795 * 796 * @param keyEvent Indicates the pointer to this <b>OH_NativeXComponent_KeyEvent</b> instance. 797 * @param isScrollLockOn Return whether the Scroll Lock is on. 798 * @return Returns the result code. 799 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 800 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 801 * @since 20 802 * @version 1.0 803 */ 804 int32_t OH_NativeXComponent_GetKeyEventScrollLockState(OH_NativeXComponent_KeyEvent* keyEvent, bool* isScrollLockOn); 805 806 /** 807 * @brief Set the Expected FrameRateRange. 808 * 809 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 810 * @param range Indicates the pointer to a expected rate range. 811 * @return Returns the status code of the execution. 812 * @since 11 813 * @version 1.0 814 */ 815 int32_t OH_NativeXComponent_SetExpectedFrameRateRange( 816 OH_NativeXComponent* component, OH_NativeXComponent_ExpectedRateRange* range); 817 818 /** 819 * @brief Registers a callback for this <b>OH_NativeXComponent</b> instance. 820 * 821 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 822 * @param callback Indicates the pointer to a onFrame callback. 823 * @return Returns the status code of the execution. 824 * @since 11 825 * @version 1.0 826 */ 827 int32_t OH_NativeXComponent_RegisterOnFrameCallback(OH_NativeXComponent* component, 828 void (*callback)(OH_NativeXComponent* component, uint64_t timestamp, uint64_t targetTimestamp)); 829 830 /** 831 * @brief UnRegister a callback for this <b>OH_NativeXComponent</b> instance. 832 * 833 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 834 * @return Returns the status code of the execution. 835 * @since 11 836 * @version 1.0 837 */ 838 int32_t OH_NativeXComponent_UnregisterOnFrameCallback(OH_NativeXComponent* component); 839 840 /** 841 * @brief Attaches the UI component created through the native API of ArkUI to this <b>OH_NativeXComponent</b> instance. 842 * 843 * @param component Indicates the pointer to the <b>OH_NativeXComponent</b> instance. 844 * @param root Indicates the pointer to the component instance created by the native API. 845 * @return Returns the error code. 846 * Returns {@link OH_NATIVEXCOMPONENT_RESULT_SUCCESS} if the operation is successful. 847 * Returns {@link OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER} if a parameter error occurs. 848 * 849 * @since 12 850 * @deprecated since 20 851 * @useinstead OH_ArkUI_NodeContent_AddNode 852 */ 853 int32_t OH_NativeXComponent_AttachNativeRootNode(OH_NativeXComponent* component, ArkUI_NodeHandle root); 854 855 /** 856 * @brief Detaches the native component of ArkUI from this <b>OH_NativeXComponent</b> instance. 857 * 858 * @param component Indicates the pointer to the <b>OH_NativeXComponent</b> instance. 859 * @param root Indicates the pointer to the component instance created by the native API. 860 * @return Returns the error code. 861 * Returns {@link OH_NATIVEXCOMPONENT_RESULT_SUCCESS} if the operation is successful. 862 * Returns {@link OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER} if a parameter error occurs. 863 * 864 * @since 12 865 * @deprecated since 20 866 * @useinstead OH_ArkUI_NodeContent_RemoveNode 867 */ 868 int32_t OH_NativeXComponent_DetachNativeRootNode(OH_NativeXComponent* component, ArkUI_NodeHandle root); 869 870 /** 871 * @brief Registers a callback for this <b>OH_NativeXComponent</b> instance. 872 * 873 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 874 * @param callback Indicates the pointer to a surface show event callback. 875 * @return Returns the status code of the execution. 876 * @since 12 877 * @version 1.0 878 */ 879 int32_t OH_NativeXComponent_RegisterSurfaceShowCallback( 880 OH_NativeXComponent* component, void (*callback)(OH_NativeXComponent* component, void* window)); 881 882 /** 883 * @brief Registers a callback for this <b>OH_NativeXComponent</b> instance. 884 * 885 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 886 * @param callback Indicates the pointer to a surface hide event callback. 887 * @return Returns the status code of the execution. 888 * @since 12 889 * @version 1.0 890 */ 891 int32_t OH_NativeXComponent_RegisterSurfaceHideCallback( 892 OH_NativeXComponent* component, void (*callback)(OH_NativeXComponent* component, void* window)); 893 894 /** 895 * @brief Registers a UI input event callback for an <b>OH_NativeXComponent</b> instance and enables the callback to be 896 * invoked when a UI input event is received. Currently, only axis events are supported. 897 * 898 * @param component Indicates the pointer to the <b>OH_NativeXComponent</b> instance. 899 * @param callback Indicates the pointer to the UI input event callback. 900 * @param type Indicates the type of the current UI input event. 901 * @return Returns the error code. 902 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 903 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 904 * @since 12 905 */ 906 int32_t OH_NativeXComponent_RegisterUIInputEventCallback( 907 OH_NativeXComponent* component, 908 void (*callback)(OH_NativeXComponent* component, ArkUI_UIInputEvent* event, 909 ArkUI_UIInputEvent_Type type), 910 ArkUI_UIInputEvent_Type type); 911 912 /** 913 * @brief Set whether the <b>OH_NativeXComponent</b> instance needs soft keyboard. 914 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 915 * @param needSoftKeyboard Indicates whether the <b>OH_NativeXComponent</b> instance needs soft keyboard or not. 916 * Default value is false. 917 * @return Returns the status code of the execution. 918 * @since 12 919 * @version 1.0 920 */ 921 int32_t OH_NativeXComponent_SetNeedSoftKeyboard(OH_NativeXComponent* component, bool needSoftKeyboard); 922 923 /** 924 * @brief Registers a custom event intercept callback for an <b>OH_NativeXComponent</b> instance. 925 * This enables the specified during hit testing. 926 * UI input-related operations are not supported on event objects received through this callback. 927 * For full functionality, use the <b>NODE_ON_TOUCH_INTERCEPT</b> event on native nodes instead. 928 * 929 * @param component Indicates the pointer to the <b>OH_NativeXComponent</b> instance. 930 * @param callback Indicates the pointer to the custom event intercept callback. 931 * @return Returns the error code. 932 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 933 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 934 * @since 12 935 */ 936 int32_t OH_NativeXComponent_RegisterOnTouchInterceptCallback( 937 OH_NativeXComponent* component, HitTestMode (*callback)(OH_NativeXComponent* component, ArkUI_UIInputEvent* event)); 938 939 /** 940 * @brief Obtains the touch event's source type dispatched by the ArkUI XComponent. 941 * 942 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 943 * @param pointId Indicates the id of the touch point which triggers this touch event. 944 * @param sourceType Indicates the source type of this touch event. 945 * @return Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if success. 946 * Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter exception occurs. 947 * Returns OH_NATIVEXCOMPONENT_RESULT_FAILED if other exceptions occur. 948 * @since 12 949 * @version 1.0 950 */ 951 int32_t OH_NativeXComponent_GetTouchEventSourceType( 952 OH_NativeXComponent* component, int32_t pointId, OH_NativeXComponent_EventSourceType* sourceType); 953 954 /** 955 * @brief Obtains the pointer to an <b>OH_NativeXComponent</b> instance based on the specified component 956 * instance created by the native API. 957 * 958 * @param node Indicates the pointer to the component instance created by the native API. 959 * @return Returns the pointer to the <b>OH_NativeXComponent</b> instance. 960 * @since 12 961 * @version 1.0 962 */ 963 OH_NativeXComponent* OH_NativeXComponent_GetNativeXComponent(ArkUI_NodeHandle node); 964 965 /** 966 * @brief Obtains the pointer to the <b> ArkUI_AccessibilityProvider</b> 967 * instance of this <b>OH_NativeXComponent</b> instance. 968 * 969 * @param component Indicates the pointer to the <b>OH_NativeXComponent</b> instance. 970 * @param handle Indicates the pointer to the <b>ArkUI_AccessibilityProvider</b> instance. 971 * @return Returns {@link OH_NATIVEXCOMPONENT_RESULT_SUCCESS} if the operation is successful. 972 * Returns {@link OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER} if a parameter error occurs. 973 * @since 13 974 */ 975 int32_t OH_NativeXComponent_GetNativeAccessibilityProvider( 976 OH_NativeXComponent* component, ArkUI_AccessibilityProvider** handle); 977 978 /** 979 * @brief Registers a callback for this <b>OH_NativeXComponent</b> instance. 980 * 981 * @param component Indicates the pointer to this <b>OH_NativeXComponent</b> instance. 982 * @param callback Indicates the pointer to a key event callback with result. 983 * @return Returns the status code of the execution. 984 * {@link OH_NATIVEXCOMPONENT_RESULT_SUCCESS} the callback function is successfully registered.\n 985 * {@link OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER} component is nullptr or callback is nullptr.\n 986 * @since 14 987 * @version 1.0 988 */ 989 int32_t OH_NativeXComponent_RegisterKeyEventCallbackWithResult( 990 OH_NativeXComponent* component, bool (*callback)(OH_NativeXComponent* component, void* window)); 991 992 /** 993 * @brief Start image analyzer for the specified XComponent 994 * instance created by the native API. 995 * 996 * @param node Indicates the pointer to the XComponent instance created by the native API. 997 * @param userData Indicates the pointer to a user defined data. 998 * @param callback Indicates the pointer to a image analyzer status callback function. 999 * @return Returns the status code of the execution. 1000 * {@link ARKUI_ERROR_CODE_NO_ERROR} the execution is successful.\n 1001 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} component is nullptr or callback is nullptr, 1002 * or the type of node is not XComponent.\n 1003 * @since 18 1004 */ 1005 int32_t OH_ArkUI_XComponent_StartImageAnalyzer(ArkUI_NodeHandle node, void* userData, 1006 void (*callback)(ArkUI_NodeHandle node, ArkUI_XComponent_ImageAnalyzerState statusCode, void* userData)); 1007 1008 /** 1009 * @brief Stop image analyzer for the specified XComponent 1010 * instance created by the native API. 1011 * 1012 * @param node Indicates the pointer to the XComponent instance created by the native API. 1013 * @return Returns the status code of the execution. 1014 * {@link ARKUI_ERROR_CODE_NO_ERROR} the execution is successful.\n 1015 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} component is nullptr or the type of node is not XComponent.\n 1016 * @since 18 1017 */ 1018 int32_t OH_ArkUI_XComponent_StopImageAnalyzer(ArkUI_NodeHandle node); 1019 1020 /** 1021 * @brief Provides an encapsulated <b>OH_ArkUI_SurfaceHolder</b> instance. 1022 * 1023 * @since 19 1024 */ 1025 typedef struct OH_ArkUI_SurfaceHolder OH_ArkUI_SurfaceHolder; 1026 1027 /** 1028 * @brief Create a <b>OH_ArkUI_SurfaceHolder</b> object from an XComponent node. 1029 * 1030 * @param node Indicates the pointer to the XComponent node. 1031 * @return Returns the created <b>OH_ArkUI_SurfaceHolder</b> object's pointer. 1032 * @since 19 1033 */ 1034 OH_ArkUI_SurfaceHolder* OH_ArkUI_SurfaceHolder_Create(ArkUI_NodeHandle node); 1035 1036 /** 1037 * @brief Disposes of a <b>OH_ArkUI_SurfaceHolder</b> object. 1038 * 1039 * @param node Indicates the pointer to <b>OH_ArkUI_SurfaceHolder</b> object needed to dispose. 1040 * @since 19 1041 */ 1042 void OH_ArkUI_SurfaceHolder_Dispose(OH_ArkUI_SurfaceHolder* surfaceHolder); 1043 1044 /** 1045 * @brief Saves custom data on the <b>OH_ArkUI_SurfaceHolder</b> instance. 1046 * 1047 * @param surfaceHolder Indicates the <b>OH_ArkUI_SurfaceHolder</b> instance 1048 * on which the custom data will be saved. 1049 * @param userData Indicates the custom data to be saved. 1050 * @return Returns the error code. 1051 * Returns {@link ARKUI_ERROR_CODE_NO_ERROR} if the operation is successful. 1052 * Returns {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 1053 * @since 19 1054 */ 1055 int32_t OH_ArkUI_SurfaceHolder_SetUserData(OH_ArkUI_SurfaceHolder* surfaceHolder, void* userData); 1056 1057 /** 1058 * @brief Obtains the custom data saved on the <b>OH_ArkUI_SurfaceHolder</b> instance. 1059 * 1060 * @param surfaceHolder Indicates the target <b>OH_ArkUI_SurfaceHolder</b> instance. 1061 * @return Returns the custom data. 1062 * @since 19 1063 */ 1064 void* OH_ArkUI_SurfaceHolder_GetUserData(OH_ArkUI_SurfaceHolder* surfaceHolder); 1065 1066 /** 1067 * @brief Define the surface lifecycle callback. 1068 * 1069 * @since 19 1070 */ 1071 typedef struct OH_ArkUI_SurfaceCallback OH_ArkUI_SurfaceCallback; 1072 1073 /** 1074 * @brief Create a <b>OH_ArkUI_SurfaceCallback</b> object. 1075 * 1076 * @return Returns the created <b>OH_ArkUI_SurfaceCallback</b> object's pointer. 1077 * @since 19 1078 */ 1079 OH_ArkUI_SurfaceCallback* OH_ArkUI_SurfaceCallback_Create(); 1080 1081 /** 1082 * @brief Disposes of a <b>OH_ArkUI_SurfaceCallback</b> object. 1083 * 1084 * @param callback Indicates the pointer to <b>OH_ArkUI_SurfaceCallback</b> object needed to dispose. 1085 * @since 19 1086 */ 1087 void OH_ArkUI_SurfaceCallback_Dispose(OH_ArkUI_SurfaceCallback* callback); 1088 1089 /** 1090 * @brief Set the surface created event of the surface callback. 1091 * 1092 * @param callback Indicated the pointer to the surface callback. 1093 * @param onSurfaceCreated Indicates the surface created callback event 1094 * which will called when the surface is created. 1095 * @since 19 1096 */ 1097 void OH_ArkUI_SurfaceCallback_SetSurfaceCreatedEvent( 1098 OH_ArkUI_SurfaceCallback* callback, 1099 void (*onSurfaceCreated)(OH_ArkUI_SurfaceHolder* surfaceHolder)); 1100 1101 /** 1102 * @brief Set the surface changed event of the surface callback. 1103 * 1104 * @param callback Indicated the pointer to the surface callback. 1105 * @param onSurfaceChanged Indicates the surface changed callback event 1106 * which will called when the surface is changed. 1107 * @since 19 1108 */ 1109 void OH_ArkUI_SurfaceCallback_SetSurfaceChangedEvent( 1110 OH_ArkUI_SurfaceCallback* callback, 1111 void (*onSurfaceChanged)(OH_ArkUI_SurfaceHolder* surfaceHolder, uint64_t width, uint64_t height)); 1112 1113 /** 1114 * @brief Set the surface destroyed event of the surface callback. 1115 * 1116 * @param callback Indicated the pointer to the surface callback. 1117 * @param onSurfaceDestroyed Indicates the surface destroyed callback event 1118 * which will called when the surface is destroyed. 1119 * @since 19 1120 */ 1121 void OH_ArkUI_SurfaceCallback_SetSurfaceDestroyedEvent( 1122 OH_ArkUI_SurfaceCallback* callback, 1123 void (*onSurfaceDestroyed)(OH_ArkUI_SurfaceHolder* surfaceHolder)); 1124 1125 /** 1126 * @brief Adds a surface lifecycle callback for this <b>OH_ArkUI_SurfaceHolder</b> instance. 1127 * 1128 * @param surfaceHolder Indicates the pointer to this <b>OH_ArkUI_SurfaceHolder</b> instance. 1129 * @param callback Indicates the pointer to this new callback. 1130 * @return Returns the status code of the execution. 1131 * {@link ARKUI_ERROR_CODE_NO_ERROR} the execution is successful. 1132 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 1133 * @since 19 1134 */ 1135 int32_t OH_ArkUI_SurfaceHolder_AddSurfaceCallback( 1136 OH_ArkUI_SurfaceHolder* surfaceHolder, 1137 OH_ArkUI_SurfaceCallback* callback); 1138 1139 /** 1140 * @brief Removes a previously added surface lifecycle callback 1141 * from this <b>OH_ArkUI_SurfaceHolder</b> instance. 1142 * 1143 * @param surfaceHolder Indicates the pointer to this <b>OH_ArkUI_SurfaceHolder</b> instance. 1144 * @param callback Indicates the pointer to the callback needed to remove. 1145 * @return Returns the status code of the execution. 1146 * {@link ARKUI_ERROR_CODE_NO_ERROR} the execution is successful. 1147 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 1148 * @since 19 1149 */ 1150 int32_t OH_ArkUI_SurfaceHolder_RemoveSurfaceCallback( 1151 OH_ArkUI_SurfaceHolder* surfaceHolder, 1152 OH_ArkUI_SurfaceCallback* callback); 1153 1154 /** 1155 * @brief Forward declaration of OHNativeWindow. 1156 * 1157 * @since 19 1158 */ 1159 typedef struct NativeWindow OHNativeWindow; 1160 1161 /** 1162 * @brief Obtains the nativeWindow associated with a <b>OH_ArkUI_SurfaceHolder</b> instance. 1163 * 1164 * @param surfaceHolder Indicates the pointer to this <b>OH_ArkUI_SurfaceHolder</b> instance. 1165 * @return Returns the nativeWindow associated with this <b>OH_ArkUI_SurfaceHolder</b> instance. 1166 * @since 19 1167 */ 1168 OHNativeWindow* OH_ArkUI_XComponent_GetNativeWindow(OH_ArkUI_SurfaceHolder* surfaceHolder); 1169 1170 /** 1171 * @brief Set whether the XComponent node needs to initialize automatically. 1172 * 1173 * @param node Indicates the pointer to the XComponent node. 1174 * @param autoInitialize Indicates whether the XComponent node needs to initialize automatically or not. 1175 * If the value is true, OnSurfaceCreated will be called when the node is mounted and 1176 * OnSurfaceDestroyed will be called when the node is unmounted. 1177 * Default value is true. 1178 * @return Returns the status code of the execution. 1179 * {@link ARKUI_ERROR_CODE_NO_ERROR} the execution is successful. 1180 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node is invalid. 1181 * @since 19 1182 */ 1183 int32_t OH_ArkUI_XComponent_SetAutoInitialize(ArkUI_NodeHandle node, bool autoInitialize); 1184 1185 /** 1186 * @brief Initialize the XComponent node. 1187 * 1188 * @param node Indicates the pointer to the XComponent node. 1189 * @return Returns the status code of the execution. 1190 * {@link ARKUI_ERROR_CODE_NO_ERROR} the execution is successful. 1191 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node is invalid. 1192 * {@link ARKUI_ERROR_CODE_XCOMPONENT_STATE_INVALID} if the node has initialized. 1193 * @since 19 1194 */ 1195 int32_t OH_ArkUI_XComponent_Initialize(ArkUI_NodeHandle node); 1196 1197 /** 1198 * @brief Finalize the XComponent node. 1199 * 1200 * @param node Indicates the pointer to the XComponent node. 1201 * @return Returns the status code of the execution. 1202 * {@link ARKUI_ERROR_CODE_NO_ERROR} the execution is successful. 1203 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node is invalid. 1204 * {@link ARKUI_ERROR_CODE_XCOMPONENT_STATE_INVALID} if the node has finalized. 1205 * @since 19 1206 */ 1207 int32_t OH_ArkUI_XComponent_Finalize(ArkUI_NodeHandle node); 1208 1209 /** 1210 * @brief Obtains whether the XComponent node has initalized or not. 1211 * 1212 * @param node Indicates the pointer to the XComponent node. 1213 * @param isInitialized Indicates whether the XComponent node has initalized. 1214 * @return Returns the status code of the execution. 1215 * {@link ARKUI_ERROR_CODE_NO_ERROR} the execution is successful. 1216 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if the node is invalid. 1217 * @since 19 1218 */ 1219 int32_t OH_ArkUI_XComponent_IsInitialized(ArkUI_NodeHandle node, bool* isInitialized); 1220 1221 /** 1222 * @brief Set the Expected FrameRateRange for the XComponent node. 1223 * 1224 * @param node Indicates the pointer to the XComponent node. 1225 * @param range Indicates the expected rate range. 1226 * @return Returns the status code of the execution. 1227 * {@link ARKUI_ERROR_CODE_NO_ERROR} the execution is successful. 1228 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 1229 * @since 20 1230 * @version 1.0 1231 */ 1232 int32_t OH_ArkUI_XComponent_SetExpectedFrameRateRange( 1233 ArkUI_NodeHandle node, OH_NativeXComponent_ExpectedRateRange range); 1234 1235 /** 1236 * @brief Registers an onFrame callback for the XComponent node. 1237 * 1238 * @param node Indicates the pointer to the XComponent node. 1239 * @param callback Indicates the pointer to an onFrame callback. 1240 * @return Returns the status code of the execution. 1241 * {@link ARKUI_ERROR_CODE_NO_ERROR} the execution is successful. 1242 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 1243 * @since 20 1244 * @version 1.0 1245 */ 1246 int32_t OH_ArkUI_XComponent_RegisterOnFrameCallback(ArkUI_NodeHandle node, 1247 void (*callback)(ArkUI_NodeHandle node, uint64_t timestamp, uint64_t targetTimestamp)); 1248 1249 /** 1250 * @brief UnRegister the onFrame callback for the XComponent node. 1251 * 1252 * @param node Indicates the pointer to the XComponent node. 1253 * @return Returns the status code of the execution. 1254 * {@link ARKUI_ERROR_CODE_NO_ERROR} the execution is successful. 1255 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 1256 * @since 20 1257 * @version 1.0 1258 */ 1259 int32_t OH_ArkUI_XComponent_UnregisterOnFrameCallback(ArkUI_NodeHandle node); 1260 1261 /** 1262 * @brief Set whether the XComponent node needs soft keyboard when focused. 1263 * @param node Indicates the pointer to the XComponent node. 1264 * @param needSoftKeyboard Indicates whether the XComponent node needs soft keyboard or not. 1265 * Default value is false. 1266 * @return Returns the status code of the execution. 1267 * {@link ARKUI_ERROR_CODE_NO_ERROR} the execution is successful. 1268 * {@link ARKUI_ERROR_CODE_PARAM_INVALID} if a parameter error occurs. 1269 * @since 20 1270 */ 1271 int32_t OH_ArkUI_XComponent_SetNeedSoftKeyboard(ArkUI_NodeHandle node, bool needSoftKeyboard); 1272 1273 /** 1274 * @brief Create a <b>ArkUI_AccessibilityProvider</b> object from an XComponent node. 1275 * 1276 * @param node Indicates the pointer to the XComponent node. 1277 * @return Returns the created <b>ArkUI_AccessibilityProvider</b> object's pointer. 1278 * @since 20 1279 */ 1280 ArkUI_AccessibilityProvider* OH_ArkUI_AccessibilityProvider_Create(ArkUI_NodeHandle node); 1281 1282 /** 1283 * @brief Disposes of an <b>ArkUI_AccessibilityProvider</b> object. 1284 * 1285 * @param provider Indicates the pointer to <b>ArkUI_AccessibilityProvider</b> object needed to dispose. 1286 * @since 20 1287 */ 1288 void OH_ArkUI_AccessibilityProvider_Dispose(ArkUI_AccessibilityProvider* provider); 1289 1290 /** 1291 * @brief Set the surface show event of the surface callback. 1292 * 1293 * @param callback Indicated the pointer to the surface callback. 1294 * @param onSurfaceShow Indicates the surface show callback event which will called when the surface is shown. 1295 * @since 20 1296 */ 1297 void OH_ArkUI_SurfaceCallback_SetSurfaceShowEvent( 1298 OH_ArkUI_SurfaceCallback* callback, 1299 void (*onSurfaceShow)(OH_ArkUI_SurfaceHolder* surfaceHolder)); 1300 1301 /** 1302 * @brief Set the surface hide event of the surface callback. 1303 * 1304 * @param callback Indicated the pointer to the surface callback. 1305 * @param onSurfaceHide Indicates the surface hide callback event which will called when the surface is hide. 1306 * @since 20 1307 */ 1308 void OH_ArkUI_SurfaceCallback_SetSurfaceHideEvent( 1309 OH_ArkUI_SurfaceCallback* callback, 1310 void (*onSurfaceHide)(OH_ArkUI_SurfaceHolder* surfaceHolder)); 1311 #ifdef __cplusplus 1312 }; 1313 #endif 1314 #endif // _NATIVE_INTERFACE_XCOMPONENT_H_ 1315 /** @} */