目录

native_interface_xcomponent.h

Overview

Declares the APIs for accessing Native XComponent features. Native XComponent provides capabilities such as surface lifecycle management, touch events, mouse events, key events, frame rate control, AI image analysis, and accessibility access. It is suitable for scenarios where self-rendered content (such as game rendering and media playback) needs to be embedded in ArkUI.

File to include: <ace/xcomponent/native_interface_xcomponent.h>

Library: libace_ndk.z.so

System capability: SystemCapability.ArkUI.ArkUI.Full

Since: 8

Related module: OH_NativeXComponent Native XComponent

Sample: NativeXComponentSample

Summary

[h2]Structs

Name typedef Keyword Description
OH_NativeXComponent_HistoricalPoint OH_NativeXComponent_HistoricalPoint Represents a historical touch point.
OH_NativeXComponent_TouchPoint OH_NativeXComponent_TouchPoint Describes the touch point of the touch event.
OH_NativeXComponent_TouchEvent OH_NativeXComponent_TouchEvent Describes the touch event.
OH_NativeXComponent_MouseEvent OH_NativeXComponent_MouseEvent Describes the mouse event.
OH_NativeXComponent_Callback OH_NativeXComponent_Callback Registers callbacks for the surface lifecycle and touch event.
OH_NativeXComponent_MouseEvent_Callback OH_NativeXComponent_MouseEvent_Callback Registers callbacks for the mouse event.
OH_NativeXComponent_ExpectedRateRange OH_NativeXComponent_ExpectedRateRange Defines the expected frame rate range.
OH_NativeXComponent OH_NativeXComponent Provides an encapsulated OH_NativeXComponent instance.
OH_NativeXComponent_KeyEvent OH_NativeXComponent_KeyEvent Provides an encapsulated OH_NativeXComponent_KeyEvent instance.
OH_NativeXComponent_ExtraMouseEventInfo OH_NativeXComponent_ExtraMouseEventInfo Provides an encapsulated instance of extended mouse event information.
OH_ArkUI_SurfaceHolder OH_ArkUI_SurfaceHolder Provides an encapsulated OH_ArkUI_SurfaceHolder instance.
OH_ArkUI_SurfaceCallback OH_ArkUI_SurfaceCallback Defines surface lifecycle callback functions.
OHNativeWindow OHNativeWindow Provides an encapsulated NativeWindow instance.
ArkUI_XComponentSurfaceConfig ArkUI_XComponentSurfaceConfig Defines the surface configuration for the XComponent, which specifies whether the XComponent's surface should be treated as opaque during rendering.

[h2]Enums

Name typedef Keyword Description
anonymous - Enumerates API execution result states.
ArkUI_XComponent_ImageAnalyzerState ArkUI_XComponent_ImageAnalyzerState Enumerates the AI image analyzer state codes of the XComponent.
OH_NativeXComponent_TouchEventType OH_NativeXComponent_TouchEventType Enumerates the touch event types.
OH_NativeXComponent_TouchPointToolType OH_NativeXComponent_TouchPointToolType Enumerates the touch point tool types.
OH_NativeXComponent_EventSourceType OH_NativeXComponent_EventSourceType Enumerates the event source types.
OH_NativeXComponent_MouseEventAction OH_NativeXComponent_MouseEventAction Enumerates the mouse event actions.
OH_NativeXComponent_MouseEventButton OH_NativeXComponent_MouseEventButton Enumerates the mouse event buttons.
OH_NativeXComponent_TouchEvent_SourceTool OH_NativeXComponent_TouchEvent_SourceTool Enumerates the source tool types of touch events.

[h2]Macros

Name Description
OH_NATIVE_XCOMPONENT_OBJ ("__NATIVE_XCOMPONENT_OBJ__") Native XComponent instance.
OH_NATIVE_XCOMPONENT_MAX_TOUCH_POINTS_NUMBER 10 Maximum number of identifiable touch points in a touch event.

[h2]Functions

Name Description
int32_t OH_NativeXComponent_GetXComponentId(OH_NativeXComponent* component, char* id, uint64_t* size) Obtains the ID of ArkUI XComponent.
int32_t OH_NativeXComponent_GetXComponentSize(OH_NativeXComponent* component, const void* window, uint64_t* width, uint64_t* height) Obtains the size of the surface held by the ArkUI XComponent.
int32_t OH_NativeXComponent_GetXComponentOffset(OH_NativeXComponent* component, const void* window, double* x, double* y) Obtains the offset of the surface held by the XComponent relative to the upper left corner of its parent component.
int32_t OH_NativeXComponent_GetTouchEvent(OH_NativeXComponent* component, const void* window, OH_NativeXComponent_TouchEvent* touchEvent) Obtains the touch event scheduled by the ArkUI XComponent.
int32_t OH_NativeXComponent_GetTouchPointToolType(OH_NativeXComponent* component, uint32_t pointIndex, OH_NativeXComponent_TouchPointToolType* toolType) Obtains the ArkUI XComponent touch point tool type.
int32_t OH_NativeXComponent_GetTouchPointTiltX(OH_NativeXComponent* component, uint32_t pointIndex, float* tiltX) Obtains the angle between the Y-Z plane of the ArkUI XComponent touch point and the x-axis.
int32_t OH_NativeXComponent_GetTouchPointTiltY(OH_NativeXComponent* component, uint32_t pointIndex, float* tiltY) Obtains the angle between the X-Z plane of the ArkUI XComponent touch point and the y-axis.
int32_t OH_NativeXComponent_GetTouchPointWindowX(OH_NativeXComponent* component, uint32_t pointIndex, float* windowX) Obtains the x-coordinate of the touch point relative to the upper left corner of the application window where the ArkUI XComponent is located.
int32_t OH_NativeXComponent_GetTouchPointWindowY(OH_NativeXComponent* component, uint32_t pointIndex, float* windowY) Obtains the y-coordinate of the touch point relative to the upper left corner of the application window where the ArkUI XComponent is located.
int32_t OH_NativeXComponent_GetTouchPointDisplayX(OH_NativeXComponent* component, uint32_t pointIndex, float* displayX) Obtains the x-coordinate of the touch point relative to the upper left corner of the screen where the ArkUI XComponent is located.
int32_t OH_NativeXComponent_GetTouchPointDisplayY(OH_NativeXComponent* component, uint32_t pointIndex, float* displayY) Obtains the y-coordinate of the touch point relative to the upper left corner of the screen where the ArkUI XComponent is located.
int32_t OH_NativeXComponent_GetHistoricalPoints(OH_NativeXComponent* component, const void* window, int32_t* size, OH_NativeXComponent_HistoricalPoint** historicalPoints) Obtains the historical point information of the current XComponent touch event. Some input devices report touch points at a very high frequency (up to once every 1 ms). Reporting to the application at this frequency would cause redundancy, so the touch event is reported to the application only once per frame. All touch points reported in the current frame are saved as historical points. If the application needs to process this data directly, it can call this API to obtain the historical point information.
int32_t OH_NativeXComponent_GetMouseEvent(OH_NativeXComponent* component, const void* window, OH_NativeXComponent_MouseEvent* mouseEvent) Obtains the mouse event scheduled by the ArkUI XComponent.
int32_t OH_NativeXComponent_RegisterCallback(OH_NativeXComponent* component, OH_NativeXComponent_Callback* callback) Registers surface lifecycle and touch event callbacks for this OH_NativeXComponent instance.
int32_t OH_NativeXComponent_RegisterMouseEventCallback(OH_NativeXComponent* component, OH_NativeXComponent_MouseEvent_Callback* callback) Registers a mouse event callback for this OH_NativeXComponent instance.
int32_t OH_NativeXComponent_GetExtraMouseEventInfo(OH_NativeXComponent* component, OH_NativeXComponent_ExtraMouseEventInfo** extraMouseEventInfo) Obtains extended mouse event information from this OH_NativeXComponent instance. This API must be called during the execution of the mouse event callback (registered via OH_NativeXComponent_RegisterMouseEventCallback).
int32_t OH_NativeXComponent_GetMouseEventModifierKeyStates (OH_NativeXComponent_ExtraMouseEventInfo* extraMouseEventInfo, uint64_t* keys) Obtains the state of modifier keys from an OH_NativeXComponent_ExtraMouseEventInfo instance.
int32_t OH_NativeXComponent_RegisterFocusEventCallback(OH_NativeXComponent* component, void (*callback)(OH_NativeXComponent* component, void* window)) Registers a focus event callback for this OH_NativeXComponent instance.
int32_t OH_NativeXComponent_RegisterKeyEventCallback(OH_NativeXComponent* component, void (*callback)(OH_NativeXComponent* component, void* window)) Registers a key event callback for this OH_NativeXComponent instance. The callback registered by this API has no return value and cannot control whether the key event continues to be distributed. To intercept key events, use OH_NativeXComponent_RegisterKeyEventCallbackWithResult.
int32_t OH_NativeXComponent_RegisterBlurEventCallback(OH_NativeXComponent* component, void (*callback)(OH_NativeXComponent* component, void* window)) Registers a blur event callback for this OH_NativeXComponent instance.
int32_t OH_NativeXComponent_GetKeyEvent(OH_NativeXComponent* component, OH_NativeXComponent_KeyEvent** keyEvent) Obtains the key event scheduled by the ArkUI XComponent.
int32_t OH_NativeXComponent_GetKeyEventAction(OH_NativeXComponent_KeyEvent* keyEvent, OH_NativeXComponent_KeyAction* action) Obtains the action of the specified key event.
int32_t OH_NativeXComponent_GetKeyEventCode(OH_NativeXComponent_KeyEvent* keyEvent, OH_NativeXComponent_KeyCode* code) Obtains the key code of the specified key event.
int32_t OH_NativeXComponent_GetKeyEventSourceType(OH_NativeXComponent_KeyEvent* keyEvent, OH_NativeXComponent_EventSourceType* sourceType) Obtains the source type of the specified key event.
int32_t OH_NativeXComponent_GetKeyEventDeviceId(OH_NativeXComponent_KeyEvent* keyEvent, int64_t* deviceId) Obtains the device ID of the specified key event.
int32_t OH_NativeXComponent_GetKeyEventTimestamp(OH_NativeXComponent_KeyEvent* keyEvent, int64_t* timestamp) Obtains the timestamp of the specified key event.
int32_t OH_NativeXComponent_GetKeyEventModifierKeyStates(OH_NativeXComponent_KeyEvent* keyEvent, uint64_t* keys) Obtains the state of modifier keys from a key event.
int32_t OH_NativeXComponent_GetKeyEventNumLockState(OH_NativeXComponent_KeyEvent* keyEvent, bool* isNumLockOn) Obtains the state of the NumLock key from a key event.
int32_t OH_NativeXComponent_GetKeyEventCapsLockState(OH_NativeXComponent_KeyEvent* keyEvent, bool* isCapsLockOn) Obtains the state of the CapsLock key from a key event.
int32_t OH_NativeXComponent_GetKeyEventScrollLockState(OH_NativeXComponent_KeyEvent* keyEvent, bool* isScrollLockOn) Obtains the state of the ScrollLock key from a key event.
int32_t OH_NativeXComponent_SetExpectedFrameRateRange(OH_NativeXComponent* component, OH_NativeXComponent_ExpectedRateRange* range) Sets the expected frame rate range. This API is applicable to scenarios where operations are performed through the OH_NativeXComponent pointer. If XComponent is created using NativeNode (ArkUI_NodeHandle), use OH_ArkUI_XComponent_SetExpectedFrameRateRange.
int32_t OH_NativeXComponent_RegisterOnFrameCallback(OH_NativeXComponent* component, void (*callback)(OH_NativeXComponent* component, uint64_t timestamp, uint64_t targetTimestamp)) Registers the display update callback for this OH_NativeXComponent instance and enables the callback for each frame.
int32_t OH_NativeXComponent_UnregisterOnFrameCallback(OH_NativeXComponent* component) Deregisters the display update callback for this OH_NativeXComponent instance and disables the callback for each frame.
int32_t OH_NativeXComponent_AttachNativeRootNode(OH_NativeXComponent* component, ArkUI_NodeHandle root)

