1 /* 2 * Copyright (c) 2024 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 /** 16 * @addtogroup InputMethod 17 * @{ 18 * 19 * @brief InputMethod provides functions to use input methods and develop input methods. 20 * 21 * @since 12 22 */ 23 24 /** 25 * @file inputmethod_text_config_capi.h 26 * 27 * @brief Provides functions to manage the text configuration. 28 * 29 * @library libohinputmethod.so 30 * @kit IMEKit 31 * @syscap SystemCapability.MiscServices.InputMethodFramework 32 * @since 12 33 * @version 1.0 34 */ 35 #ifndef OHOS_INPUTMETHOD_TEXT_CONFIG_CAPI_H 36 #define OHOS_INPUTMETHOD_TEXT_CONFIG_CAPI_H 37 #include <stdint.h> 38 #include <stddef.h> 39 40 #include "inputmethod_cursor_info_capi.h" 41 #include "inputmethod_text_avoid_info_capi.h" 42 #include "inputmethod_types_capi.h" 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif /* __cplusplus */ 47 /** 48 * @brief Define the InputMethod_TextConfig structure type. 49 * 50 * The configuration of the text editor. 51 * 52 * @since 12 53 */ 54 typedef struct InputMethod_TextConfig InputMethod_TextConfig; 55 56 /** 57 * @brief Create a new {@link InputMethod_TextConfig} instance. 58 * 59 * @return If the creation succeeds, a pointer to the newly created {@link InputMethod_TextConfig} 60 * instance is returned. If the creation fails, NULL is returned, possible cause is insufficient memory. 61 * @since 12 62 */ 63 InputMethod_TextConfig *OH_TextConfig_Create(void); 64 /** 65 * @brief Destroy a {@link InputMethod_TextConfig} instance. 66 * 67 * @param config Represents a pointer to an {@link InputMethod_TextConfig} instance which will be destroyed. 68 * @since 12 69 */ 70 void OH_TextConfig_Destroy(InputMethod_TextConfig *config); 71 72 /** 73 * @brief Set input type into TextConfig. 74 * 75 * @param config Represents a pointer to an {@link InputMethod_TextConfig} instance which will be set. 76 * @param inputType The text input type of text Editor, which is defined in {@link InputMethod_TextInputType}. 77 * @return Returns a specific error code. 78 * {@link IME_ERR_OK} - success. 79 * {@link IME_ERR_NULL_POINTER} - unexpected null pointer. 80 * Specific error codes can be referenced {@link InputMethod_ErrorCode}. 81 * @since 12 82 */ 83 InputMethod_ErrorCode OH_TextConfig_SetInputType(InputMethod_TextConfig *config, InputMethod_TextInputType inputType); 84 /** 85 * @brief Set enter key type into TextConfig. 86 * 87 * @param config Represents a pointer to an {@link InputMethod_TextConfig} instance which will be set. 88 * @param enterKeyType The enter key type of text Editor, which is defined in {@link InputMethod_EnterKeyType}. 89 * @return Returns a specific error code. 90 * {@link IME_ERR_OK} - success. 91 * {@link IME_ERR_NULL_POINTER} - unexpected null pointer. 92 * Specific error codes can be referenced {@link InputMethod_ErrorCode}. 93 * @since 12 94 */ 95 InputMethod_ErrorCode OH_TextConfig_SetEnterKeyType( 96 InputMethod_TextConfig *config, InputMethod_EnterKeyType enterKeyType); 97 /** 98 * @brief Set preview text support into TextConfig. 99 * 100 * @param config Represents a pointer to an {@link InputMethod_TextConfig} instance which will be set. 101 * @param supported Indicates whether the preview text is supported. 102 * @return Returns a specific error code. 103 * {@link IME_ERR_OK} - success. 104 * {@link IME_ERR_NULL_POINTER} - unexpected null pointer. 105 * Specific error codes can be referenced {@link InputMethod_ErrorCode}. 106 * @since 12 107 */ 108 InputMethod_ErrorCode OH_TextConfig_SetPreviewTextSupport(InputMethod_TextConfig *config, bool supported); 109 /** 110 * @brief Set selection into TextConfig. 111 * 112 * @param config Represents a pointer to an {@link InputMethod_TextConfig} instance which will be set. 113 * @param start The start position of selection. 114 * @param end The end position of selection. 115 * @return Returns a specific error code. 116 * {@link IME_ERR_OK} - success. 117 * {@link IME_ERR_NULL_POINTER} - unexpected null pointer. 118 * Specific error codes can be referenced {@link InputMethod_ErrorCode}. 119 * @since 12 120 */ 121 InputMethod_ErrorCode OH_TextConfig_SetSelection(InputMethod_TextConfig *config, int32_t start, int32_t end); 122 /** 123 * @brief Set window id into TextConfig. 124 * 125 * @param config Represents a pointer to an {@link InputMethod_TextConfig} instance which will be set. 126 * @param windowId The window ID of the application currently bound to the input method. 127 * @return Returns a specific error code. 128 * {@link IME_ERR_OK} - success. 129 * {@link IME_ERR_NULL_POINTER} - unexpected null pointer. 130 * Specific error codes can be referenced {@link InputMethod_ErrorCode}. 131 * @since 12 132 */ 133 InputMethod_ErrorCode OH_TextConfig_SetWindowId(InputMethod_TextConfig *config, int32_t windowId); 134 135 /** 136 * @brief Sets the placeholder text of an InputMethod_TextConfig instance. 137 * 138 * @param config Pointer to the InputMethod_TextConfig instance. 139 * @param placeholder Pointer to a UTF-16 encoded double-byte string. If a null pointer is passed, the placeholder text 140 * is an empty string. 141 * @param length Number of elements in the memory to which <b>placeholder</b> points, including the null character of 142 * the double-byte string. 143 * 1) If <b>length</b> is <b>0</b>, the placeholder text is an empty string. 144 * 2) The maximum number of UTF-16 encoded characters is 256, and the last element must be a null character. 145 * 3) If the <b>length</b> exceeds 256, the placeholder text will be truncated. 146 * @return Returns a specific error code. 147 * {@link IME_ERR_OK} - success. 148 * {@link IME_ERR_NULL_POINTER} - unexpected null pointer. 149 * Specific error codes can be referenced {@link InputMethod_ErrorCode}. 150 * @since 20 151 */ 152 InputMethod_ErrorCode OH_TextConfig_SetPlaceholder(InputMethod_TextConfig *config, const char16_t *placeholder, 153 size_t length); 154 155 /** 156 * @brief Sets the ability name of an InputMethod_TextConfig instance. 157 * 158 * @param config Pointer to the InputMethod_TextConfig instance. 159 * @param abilityName Pointer to a UTF-16 encoded double-byte string. If a null pointer is passed, the ability name is 160 * an empty string. 161 * @param length Number of elements in the memory to which <b>abilityName</b> points, including the null character of 162 * the double-byte string. 163 * 1) If <b>length</b> is <b>0</b>, the ability name is an empty string. 164 * 2) The maximum number of UTF-16 encoded characters is 128, and the last element must be a null character. 165 * 3) If the <b>length</b> exceeds 128, the placeholder text will be truncated. 166 * @return Returns a specific error code. 167 * {@link IME_ERR_OK} - success. 168 * {@link IME_ERR_NULL_POINTER} - unexpected null pointer. 169 * Specific error codes can be referenced {@link InputMethod_ErrorCode}. 170 * @since 20 171 */ 172 InputMethod_ErrorCode OH_TextConfig_SetAbilityName(InputMethod_TextConfig *config, const char16_t *abilityName, 173 size_t length); 174 175 /** 176 * @brief Get input type from TextConfig 177 * 178 * @param config Represents a pointer to an {@link InputMethod_TextConfig} instance which will be get from. 179 * @param inputType Represents a pointer to an {@link InputMethod_TextInputType} instance. 180 * The text input type of text Editor 181 * @return Returns a specific error code. 182 * {@link IME_ERR_OK} - success. 183 * {@link IME_ERR_NULL_POINTER} - unexpected null pointer. 184 * Specific error codes can be referenced {@link InputMethod_ErrorCode}. 185 * @since 12 186 */ 187 InputMethod_ErrorCode OH_TextConfig_GetInputType(InputMethod_TextConfig *config, InputMethod_TextInputType *inputType); 188 /** 189 * @brief Get enter key type from TextConfig 190 * 191 * @param config Represents a pointer to an {@link InputMethod_TextConfig} instance which will be get from. 192 * @param enterKeyType Represents a pointer to an {@link InputMethod_EnterKeyType} instance. 193 * Indicates the enter key type of text Editor 194 * @return Returns a specific error code. 195 * {@link IME_ERR_OK} - success. 196 * {@link IME_ERR_NULL_POINTER} - unexpected null pointer. 197 * Specific error codes can be referenced {@link InputMethod_ErrorCode}. 198 * @since 12 199 */ 200 InputMethod_ErrorCode OH_TextConfig_GetEnterKeyType( 201 InputMethod_TextConfig *config, InputMethod_EnterKeyType *enterKeyType); 202 /** 203 * @brief Get is preview text supported from TextConfig. 204 * 205 * @param config Represents a pointer to an {@link InputMethod_TextConfig} instance which will be get from. 206 * @param supported Indicates whether the preview text is supported. 207 * @return Returns a specific error code. 208 * {@link IME_ERR_OK} - success. 209 * {@link IME_ERR_NULL_POINTER} - unexpected null pointer. 210 * Specific error codes can be referenced {@link InputMethod_ErrorCode}. 211 * @since 12 212 */ 213 InputMethod_ErrorCode OH_TextConfig_IsPreviewTextSupported(InputMethod_TextConfig *config, bool *supported); 214 /** 215 * @brief Get cursor info from TextConfig. 216 * 217 * @param config Represents a pointer to an {@link InputMethod_TextConfig} instance which will be get from. 218 * @param cursorInfo Represents a pointer to an {@link InputMethod_CursorInfo} instance. 219 * @return Returns a specific error code. 220 * {@link IME_ERR_OK} - success. 221 * {@link IME_ERR_NULL_POINTER} - unexpected null pointer. 222 * Specific error codes can be referenced {@link InputMethod_ErrorCode}. 223 * @since 12 224 */ 225 InputMethod_ErrorCode OH_TextConfig_GetCursorInfo(InputMethod_TextConfig *config, InputMethod_CursorInfo **cursorInfo); 226 227 /** 228 * @brief Get text avoid information from text configuration. 229 * 230 * @param config Indicates the text configuration. 231 * @param avoidInfo Indicates the text avoid information. 232 * @return Returns a specific error code. 233 * {@link IME_ERR_OK} - success. 234 * {@link IME_ERR_NULL_POINTER} - unexpected null pointer. 235 * Specific error codes can be referenced {@link InputMethod_ErrorCode}. 236 *@since 12 237 */ 238 InputMethod_ErrorCode OH_TextConfig_GetTextAvoidInfo( 239 InputMethod_TextConfig *config, InputMethod_TextAvoidInfo **avoidInfo); 240 241 /** 242 * @brief Get selection from TextConfig. 243 * 244 * @param config Represents a pointer to an {@link InputMethod_TextConfig} instance which will be get from. 245 * @param start Represents selection start position. 246 * @param end Represents selection end position. 247 * @return Returns a specific error code. 248 * {@link IME_ERR_OK} - success. 249 * {@link IME_ERR_NULL_POINTER} - unexpected null pointer. 250 * Specific error codes can be referenced {@link InputMethod_ErrorCode}. 251 * @since 12 252 */ 253 InputMethod_ErrorCode OH_TextConfig_GetSelection(InputMethod_TextConfig *config, int32_t *start, int32_t *end); 254 /** 255 * @brief Get window id from TextConfig. 256 * 257 * @param config Represents a pointer to an {@link InputMethod_TextConfig} instance which will be get from. 258 * @param windowId The window ID of the application currently bound to the input method. 259 * @return Returns a specific error code. 260 * {@link IME_ERR_OK} - success. 261 * {@link IME_ERR_NULL_POINTER} - unexpected null pointer. 262 * Specific error codes can be referenced {@link InputMethod_ErrorCode}. 263 * @since 12 264 */ 265 InputMethod_ErrorCode OH_TextConfig_GetWindowId(InputMethod_TextConfig *config, int32_t *windowId); 266 267 /** 268 * @brief Obtains the placeholder text of an InputMethod_TextConfig instance. 269 * 270 * @param config Pointer to the InputMethod_TextConfig instance. 271 * @param placeholder Pointer to the placeholder text. The memory of this pointer is maintained by the caller. 272 * @param length Pointer to the length of the placeholder text, in double bytes. The length includes the null character 273 * of the string. 274 * 1) As an input parameter, <b>length</b> indicates the available length of the memory to which <b>placeholder</b> 275 * points. As an output parameter, it indicates the actual length of the placeholder text. 276 * 2) If <b>placeholder</b> is a null pointer and <b>length</b> points to valid memory, <b>length</b> will be set to 277 * the actual length of the placeholder text, and an error will be return. 278 * 3) If both <b>placeholder</b> and <b>length</b> point to valid memory, but the value of <b>length</b> is less 279 * than the actual length of the placeholder text, <b>length</b> will be set to the actual length of the 280 * placeholder text, and an error will be return. 281 * @return Returns a specific error code. 282 * {@link IME_ERR_OK} - success. 283 * {@link IME_ERR_PARAMCHECK} - parameter check failed. 284 * {@link IME_ERR_NULL_POINTER} - unexpected null pointer. 285 * Specific error codes can be referenced {@link InputMethod_ErrorCode}. 286 * @since 20 287 */ 288 InputMethod_ErrorCode OH_TextConfig_GetPlaceholder(InputMethod_TextConfig *config, char16_t *placeholder, 289 size_t *length); 290 291 /** 292 * @brief Obtains the ability name of an InputMethod_TextConfig instance. 293 * 294 * @param config Pointer to the InputMethod_TextConfig instance. 295 * @param abilityName Pointer to the ability name. The memory of this pointer is maintained by the caller. 296 * @param length Pointer to the length of the ability name, in double bytes. The length includes the null character of 297 * the string. 298 * 1) As an input parameter, <b>length</b> indicates the available length of the memory to which <b>abilityName</b> 299 * points. As an output parameter, it indicates the actual length of the ability name. 300 * 2) If <b>abilityName</b> is a null pointer and <b>length</b> points to valid memory, <b>length</b> will be set to 301 * the actual length of the ability name, and an error will be return. 302 * 3) If both <b>abilityName</b> and <b>length</b> point to valid memory, but the value of <b>length</b> is less 303 * than the actual length of the ability name, <b>length</b> will be set to the actual length of the ability 304 * name, and an error will be return. 305 * @return Returns a specific error code. 306 * {@link IME_ERR_OK} - success. 307 * {@link IME_ERR_PARAMCHECK} - parameter check failed. 308 * {@link IME_ERR_NULL_POINTER} - unexpected null pointer. 309 * Specific error codes can be referenced {@link InputMethod_ErrorCode}. 310 * @since 20 311 */ 312 InputMethod_ErrorCode OH_TextConfig_GetAbilityName(InputMethod_TextConfig *config, char16_t *abilityName, 313 size_t *length); 314 #ifdef __cplusplus 315 } 316 #endif /* __cplusplus */ 317 /** @} */ 318 #endif // OHOS_INPUTMETHOD_TEXT_CONFIG_CAPI_H