Provides methods for creating, destroying, reading, and writing input method attach option objects, used to manage configuration parameters when an app attaches to an input method.
Functionality: Creates and manages InputMethod_AttachOptions instances. You can configure whether to show the keyboard upon attachment (showKeyboard) and the reason for requesting the keyboard (requestKeyboardReason). AttachOptions, controlling the initial behavior when attaching to the input method service, is a mandatory parameter for OH_InputMethodController_Attach.
Usage scenarios: Before an app attaches to the input method service, create AttachOptions to configure the attachment behavior.
Use effect: After you create AttachOptions, pass it to the attach function. The attach function reads its configurations to determine attachment‑time behaviors. Once the attach operation completes, AttachOptions can be destroyed, as its configuration information has already been read.
File to include: <inputmethod/inputmethod_attach_options_capi.h>
Library: libohinputmethod.so
System capability: SystemCapability.MiscServices.InputMethodFramework
Since: 12
Related module: InputMethod
| Name | typedef Keyword | Description |
|---|---|---|
| InputMethod_AttachOptions | InputMethod_AttachOptions | Input method attach options, used to carry relevant configurations when attaching to an input method. This is an opaque type. You cannot directly access its member variables and can operate it only through the functions provided in this header file. |
| Name | Description |
|---|---|
| InputMethod_AttachOptions *OH_AttachOptions_Create(bool showKeyboard) | Creates an InputMethod_AttachOptions instance, suitable for simple attachment scenarios where only the keyboard visibility needs to be controlled. |
| InputMethod_AttachOptions *OH_AttachOptions_CreateWithRequestKeyboardReason(bool showKeyboard, InputMethod_RequestKeyboardReason requestKeyboardReason) | Creates an InputMethod_AttachOptions instance, specifying both the keyboard visibility and the reason for requesting the keyboard. This function is suitable for attachment scenarios that require identifying what triggers the keyboard request. |
| void OH_AttachOptions_Destroy(InputMethod_AttachOptions *options) | Destroys an InputMethod_AttachOptions instance and releases memory resources allocated by the OH_AttachOptions_Create function. |
| InputMethod_ErrorCode OH_AttachOptions_IsShowKeyboard(InputMethod_AttachOptions *options, bool *showKeyboard) | Obtains the value indicating whether to show the keyboard from InputMethod_AttachOptions. |
| InputMethod_ErrorCode OH_AttachOptions_GetRequestKeyboardReason(InputMethod_AttachOptions *options, int *requestKeyboardReason) | Obtains the reason for requesting the keyboard from InputMethod_AttachOptions. |
InputMethod_AttachOptions *OH_AttachOptions_Create(bool showKeyboard)
Description
Creates an InputMethod_AttachOptions instance for simple scenarios where only keyboard visibility needs to be controlled. If you also need to specify the reason for requesting the keyboard, it is recommended that you use OH_AttachOptions_CreateWithRequestKeyboardReason.
Paired calls: This function must be called in pairs with OH_AttachOptions_Destroy. Objects created by OH_AttachOptions_Create must be destroyed via OH_AttachOptions_Destroy; otherwise, memory leaks will occur.
Lifecycle management:
Since: 12
Parameters
| Name | Description |
|---|---|
| bool showKeyboard | Input parameter that indicates whether to show the keyboard upon attachment. Usage scenarios: Set to true for scenarios requiring immediate input after an input box gains focus (for example, a text‑editing box). Set to false for scenarios where an interaction channel is established first with no keyboard brought up (for example, a search box that brings up the keyboard only after user clicks). Use effect: When showKeyboard is true, the keyboard pops up automatically upon successful attachment. When showKeyboard is false, the keyboard does not pop up after successful attachment; you need to call OH_InputMethodProxy_ShowKeyboard to bring up the keyboard. Value range: true or false. Default value: No default value. You must specify it explicitly. Value‑setting guideline: Parameter values are determined based on service scenarios. A value of true applies to scenarios requiring immediate input, while a value of false applies to scenarios requiring delayed keyboard display. For the latter, you can call ShowKeyboard to bring up the keyboard at a later time. |
Returns
| Type | Description |
|---|---|
| InputMethod_AttachOptions * | Pointer type. Creation successful: Returns a pointer to the newly created InputMethod_AttachOptions instance. The pointer is valid and can be used for subsequent operations. Creation failed: Returns NULL. Possible causes include full app address space (insufficient memory). Null check: You must check whether the return value is NULL before using it. If NULL is returned, the pointer cannot be used and you should troubleshoot memory conditions or retry later. Memory management: Memory for the returned pointer is allocated internally by the create function. You need to release it using OH_AttachOptions_Destroy. Do not use free() or other methods to release the memory. |
InputMethod_AttachOptions *OH_AttachOptions_CreateWithRequestKeyboardReason(bool showKeyboard, InputMethod_RequestKeyboardReason requestKeyboardReason)
Description
Creates an InputMethod_AttachOptions instance, specifying both keyboard visibility and the reason for requesting the keyboard. The requestKeyboardReason parameter identifies the scenario that triggers the keyboard request, enabling the system to recognize input scenarios and deliver improved user experience.
Paired calls: This function must be called in pairs with OH_AttachOptions_Destroy. The object created by the create function must be destroyed via OH_AttachOptions_Destroy.
Lifecycle management: Consistent with OH_AttachOptions_Create. Multiple read operations can be performed after creation. The instance can be destroyed immediately once the attach operation completes.
Since: 15
Parameters
| Name | Description |
|---|---|
| bool showKeyboard | Input parameter indicating whether to show the keyboard upon attachment. Its meaning, functionality, usage scenarios, use effect, value range and value‑setting guideline are consistent with the showKeyboard parameter in OH_AttachOptions_Create. |
| InputMethod_RequestKeyboardReason requestKeyboardReason | Input parameter indicating the reason for requesting keyboard input. Meaning/Function: Identifies the scenario triggering the keyboard request to help the system recognize input scenarios and optimize user experience. Usage scenarios: Used when an app needs to inform the system why the keyboard is brought up. Examples include distinguishing triggers such as mouse clicks, touch events, or active API calls from the app. Use effect: The system can adjust input method behaviors according to this reason (for example, selecting an appropriate keyboard layout or input mode). Value range: Enum values of InputMethod_RequestKeyboardReason, including: - IME_REQUEST_REASON_NONE (0): No specific reason. - IME_REQUEST_REASON_MOUSE (1): Triggered by a mouse click. - IME_REQUEST_REASON_TOUCH (2): Triggered by a touch event. - IME_REQUEST_REASON_OTHER (20): Other reasons (such as active API calls initiated by the app). Value‑setting guideline: The corresponding enumerated value is selected based on the actual trigger scenario. IME_REQUEST_REASON_TOUCH applies to triggers where the user taps an input box, IME_REQUEST_REASON_MOUSE applies to mouse click triggers, and IME_REQUEST_REASON_OTHER applies to triggers initiated actively by the app's internal logic. Specification constraints: Only the above enum values are supported. Passing other values may lead to undefined behavior. |
Returns
| Type | Description |
|---|---|
| InputMethod_AttachOptions * | Pointer type. Creation successful: Returns a pointer to the newly created InputMethod_AttachOptions instance. Creation failed: Returns NULL. Possible causes include full app address space (insufficient memory). Null check: You must check whether the return value is NULL before using it. If NULL is returned, the pointer cannot be used. Memory management: Memory for the returned pointer is allocated internally by the create function. You need to release it using OH_AttachOptions_Destroy. Do not use free() or other methods to release the memory. |
void OH_AttachOptions_Destroy(InputMethod_AttachOptions *options)
Description
Destroys an InputMethod_AttachOptions instance, releasing memory resources allocated by the OH_AttachOptions_Create function. This method is used in pairs with OH_AttachOptions_Create and OH_AttachOptions_CreateWithRequestKeyboardReason.
Paired calls: This function must be called in pairs with OH_AttachOptions_Create or OH_AttachOptions_CreateWithRequestKeyboardReason. Each instance created by OH_AttachOptions_Create shall be destroyed by exactly one invocation of OH_AttachOptions_Destroy.
Lifecycle management:
Since: 12
Parameters
| Name | Description |
|---|---|
| InputMethod_AttachOptions *options | Input pointer representing the InputMethod_AttachOptions instance to be destroyed. Meaning/Function: Specifies the AttachOptions instance to destroy. OH_AttachOptions_Destroy releases memory occupied by this instance. Usage scenarios: Called when the AttachOptions is no longer required, typically after the attach operation completes. Use effect: Memory pointed to by options is released, and the pointer becomes invalid. Null pointer handling: If options is NULL, OH_AttachOptions_Destroy performs no operation (safe handling) and will not trigger a crash. However, you are advised to avoid passing NULL, as this indicates unsuccessful handling of failures from OH_AttachOptions_Create. Memory release responsibility: You are responsible for calling OH_AttachOptions_Destroy at the appropriate time to release memory. |
InputMethod_ErrorCode OH_AttachOptions_IsShowKeyboard(InputMethod_AttachOptions *options, bool *showKeyboard)
Description
Obtains the value that indicates whether to show the keyboard from InputMethod_AttachOptions.
Preconditions: options must be a valid instance created via the OH_AttachOptions_Create function, and showKeyboard must point to a valid bool variable.
Since: 12
Parameters
| Name | Description |
|---|---|
| InputMethod_AttachOptions *options | Input pointer to the InputMethod_AttachOptions instance to be read. Meaning/Function: Specifies the AttachOptions instance from which to read showKeyboard. Null pointer handling: The pointer cannot be NULL. Passing NULL returns IME_ERR_NULL_POINTER. Preconditions: It must be a valid instance created via the OH_AttachOptions_Create function. |
| bool *showKeyboard | Output pointer that obtains the value from InputMethod_AttachOptions indicating whether to display the keyboard. Meaning/Function: Obtains the value of the showKeyboard property. true indicates that the keyboard needs to be shown after attachment completes; false indicates that the keyboard does not need to be shown after attachment completes. Usage scenarios: Used for querying the keyboard display configuration of AttachOptions, such as verifying configurations before attachment or validating settings during debugging. Null pointer handling: This parameter cannot be NULL. Passing NULL returns IME_ERR_NULL_POINTER. You need to ensure showKeyboard points to a valid bool variable. Memory allocation responsibility: Memory for the bool variable is allocated by you. IsShowKeyboard only writes the value and does not allocate memory. |
Returns
| Type | Description |
|---|---|
| InputMethod_ErrorCode | Returns a specific error code. - IME_ERR_OK: Success. *showKeyboard has been assigned the correct Boolean value. - IME_ERR_NULL_POINTER: Unexpected null pointer. options or showKeyboard is a null pointer. Ensure that both parameters are properly initialized and not NULL before you call them. Error handling suggestion: If IME_ERR_NULL_POINTER is returned, verify whether options and showKeyboard are valid pointers. If IME_ERR_OK is returned, *showKeyboard holds the correct configuration value. Refer to InputMethod_ErrorCode for detailed error code definitions. |
InputMethod_ErrorCode OH_AttachOptions_GetRequestKeyboardReason(InputMethod_AttachOptions *options, int *requestKeyboardReason)
Description
Obtains the reason for requesting the keyboard from InputMethod_AttachOptions.
Preconditions: options must be a valid instance created via OH_AttachOptions_CreateWithRequestKeyboardReason (For instances created via OH_AttachOptions_Create, the default value of requestKeyboardReason is IME_REQUEST_REASON_NONE). requestKeyboardReason must point to a valid variable of InputMethod_RequestKeyboardReason.
Since: 15
Parameters
| Name | Description |
|---|---|
| InputMethod_AttachOptions *options | Input pointer to the InputMethod_AttachOptions instance whose value is read. Meaning/Function: Specifies the AttachOptions instance from which the requestKeyboardReason attribute is read. Null pointer handling: Must not be NULL. Passing NULL returns IME_ERR_NULL_POINTER. Preconditions: Must be a valid instance created through the OH_AttachOptions_CreateWithRequestKeyboardReason function. If the instance is created through OH_AttachOptions_Create (rather than CreateWithRequestKeyboardReason), the default value of the read requestKeyboardReason is IME_REQUEST_REASON_NONE. |
| int *requestKeyboardReason | Output pointer, representing the reason for requesting keyboard input. Meaning/Function: Output parameter used to obtain the enum value of the reason that triggers the input method to be brought up. Usage scenarios: Used when querying the request keyboard reason configuration of AttachOptions. Value range: The output value is the InputMethod_RequestKeyboardReason enum: IME_REQUEST_REASON_NONE(0), IME_REQUEST_REASON_MOUSE(1), IME_REQUEST_REASON_TOUCH(2), IME_REQUEST_REASON_OTHER(20). Null pointer handling: Must not be NULL. Passing NULL returns IME_ERR_NULL_POINTER. You must ensure that requestKeyboardReason points to a valid variable. Memory allocation responsibility: You allocate the memory for the variable. GetRequestKeyboardReason only writes the value and does not allocate memory. |
Returns
| Type | Description |
|---|---|
| InputMethod_ErrorCode | Returns a specific error code. - IME_ERR_OK: Success. *requestKeyboardReason has been assigned the correct enumerated value. - IME_ERR_NULL_POINTER: Unexpected null pointer. options or requestKeyboardReason is a null pointer. Ensure that both parameters are properly initialized and not NULL before you call them. Error handling suggestion: If IME_ERR_NULL_POINTER is returned, verify whether options and requestKeyboardReason are valid pointers. If IME_ERR_OK is returned, *requestKeyboardReason holds the correct configuration value. Refer to InputMethod_ErrorCode for detailed error code definitions. |