Attaches the UI component created through ArkUI native APIs to the current XComponent.

Call in pair: When the attached component is no longer needed, OH_NativeXComponent_DetachNativeRootNode must be called to detach it.
int32_t OH_NativeXComponent_DetachNativeRootNode(OH_NativeXComponent* component, ArkUI_NodeHandle root) Detaches the native component of ArkUI from this OH_NativeXComponent instance.
int32_t OH_NativeXComponent_RegisterUIInputEventCallback(OH_NativeXComponent *component, void (*callback)(OH_NativeXComponent *component, ArkUI_UIInputEvent *event,ArkUI_UIInputEvent_Type type),ArkUI_UIInputEvent_Type type) Registers a UI input event callback for this OH_NativeXComponent instance and enables this callback to be invoked when a UI input event is received. Currently, only axis events are supported.
int32_t OH_NativeXComponent_RegisterOnTouchInterceptCallback(OH_NativeXComponent* component, HitTestMode (*callback)(OH_NativeXComponent* component, ArkUI_UIInputEvent* event)) Registers a custom event intercept callback for this OH_NativeXComponent instance and enables the callback to be invoked during hit testing. This API is applicable to scenarios where touch event distribution logic needs to be customized, such as preventing touch events from being passed to child components or deciding the event consumption policy based on custom conditions. The event object obtained through this callback does not support UIInput-related information operation APIs. It is recommended to switch to the NODE_ON_TOUCH_INTERCEPT general event registered on the native node instead.
int32_t OH_NativeXComponent_SetNeedSoftKeyboard(OH_NativeXComponent* component, bool needSoftKeyboard) Sets whether the soft keyboard is required for this OH_NativeXComponent instance.
int32_t OH_NativeXComponent_RegisterSurfaceShowCallback(OH_NativeXComponent* component, void (*callback)(OH_NativeXComponent* component, void* window)) Registers a surface show callback for this OH_NativeXComponent instance. This callback is triggered when the application window returns from the background to the foreground. For XComponent created based on NativeNode (ArkUI_NodeHandle), it is recommended to use OH_ArkUI_SurfaceCallback_SetSurfaceShowEvent.
int32_t OH_NativeXComponent_RegisterSurfaceHideCallback(OH_NativeXComponent* component, void (*callback)(OH_NativeXComponent* component, void* window)) Registers a surface hiding callback for this OH_NativeXComponent instance. This callback is invoked after the application is switched to the background.
int32_t OH_NativeXComponent_GetTouchEventSourceType(OH_NativeXComponent* component, int32_t pointId, OH_NativeXComponent_EventSourceType* sourceType) Obtains the touch event source type of an ArkUI XComponent instance.
OH_NativeXComponent* OH_NativeXComponent_GetNativeXComponent(ArkUI_NodeHandle node) Obtains a pointer of the OH_NativeXComponent type based on the specified component instance created by the native API.
int32_t OH_NativeXComponent_GetNativeAccessibilityProvider(OH_NativeXComponent* component, ArkUI_AccessibilityProvider** handle) Obtains the accessibility provider handle for an ArkUI XComponent. The handle is an address (double-pointer) used to receive the returned instance pointer.
int32_t OH_NativeXComponent_RegisterKeyEventCallbackWithResult(OH_NativeXComponent* component, bool (*callback)(OH_NativeXComponent* component, void* window)) Registers a key event callback with a return value for this OH_NativeXComponent instance. Unlike OH_NativeXComponent_RegisterKeyEventCallback, all key event callbacks registered through this API must return a result, that is, true or false. When the return value is true, the event will not be distributed further; when the return value is false, the event will continue to be distributed according to the event processing flow. Use this API if you need to control whether the key event continues to be distributed. If you only need to listen for key events, use OH_NativeXComponent_RegisterKeyEventCallback.
int32_t OH_ArkUI_XComponent_StartImageAnalyzer(ArkUI_NodeHandle node, void* userData, void (*callback)(ArkUI_NodeHandle node, ArkUI_XComponent_ImageAnalyzerState statusCode, void* userData)) Starts image AI analysis for this XComponent instance. This API is applicable to scenarios where image intelligent recognition features need to be provided in the application. The image AI analysis capability must be enabled before use.
int32_t OH_ArkUI_XComponent_StopImageAnalyzer(ArkUI_NodeHandle node)

Stops image AI analysis for this XComponent instance. The image AI analysis capability must be enabled before use.

Call in pair: This API is the paired API of OH_ArkUI_XComponent_StartImageAnalyzer. After calling StartImageAnalyzer to start the analysis, call this API to stop the analysis and release related resources when the analysis is complete or no longer needed.
OH_ArkUI_SurfaceHolder* OH_ArkUI_SurfaceHolder_Create(ArkUI_NodeHandle node) Creates an OH_ArkUI_SurfaceHolder object for an XComponent.
void OH_ArkUI_SurfaceHolder_Dispose(OH_ArkUI_SurfaceHolder* surfaceHolder) Disposes of an OH_ArkUI_SurfaceHolder object.
int32_t OH_ArkUI_SurfaceHolder_SetUserData(OH_ArkUI_SurfaceHolder* surfaceHolder, void* userData) Stores custom data in an OH_ArkUI_SurfaceHolder instance.
void* OH_ArkUI_SurfaceHolder_GetUserData(OH_ArkUI_SurfaceHolder* surfaceHolder) Obtains the custom data stored in an OH_ArkUI_SurfaceHolder instance.
OH_ArkUI_SurfaceCallback* OH_ArkUI_SurfaceCallback_Create() Creates an OH_ArkUI_SurfaceCallback object.
void OH_ArkUI_SurfaceCallback_Dispose(OH_ArkUI_SurfaceCallback* callback) Disposes of an OH_ArkUI_SurfaceCallback object.
void OH_ArkUI_SurfaceCallback_SetSurfaceCreatedEvent(OH_ArkUI_SurfaceCallback* callback,void (*onSurfaceCreated)(OH_ArkUI_SurfaceHolder* surfaceHolder)) Sets the creation callback event in the surface lifecycle callbacks.
void OH_ArkUI_SurfaceCallback_SetSurfaceChangedEvent(OH_ArkUI_SurfaceCallback* callback,void (*onSurfaceChanged)(OH_ArkUI_SurfaceHolder* surfaceHolder, uint64_t width, uint64_t height)) Sets the size change callback event in the surface lifecycle callbacks.
void OH_ArkUI_SurfaceCallback_SetSurfaceDestroyedEvent(OH_ArkUI_SurfaceCallback* callback,void (*onSurfaceDestroyed)(OH_ArkUI_SurfaceHolder* surfaceHolder)) Sets the destruction callback event in the surface lifecycle callbacks.
int32_t OH_ArkUI_SurfaceHolder_AddSurfaceCallback(OH_ArkUI_SurfaceHolder* surfaceHolder,OH_ArkUI_SurfaceCallback* callback) Adds a surface lifecycle callback to an OH_ArkUI_SurfaceHolder instance.
int32_t OH_ArkUI_SurfaceHolder_RemoveSurfaceCallback(OH_ArkUI_SurfaceHolder* surfaceHolder,OH_ArkUI_SurfaceCallback* callback) Removes a previously added surface lifecycle callback from an OH_ArkUI_SurfaceHolder instance.
OHNativeWindow* OH_ArkUI_XComponent_GetNativeWindow(OH_ArkUI_SurfaceHolder* surfaceHolder) Obtains the NativeWindow instance associated with an OH_ArkUI_SurfaceHolder instance.
int32_t OH_ArkUI_XComponent_SetAutoInitialize(ArkUI_NodeHandle node, bool autoInitialize)

