native_interface_focus.h

Overview

Declares APIs for focus management, mainly used for actively transferring focus, managing the default focus transfer behavior, and controlling the focus activation state.

File to include: <arkui/native_interface_focus.h>

Library: libace_ndk.z.so

System capability: SystemCapability.ArkUI.ArkUI.Full

Since: 15

Related module: ArkUI_NativeModule

Sample: NdkFocus

Summary

Enums

Name	typedef Keyword	Description
ArkUI_KeyProcessingMode	ArkUI_KeyProcessingMode	Enumerates the key event processing priority modes.

Functions

Name	Description
ArkUI_ErrorCode OH_ArkUI_FocusRequest(ArkUI_NodeHandle node)	Requests focus for a specific node.
void OH_ArkUI_FocusClear(ArkUI_ContextHandle uiContext)	Clears the focus to the root container node.
void OH_ArkUI_FocusActivate(ArkUI_ContextHandle uiContext, bool isActive, bool isAutoInactive)	Sets the focus activation state for the current page. When activated, the focused node displays a focus box.
void OH_ArkUI_FocusSetAutoTransfer(ArkUI_ContextHandle uiContext, bool autoTransfer)	Configures the focus transfer behavior when pages are switched.
void OH_ArkUI_FocusSetKeyProcessingMode(ArkUI_ContextHandle uiContext, ArkUI_KeyProcessingMode mode)	Sets the mode for processing key events.

Enum Description

ArkUI_KeyProcessingMode

enum ArkUI_KeyProcessingMode

Description

Enumerates the key event processing priority modes.

Since: 15

Value	Description
ARKUI_KEY_PROCESSING_MODE_FOCUS_NAVIGATION = 0	Key events are used for focus navigation.
ARKUI_KEY_PROCESSING_MODE_FOCUS_ANCESTOR_EVENT = 1	Key events are passed up to ancestor components.

Function Description

OH_ArkUI_FocusRequest()

ArkUI_ErrorCode OH_ArkUI_FocusRequest(ArkUI_NodeHandle node)

Description

Requests focus for a specific node.

Since: 15

Parameters

Name	Description
ArkUI_NodeHandle node	Node.

Return value

Type	Description
ArkUI_ErrorCode	Result code. Returns ARKUI_ERROR_CODE_NO_ERROR if the operation is successful. Returns ARKUI_ERROR_CODE_FOCUS_NON_FOCUSABLE if the node cannot receive focus. Returns ARKUI_ERROR_CODE_FOCUS_NON_FOCUSABLE_ANCESTOR if the ancestor node cannot receive focus. Returns ARKUI_ERROR_CODE_FOCUS_NON_EXISTENT if the node does not exist.

OH_ArkUI_FocusClear()

void OH_ArkUI_FocusClear(ArkUI_ContextHandle uiContext)

Description

Clears the focus to the root container node.

Since: 15

Parameters

Name	Description
ArkUI_ContextHandle uiContext	UI instance object pointer.

OH_ArkUI_FocusActivate()

void OH_ArkUI_FocusActivate(ArkUI_ContextHandle uiContext, bool isActive, bool isAutoInactive)

Description

Sets the focus activation state for the current page. When activated, the focused node displays a focus box.

Since: 15

Parameters

Name	Description
ArkUI_ContextHandle uiContext	UI instance object pointer.
bool isActive	Whether to enter or exit the focus activation state. The value true means to enter the focus activation state, and false means to exit the focus activation state.
bool isAutoInactive	Whether to automatically exit the focus active state on touch or mouse down events. true: Automatically exit the focus active state. false: Maintain the current state until the corresponding setting API is called.

OH_ArkUI_FocusSetAutoTransfer()

void OH_ArkUI_FocusSetAutoTransfer(ArkUI_ContextHandle uiContext, bool autoTransfer)

Description

Configures the focus transfer behavior when pages are switched.

Since: 15

Parameters

Name	Description
ArkUI_ContextHandle uiContext	UI instance object pointer.
bool autoTransfer	Whether to automatically transfer focus when pages are switched. The value true means to automatically transfer focus when pages are switched, and false means the opposite.

OH_ArkUI_FocusSetKeyProcessingMode()

void OH_ArkUI_FocusSetKeyProcessingMode(ArkUI_ContextHandle uiContext, ArkUI_KeyProcessingMode mode)

Description

Sets the mode for processing key events.

Since: 15

Parameters

Name	Description
ArkUI_ContextHandle uiContext	UI instance object pointer.
ArkUI_KeyProcessingMode mode	Key event processing priority mode.