/* * Copyright (c) 2024 Huawei Device Co., Ltd. * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /** * @addtogroup InputMethod * @{ * * @brief InputMethod模块提供C语言接口来使用输入法。"使用输入法"面向应用侧调用。 *
*
功能定位：该模块为应用侧开发者提供自绘输入框与输入法服务交互的完整C API，支持应用绑定/解绑输入法服务、向输入法发送请求 * 和通知、接收输入法的回调通知、配置输入框属性、管理光标和避让信息等核心功能。 *
*
使用场景：适用于使用NDK开发自绘输入框的应用，需要与系统输入法服务进行交互的场景。典型流程为：应用创建TextEditorProxy * （文本编辑器代理）和AttachOptions（绑定配置选项），通过Controller绑定输入法服务，绑定成功后通过InputMethodProxy（输入法代 * 理）与输入法交互，使用完毕后通过Controller解绑。 *
*
使用后效果：绑定输入法后，应用可接收输入法的文本插入、删除、光标移动等回调通知，也可主动向输入法发送光标更新、选区变 * 更、私有命令等请求。解绑后，所有交互通道关闭，相关资源释放。 *
*
生命周期管理：本模块遵循严格的创建/销毁配对原则和绑定/解绑配对原则： *
*
- 绑定/解绑配对：OH_InputMethodController_Attach必须与OH_InputMethodController_Detach配对调用，未解绑会导致输入法 * 资源泄漏。 *
- 创建/销毁配对：所有Create函数创建的对象必须通过对应的Destroy函数销毁，否则会导致内存泄漏。 *
- 调用顺序：先创建依赖对象（TextEditorProxy、AttachOptions），再执行Attach绑定，绑定成功后使用InputMethodProxy交 * 互，最后Detach解绑并销毁所有创建的对象。 *
*
线程安全：本模块的API非线程安全，建议在主线程调用。TextEditorProxy的回调执行线程可通过 * OH_TextEditorProxy_SetCallbackInMainThread配置。 * *
模块架构: 本模块由9个头文件组成，按职责分为四层： *
*
- 控制层：inputmethod_controller_capi.h —— 模块核心入口，提供绑定/解绑输入法服务的能力，是所有交互的起点和终点。 *
- 交互层：inputmethod_text_editor_proxy_capi.h和inputmethod_inputmethod_proxy_capi.h —— 双向交互通道。 * TextEditorProxy是输入法→应用方向的回调注册通道，应用通过它接收输入法的文本插入、删除等通知；InputMethodProxy是应用→输入法方向 * 的请求发送通道，应用通过它向输入法发送光标更新、选区变更等通知。 *
- 配置层：inputmethod_attach_options_capi.h、inputmethod_text_config_capi.h、inputmethod_cursor_info_capi.h、 * inputmethod_text_avoid_info_capi.h —— 各类配置和信息的承载对象，分别管理绑定选项、输入框配置、光标位置信息、避让区域信息。 *
- 数据层：inputmethod_private_command_capi.h和inputmethod_types_capi.h —— 私有命令数据和公共类型定义（枚举、错误 * 码等）。 *
*
典型调用流程： *
1. 通过inputmethod_text_editor_proxy_capi.h创建TextEditorProxy并注册回调。 *
2. 通过inputmethod_attach_options_capi.h创建AttachOptions配置绑定选项。 *
3. 通过inputmethod_controller_capi.h调用Attach绑定输入法，获取InputMethodProxy。 *
4. 通过inputmethod_inputmethod_proxy_capi.h使用InputMethodProxy与输入法交互。 *
5. 通过inputmethod_text_config_capi.h、inputmethod_cursor_info_capi.h等管理配置信息。 *
6. 通过inputmethod_controller_capi.h调用Detach解绑。 *
7. 销毁所有创建的对象。 * * @library libohinputmethod.so * @kit IMEKit * @syscap SystemCapability.MiscServices.InputMethodFramework * @since 12 */ /** * @file inputmethod_attach_options_capi.h * * @brief 输入法绑定选项的头文件，提供AttachOptions实例的创建、销毁与属性读写方法。AttachOptions用于配置绑定输入法时的行为参数， * 如是否显示键盘（showKeyboard）和请求键盘的原因（requestKeyboardReason），是调用Attach时的必要参数。Create/Destroy必须配对。 *
*
功能：创建和管理InputMethod_AttachOptions实例，支持配置绑定时是否显示键盘（showKeyboard）以及触发输入法拉起的场景原 * 因（requestKeyboardReason）。AttachOptions是调用OH_InputMethodController_Attach时的必要参数，用于控制绑定输入法服务时的初 * 始行为。 *
*
使用场景：在应用绑定输入法服务前，创建AttachOptions配置绑定行为： *
- showKeyboard=true时，绑定时自动拉起键盘，适用于输入框获得焦点后需要立即输入的场景。 *
- showKeyboard=false时，绑定时不拉起键盘，适用于需要先建立交互通道但暂不输入的场景（如搜索框先绑定输入法，等用户点击 * 后再拉起键盘）。 *
- requestKeyboardReason用于标识触发输入法拉起的原因（如鼠标点击、触摸事件等），帮助系统识别输入场景以提供更好的用户体 * 验。 *
*
使用后效果：创建AttachOptions后，将其传入Attach函数，Attach函数将读取其中的配置来决定绑定行为。Attach完成后， * AttachOptions可销毁，因为配置信息已被读取。 * * @include * @library libohinputmethod.so * @kit IMEKit * @syscap SystemCapability.MiscServices.InputMethodFramework * @since 12 * @version 1.0 */ #ifndef OHOS_INPUTMETHOD_ATTACH_OPTIONS_CAPI_H #define OHOS_INPUTMETHOD_ATTACH_OPTIONS_CAPI_H #include #include "inputmethod_types_capi.h" #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ /** * @brief 输入法绑定选项，用于在绑定输入法时携带相关配置。这是一个不透明类型（opaque type），调用者不可直接访问其成员变量，只能通 * 过本头文件提供的函数操作。 *
*
用途：作为OH_InputMethodController_Attach和OH_InputMethodController_AttachWithUIContext的必要参数，用于配置绑定 * 输入法时的行为选项，包括： *
- 是否在绑定时自动显示键盘（showKeyboard）：控制绑定完成后键盘是否立即弹出。 *
- 请求键盘的原因（requestKeyboardReason）：标识触发输入法拉起的场景原因（如触摸点击、鼠标点击或应用主动调用），帮助系 * 统优化输入体验。 *
*
使用场景： *
- showKeyboard=true：适用于输入框获得焦点后需要立即输入的场景（如文本编辑框），绑定后键盘自动弹出。 *
- showKeyboard=false：适用于先建立交互通道但暂不需要键盘的场景（如搜索框），绑定后键盘不弹出，后续通过ShowKeyboard主 * 动拉起。 *
- requestKeyboardReason：适用于需要向系统说明触发输入法的场景原因，帮助系统选择合适的输入策略。 *
*
相关函数：
* | 函数 | 说明 | * | -- | -- | * | [OH_AttachOptions_Create](capi-inputmethod-attach-options-capi-h.md#oh_attachoptions_create) | 创建 * AttachOptions实例。 | * | [OH_AttachOptions_CreateWithRequestKeyboardReason](capi-inputmethod-attach-options-capi-h. * md#oh_attachoptions_createwithrequestkeyboardreason) | 创建AttachOptions实例并指定requestKeyboardReason。 | * | [OH_AttachOptions_Destroy](capi-inputmethod-attach-options-capi-h.md#oh_attachoptions_destroy) | 销毁 * AttachOptions实例。 | * | [OH_AttachOptions_IsShowKeyboard](capi-inputmethod-attach-options-capi-h. * md#oh_attachoptions_isshowkeyboard) | 获取showKeyboard值。 | * | [OH_AttachOptions_GetRequestKeyboardReason](capi-inputmethod-attach-options-capi-h. * md#oh_attachoptions_getrequestkeyboardreason) | 获取requestKeyboardReason值。 | *
*
与其他结构体的关系： *
- InputMethod_AttachOptions是OH_InputMethodController_Attach和OH_InputMethodController_AttachWithUIContext的 * 必要参数之一。Attach函数同时需要InputMethod_TextEditorProxy和InputMethod_AttachOptions两个参数。 *
- InputMethod_AttachOptions中的requestKeyboardReason使用InputMethod_RequestKeyboardReason枚举类型，该枚举定义在 * [inputmethod_types_capi.h](capi-inputmethod-types-capi-h.md)中。 *
- OH_InputMethodProxy_ShowTextInput函数也接受InputMethod_AttachOptions作为参数，用于在已绑定的状态下重新请求显示 * 键盘并指定请求原因。 * * @since 12 */ typedef struct InputMethod_AttachOptions InputMethod_AttachOptions; /** * @brief 创建一个{@link InputMethod_AttachOptions}实例，适用于仅需控制键盘显示状态的简单场景。 * 如需同时指定触发输入法拉起的场景原因，建议使用[OH_AttachOptions_CreateWithRequestKeyboardReason] * (#oh_attachoptions_createwithrequestkeyboardreason)。 *
*
配对调用：必须与[OH_AttachOptions_Destroy](#oh_attachoptions_destroy)配对调用，OH_AttachOptions_Create创建的对象 * 必须通过OH_AttachOptions_Destroy销毁，否则会导致内存泄漏。 *
*
生命周期管理： *
- 创建后可多次读取（IsShowKeyboard）。 *
- 将options传入Attach函数后，Attach函数将读取配置信息。Attach完成后options可立即销毁，因为配置已被读取。 *
- 不可将已销毁的options再次使用。 * * @param showKeyboard 输入参数，表示绑定时是否显示键盘。 *
**含义/功能：** 控制Attach绑定输入法时是否自动拉起键盘面板。 *
**使用场景：** true适用于输入框获得焦点后需要立即输入的场景（如文本编辑框）；false适用于先建立交互通道但暂不需要键盘的 * 场景（如搜索框，等用户主动点击后再拉起键盘）。 *
**使用后效果：** showKeyboard=true时，绑定成功后键盘将自动弹出；showKeyboard=false时，绑定成功后键盘不弹出， * 需后续通过OH_InputMethodProxy_ShowKeyboard主动拉起。 *
**取值范围：** true或false。 *
**默认值：** 无默认值，调用者必须显式指定。 *
**取值原则：** 根据业务场景决定。需要立即输入的场景设为true；需要延迟拉起键盘的场景设为false，后续通过ShowKeyboard主 * 动拉起。 * @return 返回指针类型。 *
**创建成功：** 返回一个指向新创建的InputMethod_AttachOptions实例的指针，该指针有效且可用于后续操作。 *
**创建失败：** 返回NULL，可能的失败原因包括应用地址空间满（内存不足）。 *
**NULL判断：** 调用者必须在使用返回值前检查是否为NULL，若为NULL则不可使用该指针，应排查内存状况或稍后重试。 *
**内存管理：** 返回的指针由Create函数内部分配内存，调用者需通过OH_AttachOptions_Destroy释放，不可使用free()或其他方 * 式释放。 * @since 12 */ InputMethod_AttachOptions *OH_AttachOptions_Create(bool showKeyboard); /** * @brief 创建一个{@link InputMethod_AttachOptions}实例，同时指定键盘显示状态和请求键盘的原因。 * requestKeyboardReason参数用于标识触发输入法拉起的场景原因，帮助系统识别输入场景以提供更好的用户体验。 *
*
配对调用：必须与[OH_AttachOptions_Destroy](#oh_attachoptions_destroy)配对调用，Create创建的对象必须通过 * OH_AttachOptions_Destroy销毁。 *
*
生命周期管理：与OH_AttachOptions_Create一致。创建后可多次读取，Attach完成后可立即销毁。 * * @param showKeyboard 输入参数，表示绑定时是否显示键盘。含义/功能、使用场景、使用后效果、取值范围、取值原则与 * OH_AttachOptions_Create中的showKeyboard参数一致。 * @param requestKeyboardReason 输入参数，表示请求键盘输入的原因。 *
**含义/功能：** 标识触发输入法拉起的场景原因，用于帮助系统识别输入场景并优化用户体验。 *
**使用场景：** 当应用需要告知系统为何拉起键盘时使用，例如区分用户通过鼠标点击、触摸事件还是应用主动调用API触发输入法。 *
**使用后效果：** 系统可根据此原因调整输入法行为（如选择合适的键盘布局或输入模式）。 *
**取值范围：** {@link InputMethod_RequestKeyboardReason}枚举值，包括： *
- IME_REQUEST_REASON_NONE (0)：无特定原因。 *
- IME_REQUEST_REASON_MOUSE (1)：通过鼠标点击触发。 *
- IME_REQUEST_REASON_TOUCH (2)：通过触摸事件触发。 *
- IME_REQUEST_REASON_OTHER (20)：其他原因（应用主动调用API等）。 *
**取值原则：** 根据实际触发场景选择对应的枚举值。用户通过触摸输入框触发时使用IME_REQUEST_REASON_TOUCH；通过鼠标点击 * 触发时使用IME_REQUEST_REASON_MOUSE； * 应用内部逻辑主动触发时使用IME_REQUEST_REASON_OTHER。 *
**规格限制：** 仅支持上述枚举值，传入其他值可能导致未定义行为。 * @return 返回指针类型。 *
**创建成功：** 返回一个指向新创建的InputMethod_AttachOptions实例的指针。 *
**创建失败：** 返回NULL，可能的失败原因有应用地址空间满（内存不足）。 *
**NULL判断：** 调用者必须在使用返回值前检查是否为NULL，若为NULL则不可使用该指针。 *
**内存管理：** 返回的指针由Create函数内部分配内存，调用者需通过OH_AttachOptions_Destroy释放，不可使用free()或其他方 * 式释放。 * @since 15 */ InputMethod_AttachOptions *OH_AttachOptions_CreateWithRequestKeyboardReason( bool showKeyboard, InputMethod_RequestKeyboardReason requestKeyboardReason); /** * @brief 销毁一个{@link InputMethod_AttachOptions}实例，释放由OH_AttachOptions_Create函数分配的内存资源。 * 该方法与OH_AttachOptions_Create和OH_AttachOptions_CreateWithRequestKeyboardReason配对使用。 *
*
配对调用：必须与OH_AttachOptions_Create或OH_AttachOptions_CreateWithRequestKeyboardReason配对调用。每个 * OH_AttachOptions_Create创建的实例必须且只能调用一次OH_AttachOptions_Destroy。 *
*
生命周期管理： *
- OH_AttachOptions_Destroy后，options指针不再有效，不可继续使用。 *
- 不可对同一个options指针调用两次OH_AttachOptions_Destroy，否则会导致重复释放（double-free）。 *
- 建议在Attach成功后立即调用OH_AttachOptions_Destroy，因为Attach已读取完配置信息。 * * @param options 输入指针，表示即将被销毁的InputMethod_AttachOptions实例。 *
**含义/功能：** 指定要销毁的AttachOptions实例，OH_AttachOptions_Destroy将释放该实例占用的内存资源。 *
**使用场景：** 在AttachOptions不再需要时调用，典型时机为Attach绑定完成后。 *
**使用后效果：** options指向的内存被释放，该指针不再有效。 *
**NULL指针处理：** 若options为NULL，OH_AttachOptions_Destroy函数不做任何操作（安全处理），不会导致崩溃。但建议调用 * 者避免传入NULL， * 因为这意味着OH_AttachOptions_Create失败未被正确处理。 *
**内存释放责任：** 由调用者负责在适当时机调用OH_AttachOptions_Destroy释放内存。 * @since 12 */ void OH_AttachOptions_Destroy(InputMethod_AttachOptions *options); /** * @brief 从{@link InputMethod_AttachOptions}中获取是否显示键盘的值。 *
*
前置条件：options必须是通过OH_AttachOptions_Create函数创建的有效实例，showKeyboard必须指向有效的bool变量。 * * @param options 输入指针，表示被读取值的InputMethod_AttachOptions实例。 *
**含义/功能：** 指定要从哪个AttachOptions实例中读取showKeyboard属性。 *
**NULL指针处理：** 不可为NULL，传入NULL将返回IME_ERR_NULL_POINTER。 *
**前提条件：** 必须通过OH_AttachOptions_Create函数创建的有效实例。 * @param showKeyboard 输出指针，表示从InputMethod_AttachOptions中获取的是否显示键盘的值。 *
**含义/功能：** 用于接收showKeyboard属性的值。true表示绑定完成时需要显示键盘；false表示绑定完成时不需要显示键盘。 *
**使用场景：** 需要查询AttachOptions的键盘显示配置时使用，如Attach前确认配置、调试时验证配置等。 *
**NULL指针处理：** 不可为NULL，传入NULL将返回IME_ERR_NULL_POINTER。调用者需确保showKeyboard指向有效的bool变量。 *
**内存分配责任：** 由调用者分配bool变量的内存，IsShowKeyboard仅写入值，不分配内存。 * @return 返回一个特定的错误码。 *
{@link IME_ERR_OK} - 表示成功。*showKeyboard已被赋值为正确的布尔值。 *
{@link IME_ERR_NULL_POINTER} - 非预期的空指针。表示options或showKeyboard为空指针，调用前需确保这两个参数已正确初始 * 化且不为NULL。 *
**错误处理建议：** 若返回IME_ERR_NULL_POINTER，检查options和showKeyboard是否为有效指针； * 若返回IME_ERR_OK，*showKeyboard即为正确的配置值。 * 具体错误码可以参考{@link InputMethod_ErrorCode}。 * @since 12 */ InputMethod_ErrorCode OH_AttachOptions_IsShowKeyboard(InputMethod_AttachOptions *options, bool *showKeyboard); /** * @brief 从{@link InputMethod_AttachOptions}中获取请求键盘输入的原因。 *
*
前置条件：options必须是通过OH_AttachOptions_CreateWithRequestKeyboardReason创建的实例 * （通过OH_AttachOptions_Create创建的实例的requestKeyboardReason默认值为IME_REQUEST_REASON_NONE）。 * requestKeyboardReason必须指向有效的InputMethod_RequestKeyboardReason变量。 * * @param options 输入指针，表示被读取值的InputMethod_AttachOptions实例。 *
**含义/功能：** 指定要从哪个AttachOptions实例中读取requestKeyboardReason属性。 *
**NULL指针处理：** 不可为NULL，传入NULL将返回IME_ERR_NULL_POINTER。 *
**前提条件：** 必须通过OH_AttachOptions_Create函数创建的有效实例。若实例通过OH_AttachOptions_Create * （而非CreateWithRequestKeyboardReason）创建，读取的requestKeyboardReason默认值为IME_REQUEST_REASON_NONE。 * @param requestKeyboardReason 输出指针，表示请求键盘输入的原因。 *
**含义/功能：** 输出参数，用于获取触发输入法拉起的场景原因枚举值。 *
**使用场景：** 需要查询AttachOptions的请求键盘原因配置时使用。 *
**取值范围：** 输出值为{@link InputMethod_RequestKeyboardReason}枚举：IME_REQUEST_REASON_NONE(0)、 * IME_REQUEST_REASON_MOUSE(1)、IME_REQUEST_REASON_TOUCH(2)、IME_REQUEST_REASON_OTHER(20)。 *
**NULL指针处理：** 不可为NULL，传入NULL将返回IME_ERR_NULL_POINTER。调用者需确保requestKeyboardReason指向有效的变 * 量。 *
**内存分配责任：** 由调用者分配变量的内存，GetRequestKeyboardReason仅写入值，不分配内存。 * @return 返回一个特定的错误码。 *
{@link IME_ERR_OK} - 表示成功。*requestKeyboardReason已被赋值为正确的枚举值。 *
{@link IME_ERR_NULL_POINTER} - 非预期的空指针。表示options或requestKeyboardReason为空指针，调用前需确保这两个参数 * 已正确初始化且不为NULL。 *
**错误处理建议：** 若返回IME_ERR_NULL_POINTER，检查options和requestKeyboardReason是否为有效指针；若返IME_ERR_OK， * *requestKeyboardReason即为正确的配置值。具体错误码可以参考{@link InputMethod_ErrorCode}。 * * @since 15 */ InputMethod_ErrorCode OH_AttachOptions_GetRequestKeyboardReason( InputMethod_AttachOptions *options, int *requestKeyboardReason); #ifdef __cplusplus } #endif /* __cplusplus */ /** @} */ #endif // OHOS_INPUTMETHOD_ATTACH_OPTIONS_CAPI_H