Sets whether the XComponent needs to automatically initialize the surface.

API relationship (configuration dependency): This API controls the initialization mode of the surface and affects how OH_ArkUI_XComponent_Initialize and OH_ArkUI_XComponent_Finalize are used. When autoInitialize is set to true (default), the surface is automatically initialized/finalized when the component is attached to/detached from the tree, and there is no need to manually call Initialize/Finalize. When autoInitialize is set to false, you must manually call Initialize to initialize the surface and call Finalize to finalize the surface at the appropriate time.
int32_t OH_ArkUI_XComponent_Initialize(ArkUI_NodeHandle node)

Initializes the surface held by the XComponent. Before calling this API, set autoInitialize to false through OH_ArkUI_XComponent_SetAutoInitialize() to prevent the surface from being automatically initialized when the component is attached to the tree.

API relationship (prerequisites): This API needs to be called to manually initialize the surface only when autoInitialize is set to false through OH_ArkUI_XComponent_SetAutoInitialize. When autoInitialize is set to true (default), the surface is automatically initialized when the component is attached to the tree, and this API does not need to be called. Call in pair: After calling this API to initialize the surface, OH_ArkUI_XComponent_Finalize must be called to finalize the surface when it is no longer needed. Status query: The current initialization status can be queried through OH_ArkUI_XComponent_IsInitialized. Status requirement: This API can be called only when the surface is in the uninitialized state. Repeated initialization will return ARKUI_ERROR_CODE_XCOMPONENT_STATE_INVALID.
int32_t OH_ArkUI_XComponent_Finalize(ArkUI_NodeHandle node)

Finalizes the surface held by the XComponent.

Call in pair: This API is the paired API of OH_ArkUI_XComponent_Initialize. It is called only after the surface has been initialized through Initialize, to finalize the surface and release the resources. Status requirement: This API can be called only when the surface is in the initialized state. Repeatedly calling this API on an already finalized surface will return ARKUI_ERROR_CODE_XCOMPONENT_STATE_INVALID.
int32_t OH_ArkUI_XComponent_IsInitialized(ArkUI_NodeHandle node, bool* isInitialized) Checks whether the surface held by the XComponent component is initialized.
int32_t OH_ArkUI_XComponent_SetExpectedFrameRateRange(ArkUI_NodeHandle node, OH_NativeXComponent_ExpectedRateRange range) Sets an expected frame rate range for this XComponent instance.
int32_t OH_ArkUI_XComponent_RegisterOnFrameCallback(ArkUI_NodeHandle node,void (*callback)(ArkUI_NodeHandle node, uint64_t timestamp, uint64_t targetTimestamp)) Registers a frame callback function for this XComponent instance and enables the callback to be invoked on each frame.
int32_t OH_ArkUI_XComponent_UnregisterOnFrameCallback(ArkUI_NodeHandle node) Unregisters the frame callback function for this XComponent instance and disables the callback to be invoked on each frame.
int32_t OH_ArkUI_XComponent_SetNeedSoftKeyboard(ArkUI_NodeHandle node, bool needSoftKeyboard) Sets whether the soft keyboard is required for the XComponent.
ArkUI_AccessibilityProvider* OH_ArkUI_AccessibilityProvider_Create(ArkUI_NodeHandle node) Creates an ArkUI_AccessibilityProvider instance for this XComponent instance.
void OH_ArkUI_AccessibilityProvider_Dispose(ArkUI_AccessibilityProvider* provider) Disposes of the ArkUI_AccessibilityProvider instance created using OH_ArkUI_AccessibilityProvider_Create.
void OH_ArkUI_SurfaceCallback_SetSurfaceShowEvent(OH_ArkUI_SurfaceCallback* callback, void (*onSurfaceShow)(OH_ArkUI_SurfaceHolder* surfaceHolder)) Sets a surface display callback for this OH_ArkUI_SurfaceCallback instance. This callback is invoked when the application window has moved from the background to the foreground.
void OH_ArkUI_SurfaceCallback_SetSurfaceHideEvent(OH_ArkUI_SurfaceCallback* callback, void (*onSurfaceHide)(OH_ArkUI_SurfaceHolder* surfaceHolder)) Sets a surface hiding callback for this OH_ArkUI_SurfaceCallback instance. This callback is invoked when the application window has moved from the foreground to the background.
ArkUI_XComponentSurfaceConfig* OH_ArkUI_XComponentSurfaceConfig_Create() Creates an ArkUI_XComponentSurfaceConfig object for an XComponent.
void OH_ArkUI_XComponentSurfaceConfig_Dispose(ArkUI_XComponentSurfaceConfig* config) Disposes of an ArkUI_XComponentSurfaceConfig object.
void OH_ArkUI_XComponentSurfaceConfig_SetIsOpaque(ArkUI_XComponentSurfaceConfig* config, bool isOpaque) Sets whether the surface held by the XComponent should be treated as opaque during rendering, regardless of the actual pixel transparency.
int32_t OH_ArkUI_SurfaceHolder_SetSurfaceConfig(OH_ArkUI_SurfaceHolder* surfaceHolder, ArkUI_XComponentSurfaceConfig *config) Sets the surface configuration for the OH_ArkUI_SurfaceHolder instance.

[h2]Variables

Name Description
const uint32_t OH_XCOMPONENT_ID_LEN_MAX = 128

Maximum length of the ArkUI XComponent ID.

Since: 8
const uint32_t OH_MAX_TOUCH_POINTS_NUMBER = 10

Maximum number of identifiable touch points in a touch event.

Since: 8
OH_NATIVE_XCOMPONENT_MAX_TOUCH_POINTS_NUMBER 10

Maximum number of identifiable touch points in a touch event.

Since: 8

Enum Description

[h2]anonymous

enum anonymous

Description

Enumerates API execution result states.

Since: 8

Value Description
OH_NATIVEXCOMPONENT_RESULT_SUCCESS = 0 Success.
OH_NATIVEXCOMPONENT_RESULT_FAILED = -1 Failure, indicating the API execution failed, which may be caused by the following: 1. XComponent has not been initialized. 2. The surface has been finalized or released. 3. An internal system error occurs. Check the XComponent initialization status and surface lifecycle and try again.
OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER = -2 Invalid parameter. The input parameter is a null pointer or does not meet the API requirements. Check whether the input parameter is valid.

[h2]ArkUI_XComponent_ImageAnalyzerState

enum ArkUI_XComponent_ImageAnalyzerState

Description

Enumerates the AI image analyzer state codes of the XComponent.

Since: 18

Value Description
ARKUI_XCOMPONENT_AI_ANALYSIS_FINISHED = 0 AI image analysis is complete.
ARKUI_XCOMPONENT_AI_ANALYSIS_DISABLED = 110000 AI image analysis is disabled.
ARKUI_XCOMPONENT_AI_ANALYSIS_UNSUPPORTED = 110001 The device does not support AI image analysis.
ARKUI_XCOMPONENT_AI_ANALYSIS_ONGOING = 110002 AI image analysis is in progress.
ARKUI_XCOMPONENT_AI_ANALYSIS_STOPPED = 110003 AI image analysis has been stopped.

[h2]OH_NativeXComponent_TouchEventType

enum OH_NativeXComponent_TouchEventType

Description

Enumerates the touch event types.

Since: 8

Value Description
OH_NATIVEXCOMPONENT_DOWN = 0 The touch event is triggered when a finger is pressed.
OH_NATIVEXCOMPONENT_UP = 1 The touch event is triggered when a finger is lifted.
OH_NATIVEXCOMPONENT_MOVE = 2 The touch event is triggered when a finger is moved on the screen.
OH_NATIVEXCOMPONENT_CANCEL = 3 The event is triggered when a touch event is canceled.
OH_NATIVEXCOMPONENT_UNKNOWN = 4 Invalid touch type.

[h2]OH_NativeXComponent_TouchPointToolType

enum OH_NativeXComponent_TouchPointToolType

Description

Enumerates the touch point tool types.

Since: 9

Value Description
OH_NATIVEXCOMPONENT_TOOL_TYPE_UNKNOWN = 0 Unknown tool type.
OH_NATIVEXCOMPONENT_TOOL_TYPE_FINGER = 1 Finger.
OH_NATIVEXCOMPONENT_TOOL_TYPE_PEN = 2 Pen.
OH_NATIVEXCOMPONENT_TOOL_TYPE_RUBBER = 3 Rubber.
OH_NATIVEXCOMPONENT_TOOL_TYPE_BRUSH = 4 Brush.
OH_NATIVEXCOMPONENT_TOOL_TYPE_PENCIL = 5 Pencil.
OH_NATIVEXCOMPONENT_TOOL_TYPE_AIRBRUSH = 6 Airbrush.
OH_NATIVEXCOMPONENT_TOOL_TYPE_MOUSE = 7 Mouse.
OH_NATIVEXCOMPONENT_TOOL_TYPE_LENS = 8 Lens.

[h2]OH_NativeXComponent_EventSourceType

enum OH_NativeXComponent_EventSourceType

Description

Enumerates the touch event source types.

Since: 9

