Declares APIs for focus management, mainly used for actively transferring focus, managing and controlling the default focus transfer behavior, and controlling the focus active state. It is applicable to scenarios such as page switching and keyboard navigation that require unified management of the focus state and focus transfer behavior, helping improve the predictability of focus control and the interaction experience.
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
| Name | typedef Keyword | Description |
|---|---|---|
| ArkUI_KeyProcessingMode | ArkUI_KeyProcessingMode | Enumerates the processing mode of key events. |
| 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 active state for the current page. When activated, the focused node displays a focus box. |
| void OH_ArkUI_FocusSetAutoTransfer(ArkUI_ContextHandle uiContext, bool autoTransfer) | Sets whether focus is automatically transferred when the page is switched. |
| void OH_ArkUI_FocusSetKeyProcessingMode(ArkUI_ContextHandle uiContext, ArkUI_KeyProcessingMode mode) | Sets the mode for processing key events. |
enum ArkUI_KeyProcessingMode
Description
Enumerates the processing mode of key events.
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. |
ArkUI_ErrorCode OH_ArkUI_FocusRequest(ArkUI_NodeHandle node)
Description
Requests focus for a specific node. This is applicable when focus needs to be proactively moved to a specified component, for example, setting the default focus after page initialization or navigating focus through a keyboard or remote control.
Since: 15
Parameters
| Name | Description |
|---|---|
| ArkUI_NodeHandle node | Target node for which focus is requested. |
Return value
| Type | Description |
|---|---|
| ArkUI_ErrorCode | Result code. Returns ARKUI_ERROR_CODE_NO_ERROR if the request is successful. Returns ARKUI_ERROR_CODE_FOCUS_NON_FOCUSABLE if the node cannot gain focus. Returns ARKUI_ERROR_CODE_FOCUS_NON_FOCUSABLE_ANCESTOR if the ancestor node cannot gain focus. Returns ARKUI_ERROR_CODE_FOCUS_NON_EXISTENT if the node does not exist. |
void OH_ArkUI_FocusClear(ArkUI_ContextHandle uiContext)
Description
Clears the current focus, after which the focus returns to the root container node. This is applicable when exiting the current focus interaction or when the page focus state needs to be reset.
Since: 15
Parameters
| Name | Description |
|---|---|
| ArkUI_ContextHandle uiContext | Pointer to the UI context instance object whose focus is to be cleared. |
void OH_ArkUI_FocusActivate(ArkUI_ContextHandle uiContext, bool isActive, bool isAutoInactive)
Description
Sets the focus active state of the current page, so that the focused node displays the focus frame. This is applicable when the focus position needs to be displayed in non-touch interactions such as keyboard and remote control.
Since: 15
Parameters
| Name | Description |
|---|---|
| ArkUI_ContextHandle uiContext | UI instance object pointer. |
| bool isActive | Whether to enter or exit the focus active state. The value true means to enter the focus active state, and false means to exit the focus active 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 OH_ArkUI_FocusActivate API is called. |
void OH_ArkUI_FocusSetAutoTransfer(ArkUI_ContextHandle uiContext, bool autoTransfer)
Description
Sets whether focus is automatically transferred when the page is switched.
Since: 15
Parameters
| Name | Description |
|---|---|
| ArkUI_ContextHandle uiContext | UI instance object pointer. |
| bool autoTransfer | Whether to transfer focus when the page is switched. The value true means to automatically transfer focus to the new page when the page is switched, and false means not to transfer focus. |
void OH_ArkUI_FocusSetKeyProcessingMode(ArkUI_ContextHandle uiContext, ArkUI_KeyProcessingMode mode)
Description
Sets the processing mode of key events. This is applicable when a priority policy needs to be selected between focus navigation and key event processing of ancestor components.
Since: 15
Parameters
| Name | Description |
|---|---|
| ArkUI_ContextHandle uiContext | UI instance object pointer. |
| ArkUI_KeyProcessingMode mode | Key event processing mode. |