Value Description
OH_NATIVEXCOMPONENT_SOURCE_TYPE_UNKNOWN = 0 Unknown source type.
OH_NATIVEXCOMPONENT_SOURCE_TYPE_MOUSE = 1 Source that generates a mouse event.
OH_NATIVEXCOMPONENT_SOURCE_TYPE_TOUCHSCREEN = 2 Source that generates a touchscreen multitouch event.
OH_NATIVEXCOMPONENT_SOURCE_TYPE_TOUCHPAD = 3 Source that generates a touchpad multitouch event.
OH_NATIVEXCOMPONENT_SOURCE_TYPE_JOYSTICK = 4 Source that generates a joystick event.
OH_NATIVEXCOMPONENT_SOURCE_TYPE_KEYBOARD = 5

Source that generates a key event.

Since: 10

[h2]OH_NativeXComponent_MouseEventAction

enum OH_NativeXComponent_MouseEventAction

Description

Enumerates the mouse event actions.

Since: 9

Value Description
OH_NATIVEXCOMPONENT_MOUSE_NONE = 0 Invalid mouse event.
OH_NATIVEXCOMPONENT_MOUSE_PRESS = 1 Mouse button press.
OH_NATIVEXCOMPONENT_MOUSE_RELEASE = 2 Mouse button release.
OH_NATIVEXCOMPONENT_MOUSE_MOVE = 3 Mouse movement.
OH_NATIVEXCOMPONENT_MOUSE_CANCEL = 4

Mouse operation cancellation.

Since: 18

Note: OH_NATIVEXCOMPONENT_MOUSE_CANCEL indicates that the mouse event is canceled. It is typically triggered in the following scenarios:

1. Component focus loss: This action is triggered when the currently focused XComponent loses focus due to a system event (such as a pop-up interruption or application switching).

2. Event interruption: A higher-priority event (such as a system-level gesture or forced event stream reclamation) occurs during the mouse operation, causing the current mouse operation to be forcibly terminated.

3. Abnormal state exit: In scenarios such as component destruction or abnormal rendering environment, unfinished mouse events are marked as canceled.

[h2]OH_NativeXComponent_MouseEventButton

enum OH_NativeXComponent_MouseEventButton

Description

Enumerates the mouse event buttons.

Since: 9

Value Description
OH_NATIVEXCOMPONENT_NONE_BUTTON = 0 No button.
OH_NATIVEXCOMPONENT_LEFT_BUTTON = 0x01 Left mouse button.
OH_NATIVEXCOMPONENT_RIGHT_BUTTON = 0x02 Right mouse button.
OH_NATIVEXCOMPONENT_MIDDLE_BUTTON = 0x04 Middle mouse button.
OH_NATIVEXCOMPONENT_BACK_BUTTON = 0x08 Back button on the left of the mouse.
OH_NATIVEXCOMPONENT_FORWARD_BUTTON = 0x10 Forward key on the left of the mouse.

[h2]OH_NativeXComponent_TouchEvent_SourceTool

enum OH_NativeXComponent_TouchEvent_SourceTool

Description

Enumerates the source tool types of touch events.

Since: 10

Value Description
OH_NATIVEXCOMPONENT_SOURCETOOL_UNKNOWN = 0 Unknown source tool.
OH_NATIVEXCOMPONENT_SOURCETOOL_FINGER = 1 Finger.
OH_NATIVEXCOMPONENT_SOURCETOOL_PEN = 2 Pen.
OH_NATIVEXCOMPONENT_SOURCETOOL_RUBBER = 3 Rubber.
OH_NATIVEXCOMPONENT_SOURCETOOL_BRUSH = 4 Brush.
OH_NATIVEXCOMPONENT_SOURCETOOL_PENCIL = 5 Pencil.
OH_NATIVEXCOMPONENT_SOURCETOOL_AIRBRUSH = 6 Airbrush.
OH_NATIVEXCOMPONENT_SOURCETOOL_MOUSE = 7 Mouse pointer.
OH_NATIVEXCOMPONENT_SOURCETOOL_LENS = 8 Lens.
OH_NATIVEXCOMPONENT_SOURCETOOL_TOUCHPAD = 9 Touchpad.

Function Description

[h2]OH_NativeXComponent_GetXComponentId()

int32_t OH_NativeXComponent_GetXComponentId(OH_NativeXComponent* component, char* id, uint64_t* size)

Description

Obtains the ID of ArkUI XComponent.

Since: 8

Parameters

Name Description
OH_NativeXComponent* component Pointer to the OH_NativeXComponent instance, used to access and manage the native capabilities of XComponent.
char* id Pointer to the character buffer for storing the ID of the OH_NativeXComponent instance. Note that null terminators will be attached to the character buffer, so the size of the character buffer should be at least one unit greater than the length of the real ID. The recommended size is [OH_XCOMPONENT_ID_LEN_MAX + 1].
uint64_t* size Pointer to the length of the ID, used to receive the length information of the ID.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_GetXComponentSize()

int32_t OH_NativeXComponent_GetXComponentSize(OH_NativeXComponent* component, const void* window, uint64_t* width, uint64_t* height)

Description

Obtains the size of the surface held by the ArkUI XComponent.

Since: 8

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
const void* window Handle to the NativeWindow instance.
uint64_t* width Pointer to the width of the current surface. Unit: px.
uint64_t* height Pointer to the height of the current surface. Unit: px.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_GetXComponentOffset()

int32_t OH_NativeXComponent_GetXComponentOffset(OH_NativeXComponent* component, const void* window, double* x, double* y)

Description

Obtains the offset of the surface held by the XComponent relative to the upper left corner of its parent component.

Since: 8

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
const void* window Handle to the NativeWindow instance.
double* x Pointer to the x-coordinate of the current surface relative to the upper left corner of the XComponent's parent component. Unit: vp.
double* y Pointer to the y-coordinate of the current surface relative to the upper left corner of the XComponent's parent component. Unit: vp.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_GetTouchEvent()

int32_t OH_NativeXComponent_GetTouchEvent(OH_NativeXComponent* component, const void* window, OH_NativeXComponent_TouchEvent* touchEvent)

Description

Obtains the touch event scheduled by the ArkUI XComponent.

Since: 8

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
const void* window Handle to the NativeWindow instance.
OH_NativeXComponent_TouchEvent* touchEvent Pointer to the current touch event.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_GetTouchPointToolType()

int32_t OH_NativeXComponent_GetTouchPointToolType(OH_NativeXComponent* component, uint32_t pointIndex,OH_NativeXComponent_TouchPointToolType* toolType)

Description

Obtains the ArkUI XComponent touch point tool type.

Since: 9

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
uint32_t pointIndex Index of the touch point. The value range is [0, OH_NATIVE_XCOMPONENT_MAX_TOUCH_POINTS_NUMBER - 1]. A value out of this range will return a parameter error.
OH_NativeXComponent_TouchPointToolType* toolType Pointer to the tool type.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_GetTouchPointTiltX()

int32_t OH_NativeXComponent_GetTouchPointTiltX(OH_NativeXComponent* component, uint32_t pointIndex, float* tiltX)

Description

Obtains the angle between the Y-Z plane of the ArkUI XComponent touch point and the x-axis.

Since: 9

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
uint32_t pointIndex Pointer index of the touch point. The value range is [0, Number of touch points in the touch event - 1]. If an invalid index is passed, OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER is returned.
float* tiltX Pointer to the tilt angle of the touch point along the X-axis. The value range is [-90, 90], in degrees.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_GetTouchPointTiltY()

int32_t OH_NativeXComponent_GetTouchPointTiltY(OH_NativeXComponent* component, uint32_t pointIndex, float* tiltY)

Description

Obtains the angle between the X-Z plane of the ArkUI XComponent touch point and the y-axis.

Since: 9

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
uint32_t pointIndex Index of the touch point. The value range is [0, OH_NATIVE_XCOMPONENT_MAX_TOUCH_POINTS_NUMBER). The information can be correctly obtained only when the passed index is a valid touch point index in the current touch event.
float* tiltY Pointer to the tilt angle of the touch point along the Y-axis. The value ranges from [-90, 90], in degrees.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_GetTouchPointWindowX()

int32_t OH_NativeXComponent_GetTouchPointWindowX(OH_NativeXComponent* component, uint32_t pointIndex, float* windowX)

Description

Obtains the x-coordinate of the touch point relative to the upper left corner of the application window where the ArkUI XComponent is located.

Since: 12

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
uint32_t pointIndex Index of the touch point. The value range is [0, Number of touch points in the current touch event - 1], and does not exceed OH_NATIVE_XCOMPONENT_MAX_TOUCH_POINTS_NUMBER minus 1. If an out-of-bounds index is passed, OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER is returned.
float* windowX Pointer to the X-coordinate of the touch point relative to the upper left corner of the application window. Unit: px.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if windowX is obtained successfully.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if component is a null pointer, windowX is a null pointer, or Native XComponent is a null pointer.

[h2]OH_NativeXComponent_GetTouchPointWindowY()

int32_t OH_NativeXComponent_GetTouchPointWindowY(OH_NativeXComponent* component, uint32_t pointIndex, float* windowY)

Description

Obtains the y-coordinate of the touch point relative to the upper left corner of the application window where the ArkUI XComponent is located.

Since: 12

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
uint32_t pointIndex Pointer index of the touch point. The value range is [0, OH_NATIVE_XCOMPONENT_MAX_TOUCH_POINTS_NUMBER - 1].
float* windowY Pointer to the Y-coordinate of the touch point relative to the upper left corner of the application window. Unit: px.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if windowY is obtained successfully.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if component is a null pointer, windowY is a null pointer, or Native XComponent is a null pointer.

[h2]OH_NativeXComponent_GetTouchPointDisplayX()

int32_t OH_NativeXComponent_GetTouchPointDisplayX(OH_NativeXComponent* component, uint32_t pointIndex, float* displayX)

Description

Obtains the x-coordinate of the touch point relative to the upper left corner of the screen where the ArkUI XComponent is located.

Since: 12

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
uint32_t pointIndex Pointer index of the touch point.
float* displayX Pointer to the X-coordinate of the touch point relative to the upper left corner of the display where the application is located. Unit: px.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if displayX is obtained successfully.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if component is a null pointer, displayX is a null pointer, or Native XComponent is a null pointer.

[h2]OH_NativeXComponent_GetTouchPointDisplayY()

int32_t OH_NativeXComponent_GetTouchPointDisplayY(OH_NativeXComponent* component, uint32_t pointIndex, float* displayY)

Description

Obtains the y-coordinate of the touch point relative to the upper left corner of the screen where the ArkUI XComponent is located.

Since: 12

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
uint32_t pointIndex Pointer index of the touch point.
float* displayY Pointer to the Y-coordinate of the touch point relative to the upper left corner of the display where the application is located. Unit: px.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if displayY is obtained successfully.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if component is a null pointer, displayY is a null pointer, or Native XComponent is a null pointer.

[h2]OH_NativeXComponent_GetHistoricalPoints()

int32_t OH_NativeXComponent_GetHistoricalPoints(OH_NativeXComponent* component, const void* window,int32_t* size, OH_NativeXComponent_HistoricalPoint** historicalPoints)

Description

Obtains the historical point information of the current XComponent touch event. Some input devices report touch points at a very high frequency (up to once every 1 ms), while the response to input events is usually intended to change the UI in response to user operations. If touch events are reported to the application at the same frequency as touch point reporting, most of them will cause redundancy. Therefore, touch events are reported to the application only once per frame. All touch points reported within the current frame are saved as historical points. If the application needs to process this data directly, it can call this API to obtain the historical point information.

Since: 10

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
const void* window Handle to the NativeWindow instance.
int32_t* size Pointer to the length of the current historical point array.
OH_NativeXComponent_HistoricalPoint** historicalPoints Pointer to the historical touch point array.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_GetMouseEvent()

int32_t OH_NativeXComponent_GetMouseEvent(OH_NativeXComponent* component, const void* window, OH_NativeXComponent_MouseEvent* mouseEvent)

Description

Obtains the mouse event scheduled by the ArkUI XComponent.

Since: 9

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
const void* window Handle to the NativeWindow instance.
OH_NativeXComponent_MouseEvent* mouseEvent Pointer to the current mouse event.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_RegisterCallback()

int32_t OH_NativeXComponent_RegisterCallback(OH_NativeXComponent* component, OH_NativeXComponent_Callback* callback)

Description

Registers a callback for this OH_NativeXComponent instance.

Since: 8

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
OH_NativeXComponent_Callback* callback Pointer to the surface lifecycle and touch event callback.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_RegisterMouseEventCallback()

int32_t OH_NativeXComponent_RegisterMouseEventCallback(OH_NativeXComponent* component, OH_NativeXComponent_MouseEvent_Callback* callback)

Description

Registers a mouse event callback for this OH_NativeXComponent instance.

Since: 9

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
OH_NativeXComponent_MouseEvent_Callback* callback Pointer to the mouse event callback.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_GetExtraMouseEventInfo()

int32_t OH_NativeXComponent_GetExtraMouseEventInfo(OH_NativeXComponent* component, OH_NativeXComponent_ExtraMouseEventInfo** extraMouseEventInfo)

Description

Obtains extended mouse event information from this OH_NativeXComponent instance.

Since: 20

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
OH_NativeXComponent_ExtraMouseEventInfo** extraMouseEventInfo Address of a pointer to the OH_NativeXComponent_ExtraMouseEventInfo type.

Returns

Type Description
int32_t

Result code.

Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful.

Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

[h2]OH_NativeXComponent_GetMouseEventModifierKeyStates()

int32_t OH_NativeXComponent_GetMouseEventModifierKeyStates(OH_NativeXComponent_ExtraMouseEventInfo* extraMouseEventInfo, uint64_t* keys)

Description

Obtains the state of modifier keys from an OH_NativeXComponent_ExtraMouseEventInfo instance.

Since: 20

Parameters

Name Description
OH_NativeXComponent_ExtraMouseEventInfo* extraMouseEventInfo Pointer to the extended mouse event information instance.
uint64_t* keys Pointer to the 64-bit unsigned integer used to receive the functional key press state. Each bit corresponds to the press state of a functional key (for example, a bit value of 1 indicates that the corresponding key is pressed). For the mapping between specific bits and functional keys, see the definition of functional key state bits.

Returns

Type Description
int32_t

Result code.

Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful.

Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

[h2]OH_NativeXComponent_RegisterFocusEventCallback()

int32_t OH_NativeXComponent_RegisterFocusEventCallback(OH_NativeXComponent* component, void (*callback)(OH_NativeXComponent* component, void* window))

Description

Registers a focus event callback for this OH_NativeXComponent instance.

Since: 10

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
void (*callback)(OH_NativeXComponent* component, void* window) Pointer to the callback invoked when the component gains focus. - window: NativeWindow handle.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_RegisterKeyEventCallback()

int32_t OH_NativeXComponent_RegisterKeyEventCallback(OH_NativeXComponent* component, void (*callback)(OH_NativeXComponent* component, void* window))

Description

Registers a key event callback for this OH_NativeXComponent instance.

Since: 10

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
void (*callback)(OH_NativeXComponent* component, void* window) Pointer to the key event callback. - window: handle to the NativeWindow instance.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_RegisterBlurEventCallback()

int32_t OH_NativeXComponent_RegisterBlurEventCallback(OH_NativeXComponent* component, void (*callback)(OH_NativeXComponent* component, void* window))

Description

Registers a blur event callback for this OH_NativeXComponent instance.

Since: 10

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
void (*callback)(OH_NativeXComponent* component, void* window) Pointer to the blur event callback. - window: handle to the NativeWindow instance.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_GetKeyEvent()

int32_t OH_NativeXComponent_GetKeyEvent(OH_NativeXComponent* component, OH_NativeXComponent_KeyEvent** keyEvent)

Description

Obtains the key event scheduled by the ArkUI XComponent.

Since: 10

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
OH_NativeXComponent_KeyEvent** keyEvent Pointer to the current key event.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_GetKeyEventAction()

int32_t OH_NativeXComponent_GetKeyEventAction(OH_NativeXComponent_KeyEvent* keyEvent, OH_NativeXComponent_KeyAction* action)

Description

Obtains the action of the specified key event.

Since: 10

Parameters

Name Description
OH_NativeXComponent_KeyEvent* keyEvent Pointer to an OH_NativeXComponent_KeyEvent instance.
OH_NativeXComponent_KeyAction* action Pointer to the key event action.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_GetKeyEventCode()

int32_t OH_NativeXComponent_GetKeyEventCode(OH_NativeXComponent_KeyEvent* keyEvent, OH_NativeXComponent_KeyCode* code)

Description

Obtains the key code of the specified key event.

Since: 10

Parameters

Name Description
OH_NativeXComponent_KeyEvent* keyEvent Pointer to an OH_NativeXComponent_KeyEvent instance.
OH_NativeXComponent_KeyCode* code Pointer to the key code of the key event.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_GetKeyEventSourceType()

int32_t OH_NativeXComponent_GetKeyEventSourceType(OH_NativeXComponent_KeyEvent* keyEvent, OH_NativeXComponent_EventSourceType* sourceType)

Description

Obtains the source type of the specified key event.

Since: 10

Parameters

Name Description
OH_NativeXComponent_KeyEvent* keyEvent Pointer to an OH_NativeXComponent_KeyEvent instance.
OH_NativeXComponent_EventSourceType* sourceType Pointer to the event source type of the key event.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_GetKeyEventDeviceId()

int32_t OH_NativeXComponent_GetKeyEventDeviceId(OH_NativeXComponent_KeyEvent* keyEvent, int64_t* deviceId)

Description

Obtains the device ID of the specified key event.

Since: 10

Parameters

Name Description
OH_NativeXComponent_KeyEvent* keyEvent Pointer to an OH_NativeXComponent_KeyEvent instance.
int64_t* deviceId Pointer to the device ID of the key event.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_GetKeyEventTimestamp()

int32_t OH_NativeXComponent_GetKeyEventTimestamp(OH_NativeXComponent_KeyEvent* keyEvent, int64_t* timestamp)

Description

Obtains the timestamp of the specified key event.

Since: 10

Parameters

Name Description
OH_NativeXComponent_KeyEvent* keyEvent Pointer to an OH_NativeXComponent_KeyEvent instance.
int64_t* timestamp Pointer to the key event timestamp. Unit: nanoseconds.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_GetKeyEventModifierKeyStates()

int32_t OH_NativeXComponent_GetKeyEventModifierKeyStates(OH_NativeXComponent_KeyEvent* keyEvent, uint64_t* keys)

Description

Obtains the state of modifier keys from a key event.

Since: 20

Parameters

Name Description
OH_NativeXComponent_KeyEvent* keyEvent Pointer to the key event.
uint64_t* keys Pointer to the 64-bit unsigned integer used to receive functional key press state information. Each bit corresponds to the press state of a functional key. For the mapping between bits and functional keys, see the definition of functional key state bits in ArkUI_UIInputEvent.

Returns

Type Description
int32_t

Result code.

Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful.

Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

[h2]OH_NativeXComponent_GetKeyEventNumLockState()

int32_t OH_NativeXComponent_GetKeyEventNumLockState(OH_NativeXComponent_KeyEvent* keyEvent, bool* isNumLockOn)

Description

Obtains the state of the NumLock key from a key event.

Since: 20

Parameters

Name Description
OH_NativeXComponent_KeyEvent* keyEvent Pointer to the key event.
bool* isNumLockOn Pointer to a boolean variable to receive the state of the NumLock key. true: NumLock is enabled. false: NumLock is disabled.

Returns

Type Description
int32_t

Result code.

Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful.

Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

[h2]OH_NativeXComponent_GetKeyEventCapsLockState()

int32_t OH_NativeXComponent_GetKeyEventCapsLockState(OH_NativeXComponent_KeyEvent* keyEvent, bool* isCapsLockOn)

Description

Obtains the state of the CapsLock key from a key event.

Since: 20

Parameters

Name Description
OH_NativeXComponent_KeyEvent* keyEvent Pointer to the key event.
bool* isCapsLockOn Pointer to a boolean variable to receive the state of the CapsLock key. true: CapsLock is enabled. false: CapsLock is disabled.

Returns

Type Description
int32_t

Result code.

Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful.

Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

[h2]OH_NativeXComponent_GetKeyEventScrollLockState()

int32_t OH_NativeXComponent_GetKeyEventScrollLockState(OH_NativeXComponent_KeyEvent* keyEvent, bool* isScrollLockOn)

Description

Obtains the state of the ScrollLock key from a key event.

Since: 20

Parameters

Name Description
OH_NativeXComponent_KeyEvent* keyEvent Pointer to the key event.
bool* isScrollLockOn Pointer to a boolean variable to receive the state of the ScrollLock key. true: ScrollLock is enabled. false: ScrollLock is disabled.

Returns

Type Description
int32_t

Result code.

Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful.

Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

[h2]OH_NativeXComponent_SetExpectedFrameRateRange()

int32_t OH_NativeXComponent_SetExpectedFrameRateRange(OH_NativeXComponent* component, OH_NativeXComponent_ExpectedRateRange* range)

Description

Sets the expected frame rate range.

Since: 11

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
OH_NativeXComponent_ExpectedRateRange* range Pointer to the expected frame rate information object of the OH_NativeXComponent_ExpectedRateRange type.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_RegisterOnFrameCallback()

int32_t OH_NativeXComponent_RegisterOnFrameCallback(OH_NativeXComponent* component,void (*callback)(OH_NativeXComponent* component, uint64_t timestamp, uint64_t targetTimestamp))

Description

Registers the display update callback for this OH_NativeXComponent instance and enables the callback for each frame.

Since: 11

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
void (*callback)(OH_NativeXComponent* component, uint64_t timestamp, uint64_t targetTimestamp) Pointer to the display update callback. - timestamp: time when the current frame arrives, in ns. - targetTimestamp: expected arrival time of the next frame, in ns.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_UnregisterOnFrameCallback()

int32_t OH_NativeXComponent_UnregisterOnFrameCallback(OH_NativeXComponent* component)

Description

Deregisters the display update callback for this OH_NativeXComponent instance and disables the callback for each frame.

Since: 11

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_AttachNativeRootNode()

int32_t OH_NativeXComponent_AttachNativeRootNode(OH_NativeXComponent* component, ArkUI_NodeHandle root)

Description

Attaches the UI component created through the native API of ArkUI to this OH_NativeXComponent instance.

When the attached component is no longer needed, OH_NativeXComponent_DetachNativeRootNode must be called to detach it to avoid memory leaks.

Since: 12

Deprecated from: 20

Substitute: OH_ArkUI_NodeContent_AddNode

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
ArkUI_NodeHandle root Pointer to the component instance created through the native API.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_DetachNativeRootNode()

int32_t OH_NativeXComponent_DetachNativeRootNode(OH_NativeXComponent* component, ArkUI_NodeHandle root)

Description

Detaches the native component of ArkUI from this OH_NativeXComponent instance.

Since: 12

Deprecated from: 20

Substitute: OH_ArkUI_NodeContent_RemoveNode

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
ArkUI_NodeHandle root Pointer to the component instance created through the native API.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_RegisterUIInputEventCallback()

int32_t OH_NativeXComponent_RegisterUIInputEventCallback(OH_NativeXComponent *component,void (*callback)(OH_NativeXComponent *component, ArkUI_UIInputEvent *event,ArkUI_UIInputEvent_Type type),ArkUI_UIInputEvent_Type type)

Description

Registers a UI input event callback for this OH_NativeXComponent instance and enables this callback to be invoked when a UI input event is received. Currently, only axis events are supported.

Since: 12

Parameters

Name Description
OH_NativeXComponent *component Pointer to an OH_NativeXComponent instance.
void (*callback)(OH_NativeXComponent *component, ArkUI_UIInputEvent *event,ArkUI_UIInputEvent_Type type) Pointer to the UI input event callback. - event: pointer to the UI input event.
ArkUI_UIInputEvent_Type type Type of the UI input event for which the callback is registered. Currently, only the axis event type is supported.

Returns

Type Description
int32_t

Result code.

Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful.

Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

[h2]OH_NativeXComponent_RegisterOnTouchInterceptCallback()

int32_t OH_NativeXComponent_RegisterOnTouchInterceptCallback(OH_NativeXComponent* component, HitTestMode (*callback)(OH_NativeXComponent* component, ArkUI_UIInputEvent* event))

Description

Registers a custom event intercept callback for this OH_NativeXComponent instance and enables this callback to be invoked during hit testing. UI input–related operations are not supported on event objects received through this callback. For full functionality, use the NODE_ON_TOUCH_INTERCEPT event on native nodes instead.

Since: 12

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
HitTestMode (*callback)(OH_NativeXComponent* component, ArkUI_UIInputEvent* event) Pointer to the custom event intercept callback. - event: pointer to the UI input event.

Returns

Type Description
int32_t

Result code.

Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful.

Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

[h2]OH_NativeXComponent_SetNeedSoftKeyboard()

int32_t OH_NativeXComponent_SetNeedSoftKeyboard(OH_NativeXComponent* component, bool needSoftKeyboard)

Description

Sets whether the soft keyboard is required for this OH_NativeXComponent instance.

Since: 12

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
bool needSoftKeyboard Whether the soft keyboard is required for the current OH_NativeXComponent instance. true if the soft keyboard is required, false otherwise. The default value is false.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_RegisterSurfaceShowCallback()

int32_t OH_NativeXComponent_RegisterSurfaceShowCallback(OH_NativeXComponent* component, void (*callback)(OH_NativeXComponent* component, void* window))

Description

Registers a surface display callback for this OH_NativeXComponent instance. This callback is invoked after the application is switched to the foreground.

Since: 12

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
void (*callback)(OH_NativeXComponent* component, void* window) Pointer to the surface display callback. - window: handle to the NativeWindow instance.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_RegisterSurfaceHideCallback()

int32_t OH_NativeXComponent_RegisterSurfaceHideCallback(OH_NativeXComponent* component, void (*callback)(OH_NativeXComponent* component, void* window))

Description

Registers a surface hiding callback for this OH_NativeXComponent instance. This callback is invoked after the application is switched to the background.

Since: 12

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
void (*callback)(OH_NativeXComponent* component, void* window) Pointer to the surface hiding callback. - window: handle to the NativeWindow instance.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_NativeXComponent_GetTouchEventSourceType()

int32_t OH_NativeXComponent_GetTouchEventSourceType(OH_NativeXComponent* component, int32_t pointId, OH_NativeXComponent_EventSourceType* sourceType)

Description

Obtains the touch event source type of an ArkUI XComponent instance.

Since: 12

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
int32_t pointId ID of the touch point. The input device type can be correctly returned only when the passed-in ID is the touch point ID that triggers the touch event; otherwise, OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER is returned.
OH_NativeXComponent_EventSourceType* sourceType Pointer to the touch event source type.

Returns

Type Description
int32_t

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

Returns OH_NATIVEXCOMPONENT_RESULT_FAILED if any other error occurs.

[h2]OH_NativeXComponent_GetNativeXComponent()

OH_NativeXComponent* OH_NativeXComponent_GetNativeXComponent(ArkUI_NodeHandle node)

Description

Obtains a pointer of the OH_NativeXComponent type based on the specified component instance created by the native API.

Since: 12

Parameters

Name Description
ArkUI_NodeHandle node Pointer to the component instance created by the native API.

Returns

Type Description
OH_NativeXComponent* Pointer to an OH_NativeXComponent instance.

[h2]OH_NativeXComponent_GetNativeAccessibilityProvider()

int32_t OH_NativeXComponent_GetNativeAccessibilityProvider(OH_NativeXComponent* component, ArkUI_AccessibilityProvider** handle)

Description

Obtains the accessibility provider handle for an ArkUI XComponent.

Since: 13

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
ArkUI_AccessibilityProvider** handle Double pointer to the ArkUI_AccessibilityProvider instance (that is, the address used to receive the instance pointer).

Returns

Type Description
int32_t

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

Returns OH_NATIVEXCOMPONENT_RESULT_FAILED if any other error occurs.

[h2]OH_NativeXComponent_RegisterKeyEventCallbackWithResult()

int32_t OH_NativeXComponent_RegisterKeyEventCallbackWithResult(OH_NativeXComponent* component, bool (*callback)(OH_NativeXComponent* component, void* window))

Description

Registers a key event callback with a return value for this OH_NativeXComponent instance. The callback must return a result (true or false). If the callback returns true, the event will not be further propagated. If it returns false, the event will continue to be processed according to the normal event handling flow.

Since: 14

Parameters

Name Description
OH_NativeXComponent* component Pointer to an OH_NativeXComponent instance.
bool (*callback)(OH_NativeXComponent* component, void* window) Pointer to the key event callback. - window: handle to the NativeWindow instance. If the callback returns true, the event will not be further propagated. If it returns false, the event will continue to be processed according to the normal event handling flow.

Returns

Type Description
int32_t

Result code.

Returns OH_NATIVEXCOMPONENT_RESULT_SUCCESS if the operation is successful.

Returns OH_NATIVEXCOMPONENT_RESULT_BAD_PARAMETER if a parameter error occurs.

[h2]OH_ArkUI_XComponent_StartImageAnalyzer()

int32_t OH_ArkUI_XComponent_StartImageAnalyzer(ArkUI_NodeHandle node, void* userData,void (*callback)(ArkUI_NodeHandle node, ArkUI_XComponent_ImageAnalyzerState statusCode, void* userData))

Description

Starts AI image analysis for this XComponent instance. Before calling this API, make sure the AI image analysis capability is enabled (for example, through the enableAnalyzer attribute of the XComponent component).

Since: 18

Parameters

Name Description
ArkUI_NodeHandle node Pointer to the XComponent instance.
void* userData Pointer to the data that you need to obtain when the callback function is executed.
void (*callback)(ArkUI_NodeHandle node, ArkUI_XComponent_ImageAnalyzerState statusCode, void* userData) Pointer to the callback function triggered when the AI image analysis status is updated. - statusCode: one of the input parameters of the callback function, indicating the current image analysis status.

Returns

Type Description
int32_t

Result code.

Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful.

Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

[h2]OH_ArkUI_XComponent_StopImageAnalyzer()

int32_t OH_ArkUI_XComponent_StopImageAnalyzer(ArkUI_NodeHandle node)

Description

Stops AI image analysis for this XComponent instance.

Since: 18

Parameters

Name Description
ArkUI_NodeHandle node XComponent instance.

Returns

Type Description
int32_t

Result code.

Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful.

Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

[h2]OH_ArkUI_SurfaceHolder_Create()

OH_ArkUI_SurfaceHolder* OH_ArkUI_SurfaceHolder_Create(ArkUI_NodeHandle node)

Description

Creates an OH_ArkUI_SurfaceHolder object for an XComponent.

Since: 19

Parameters

Name Description
ArkUI_NodeHandle node Pointer to the XComponent instance created through the native API.

Returns

Type Description
OH_ArkUI_SurfaceHolder* Pointer to the created OH_ArkUI_SurfaceHolder object.

[h2]OH_ArkUI_SurfaceHolder_Dispose()

void OH_ArkUI_SurfaceHolder_Dispose(OH_ArkUI_SurfaceHolder* surfaceHolder)

Description

Disposes of an OH_ArkUI_SurfaceHolder object.

Since: 19

Parameters

Name Description
OH_ArkUI_SurfaceHolder* surfaceHolder Pointer to the target OH_ArkUI_SurfaceHolder instance.

[h2]OH_ArkUI_SurfaceHolder_SetUserData()

int32_t OH_ArkUI_SurfaceHolder_SetUserData(OH_ArkUI_SurfaceHolder* surfaceHolder, void* userData)

Description

Stores custom data in an OH_ArkUI_SurfaceHolder instance.

Since: 19

Parameters

Name Description
OH_ArkUI_SurfaceHolder* surfaceHolder Pointer to the target OH_ArkUI_SurfaceHolder instance.
void* userData Pointer to the custom data to be stored.

Returns

Type Description
int32_t

Result code.

Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful.

Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

[h2]OH_ArkUI_SurfaceHolder_GetUserData()

void* OH_ArkUI_SurfaceHolder_GetUserData(OH_ArkUI_SurfaceHolder* surfaceHolder)

Description

Obtains the custom data stored in an OH_ArkUI_SurfaceHolder instance.

Since: 19

Parameters

Name Description
OH_ArkUI_SurfaceHolder* surfaceHolder Pointer to the target OH_ArkUI_SurfaceHolder instance.

Returns

Type Description
void* Custom data.

[h2]OH_ArkUI_SurfaceCallback_Create()

OH_ArkUI_SurfaceCallback* OH_ArkUI_SurfaceCallback_Create()

Description

Creates an OH_ArkUI_SurfaceCallback object.

Since: 19

Returns

Type Description
OH_ArkUI_SurfaceCallback* Pointer to the created OH_ArkUI_SurfaceCallback object.

[h2]OH_ArkUI_SurfaceCallback_Dispose()

void OH_ArkUI_SurfaceCallback_Dispose(OH_ArkUI_SurfaceCallback* callback)

Description

Disposes of an OH_ArkUI_SurfaceCallback object.

Since: 19

Parameters

Name Description
OH_ArkUI_SurfaceCallback* callback Pointer to the target OH_ArkUI_SurfaceCallback instance.

[h2]OH_ArkUI_SurfaceCallback_SetSurfaceCreatedEvent()

void OH_ArkUI_SurfaceCallback_SetSurfaceCreatedEvent(OH_ArkUI_SurfaceCallback* callback,void (*onSurfaceCreated)(OH_ArkUI_SurfaceHolder* surfaceHolder))

Description

Sets the creation callback event in the surface lifecycle callbacks.

Since: 19

Parameters

Name Description
OH_ArkUI_SurfaceCallback* callback Pointer to the surface lifecycle callback.
void (*onSurfaceCreated)(OH_ArkUI_SurfaceHolder* surfaceHolder) Callback event triggered when the surface is created. - surfaceHolder: pointer to the target OH_ArkUI_SurfaceHolder instance.

[h2]OH_ArkUI_SurfaceCallback_SetSurfaceChangedEvent()

void OH_ArkUI_SurfaceCallback_SetSurfaceChangedEvent(OH_ArkUI_SurfaceCallback* callback,void (*onSurfaceChanged)(OH_ArkUI_SurfaceHolder* surfaceHolder, uint64_t width, uint64_t height))

Description

Sets the size change callback event in the surface lifecycle callbacks.

Since: 19

Parameters

Name Description
OH_ArkUI_SurfaceCallback* callback Pointer to the surface lifecycle callback.
void (*onSurfaceChanged)(OH_ArkUI_SurfaceHolder* surfaceHolder, uint64_t width, uint64_t height) Callback event triggered when the surface size changes. - surfaceHolder: pointer to the target OH_ArkUI_SurfaceHolder instance. - width: new width of the surface after the size change. Unit: vp. - height: new height of the surface after the size change. Unit: vp.

[h2]OH_ArkUI_SurfaceCallback_SetSurfaceDestroyedEvent()

void OH_ArkUI_SurfaceCallback_SetSurfaceDestroyedEvent(OH_ArkUI_SurfaceCallback* callback,void (*onSurfaceDestroyed)(OH_ArkUI_SurfaceHolder* surfaceHolder))

Description

Sets the destruction callback event in the surface lifecycle callbacks.

Since: 19

Parameters

Name Description
OH_ArkUI_SurfaceCallback* callback Pointer to the surface lifecycle callback.
void (*onSurfaceDestroyed)(OH_ArkUI_SurfaceHolder* surfaceHolder) Callback event triggered when the surface is destroyed. - surfaceHolder: pointer to the target OH_ArkUI_SurfaceHolder instance.

[h2]OH_ArkUI_SurfaceHolder_AddSurfaceCallback()

int32_t OH_ArkUI_SurfaceHolder_AddSurfaceCallback(OH_ArkUI_SurfaceHolder* surfaceHolder,OH_ArkUI_SurfaceCallback* callback)

Description

Adds a surface lifecycle callback to an OH_ArkUI_SurfaceHolder instance.

Since: 19

Parameters

Name Description
OH_ArkUI_SurfaceHolder* surfaceHolder Pointer to the target OH_ArkUI_SurfaceHolder instance.
OH_ArkUI_SurfaceCallback* callback Pointer to the new callback.

Returns

Type Description
int32_t

Result code.

Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful.

Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

[h2]OH_ArkUI_SurfaceHolder_RemoveSurfaceCallback()

int32_t OH_ArkUI_SurfaceHolder_RemoveSurfaceCallback(OH_ArkUI_SurfaceHolder* surfaceHolder,OH_ArkUI_SurfaceCallback* callback)

Description

Removes a previously added surface lifecycle callback from an OH_ArkUI_SurfaceHolder instance.

Since: 19

Parameters

Name Description
OH_ArkUI_SurfaceHolder* surfaceHolder Pointer to the target OH_ArkUI_SurfaceHolder instance.
OH_ArkUI_SurfaceCallback* callback Pointer to the callback to be removed.

Returns

Type Description
int32_t

Result code.

Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful.

Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

[h2]OH_ArkUI_XComponent_GetNativeWindow()

OHNativeWindow* OH_ArkUI_XComponent_GetNativeWindow(OH_ArkUI_SurfaceHolder* surfaceHolder)

Description

Obtains the NativeWindow instance associated with an OH_ArkUI_SurfaceHolder instance.

Since: 19

Parameters

Name Description
OH_ArkUI_SurfaceHolder* surfaceHolder Pointer to the target OH_ArkUI_SurfaceHolder instance.

Returns

Type Description
OHNativeWindow* Pointer to OHNativeWindow associated with the OH_ArkUI_SurfaceHolder instance.

[h2]OH_ArkUI_XComponent_SetAutoInitialize()

int32_t OH_ArkUI_XComponent_SetAutoInitialize(ArkUI_NodeHandle node, bool autoInitialize)

Description

Sets whether the XComponent component needs to automatically initialize the surface.

Configuration dependency:

Since: 19

Parameters

Name Description
ArkUI_NodeHandle node Pointer to the XComponent component instance.
bool autoInitialize

Whether the XComponent needs to automatically initialize the surface. If the value is true, the OnSurfaceCreated callback is triggered when the component is attached to the component tree, and the OnSurfaceDestroyed callback is triggered when the component is detached from the component tree. The value false indicates that the component does not need to automatically initialize the surface.

The default value of autoInitialize is true.

Returns

Type Description
int32_t

Result code.

Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful.

Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

[h2]OH_ArkUI_XComponent_Initialize()

int32_t OH_ArkUI_XComponent_Initialize(ArkUI_NodeHandle node)

Description

Initializes the surface held by the XComponent component.

Call in pair:

Since: 19

Parameters

Name Description
ArkUI_NodeHandle node Pointer to the XComponent component instance.

Returns

Type Description
int32_t

Result code.

Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful.

Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

Returns ARKUI_ERROR_CODE_XCOMPONENT_STATE_INVALID if the surface held by the XComponent component has been initialized.

[h2]OH_ArkUI_XComponent_Finalize()

int32_t OH_ArkUI_XComponent_Finalize(ArkUI_NodeHandle node)

Description

Destroys the surface held by the XComponent component.

Call in pair:

Since: 19

Parameters

Name Description
ArkUI_NodeHandle node Pointer to the XComponent component instance.

Returns

Type Description
int32_t

Result code.

Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful.

Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

Returns ARKUI_ERROR_CODE_XCOMPONENT_STATE_INVALID if the surface held by the XComponent component has been finalized.

[h2]OH_ArkUI_XComponent_IsInitialized()

int32_t OH_ArkUI_XComponent_IsInitialized(ArkUI_NodeHandle node, bool* isInitialized)

Description

Checks whether the surface held by the XComponent component is initialized.

Since: 19

Parameters

Name Description
ArkUI_NodeHandle node Pointer to the XComponent component instance.
bool* isInitialized Whether the surface held by the XComponent component is initialized. true: The surface is initialized. false: The surface is not initialized.

Returns

Type Description
int32_t

Result code.

Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful.

Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

[h2]OH_ArkUI_XComponent_SetExpectedFrameRateRange()

int32_t OH_ArkUI_XComponent_SetExpectedFrameRateRange(ArkUI_NodeHandle node, OH_NativeXComponent_ExpectedRateRange range)

Description

Sets an expected frame rate range for this XComponent instance.

Since: 20

Parameters

Name Description
ArkUI_NodeHandle node XComponent instance.
OH_NativeXComponent_ExpectedRateRange range Expected frame rate information object of the OH_NativeXComponent_ExpectedRateRange type.

Returns

Type Description
int32_t

Result code.

Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful.

Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

[h2]OH_ArkUI_XComponent_RegisterOnFrameCallback()

int32_t OH_ArkUI_XComponent_RegisterOnFrameCallback(ArkUI_NodeHandle node,void (*callback)(ArkUI_NodeHandle node, uint64_t timestamp, uint64_t targetTimestamp))

Description

Registers a frame callback function for the XComponent.

Since: 20

Parameters

Name Description
ArkUI_NodeHandle node XComponent instance.
void (*callback)(ArkUI_NodeHandle node, uint64_t timestamp, uint64_t targetTimestamp) Pointer to the frame callback function. - timestamp: arrival time of the current frame (number of nanoseconds since the system startup), in nanoseconds. - targetTimestamp: expected arrival time of the next frame (number of nanoseconds from system startup to the expected moment of the next frame), in nanoseconds.

Returns

Type Description
int32_t

Result code.

Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful.

Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

[h2]OH_ArkUI_XComponent_UnregisterOnFrameCallback()

int32_t OH_ArkUI_XComponent_UnregisterOnFrameCallback(ArkUI_NodeHandle node)

Description

Unregisters the frame callback function for the XComponent.

Since: 20

Parameters

Name Description
ArkUI_NodeHandle node XComponent instance.

Returns

Type Description
int32_t

Result code.

Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful.

Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

[h2]OH_ArkUI_XComponent_SetNeedSoftKeyboard()

int32_t OH_ArkUI_XComponent_SetNeedSoftKeyboard(ArkUI_NodeHandle node, bool needSoftKeyboard)

Description

Sets whether the soft keyboard is required for the XComponent.

Since: 20

Parameters

Name Description
ArkUI_NodeHandle node XComponent instance.
bool needSoftKeyboard Whether the soft keyboard is required. true if the soft keyboard is required, false otherwise. The default value is false.

Returns

Type Description
int32_t

Result code.

Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful.

Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.

[h2]OH_ArkUI_AccessibilityProvider_Create()

ArkUI_AccessibilityProvider* OH_ArkUI_AccessibilityProvider_Create(ArkUI_NodeHandle node)

Description

Creates an ArkUI_AccessibilityProvider instance for this XComponent instance.

Since: 20

Parameters

Name Description
ArkUI_NodeHandle node XComponent instance.

Returns

Type Description
ArkUI_AccessibilityProvider* Pointer to the created ArkUI_AccessibilityProvider object, which is used for accessibility access.

[h2]OH_ArkUI_AccessibilityProvider_Dispose()

void OH_ArkUI_AccessibilityProvider_Dispose(ArkUI_AccessibilityProvider* provider)

Description

Disposes of the ArkUI_AccessibilityProvider instance created using OH_ArkUI_AccessibilityProvider_Create.

Since: 20

Parameters

Name Description
ArkUI_AccessibilityProvider* provider ArkUI_AccessibilityProvider instance created using OH_ArkUI_AccessibilityProvider_Create.

[h2]OH_ArkUI_SurfaceCallback_SetSurfaceShowEvent()

void OH_ArkUI_SurfaceCallback_SetSurfaceShowEvent(OH_ArkUI_SurfaceCallback* callback,void (*onSurfaceShow)(OH_ArkUI_SurfaceHolder* surfaceHolder))

Description

Sets a surface display callback for this OH_ArkUI_SurfaceCallback instance. This callback is invoked when the application window has moved from the background to the foreground.

Since: 20

Parameters

Name Description
OH_ArkUI_SurfaceCallback* callback Pointer to the OH_ArkUI_SurfaceCallback instance.
void (*onSurfaceShow)(OH_ArkUI_SurfaceHolder* surfaceHolder) Pointer to the callback invoked when the surface is displayed. - surfaceHolder: pointer to the OH_ArkUI_SurfaceHolder instance.

[h2]OH_ArkUI_SurfaceCallback_SetSurfaceHideEvent()

void OH_ArkUI_SurfaceCallback_SetSurfaceHideEvent(OH_ArkUI_SurfaceCallback* callback,void (*onSurfaceHide)(OH_ArkUI_SurfaceHolder* surfaceHolder))

Description

Sets a surface hiding callback for this OH_ArkUI_SurfaceCallback instance. This callback is invoked when the application window has moved from the foreground to the background.

Since: 20

Parameters

Name Description
OH_ArkUI_SurfaceCallback* callback Pointer to the OH_ArkUI_SurfaceCallback instance.
void (*onSurfaceHide)(OH_ArkUI_SurfaceHolder* surfaceHolder) Pointer to the callback invoked when the surface is hidden. - surfaceHolder: pointer to the OH_ArkUI_SurfaceHolder instance.

[h2]OH_ArkUI_XComponentSurfaceConfig_Create()

ArkUI_XComponentSurfaceConfig* OH_ArkUI_XComponentSurfaceConfig_Create()

Description

Creates an ArkUI_XComponentSurfaceConfig object for an XComponent.

Since: 22

Returns

Type Description
ArkUI_XComponentSurfaceConfig* Pointer to the created ArkUI_XComponentSurfaceConfig object.

[h2]OH_ArkUI_XComponentSurfaceConfig_Dispose()

void OH_ArkUI_XComponentSurfaceConfig_Dispose(ArkUI_XComponentSurfaceConfig* config)

Description

Disposes of an ArkUI_XComponentSurfaceConfig object.

Since: 22

Parameters

Name Description
ArkUI_XComponentSurfaceConfig* config Pointer to the target ArkUI_XComponentSurfaceConfig object.

[h2]OH_ArkUI_XComponentSurfaceConfig_SetIsOpaque()

void OH_ArkUI_XComponentSurfaceConfig_SetIsOpaque(ArkUI_XComponentSurfaceConfig* config, bool isOpaque)

Description

Sets whether the surface held by the XComponent should be treated as opaque during rendering, regardless of the actual pixel transparency.

Since: 22

Parameters

Name Description
ArkUI_XComponentSurfaceConfig* config Pointer to the target ArkUI_XComponentSurfaceConfig instance.
bool isOpaque Whether the surface held by the XComponent should be treated as opaque during rendering. true if the surface should be treated as opaque, false otherwise. The default value is false, which means pixel opacity of the surface content will be applied during rendering.

[h2]OH_ArkUI_SurfaceHolder_SetSurfaceConfig()

int32_t OH_ArkUI_SurfaceHolder_SetSurfaceConfig(OH_ArkUI_SurfaceHolder* surfaceHolder, ArkUI_XComponentSurfaceConfig *config)

Description

Sets the surface configuration for the OH_ArkUI_SurfaceHolder instance.

Since: 22

Parameters

Name Description
OH_ArkUI_SurfaceHolder* surfaceHolder Pointer to the target OH_ArkUI_SurfaceHolder instance.
ArkUI_XComponentSurfaceConfig *config Pointer to the target ArkUI_XComponentSurfaceConfig instance.

Returns

Type Description
int32_t

Result code.

Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful.

Returns ARKUI_ERROR_CODE_PARAM_INVALID if a parameter error occurs.