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 #ifndef OHOS_INPUTMETHOD_TEXT_CONFIG_CAPI_H 16 #define OHOS_INPUTMETHOD_TEXT_CONFIG_CAPI_H 17 /** 18 * @addtogroup InputMethod 19 * @{ 20 * 21 * @brief InputMethod provides functions to use input methods and develop input methods. 22 * 23 * @since 12 24 */ 25 26 /** 27 * @file inputmethod_text_config_capi.h 28 * 29 * @brief Provides functions to manage the text configuration. 30 * 31 * @library libohinputmethod.so 32 * @kit IMEKit 33 * @syscap SystemCapability.MiscServices.InputMethodFramework 34 * @since 12 35 * @version 1.0 36 */ 37 #include <stdint.h> 38 #include <uchar.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_PARAMCHECK} - parameter check failed. 184 * {@link IME_ERR_NULL_POINTER} - unexpected null pointer. 185 * Specific error codes can be referenced {@link InputMethod_ErrorCode}. 186 * @since 12 187 */ 188 InputMethod_ErrorCode OH_TextConfig_GetInputType(InputMethod_TextConfig *config, InputMethod_TextInputType *inputType); 189 /** 190 * @brief Get enter key type from TextConfig 191 * 192 * @param config Represents a pointer to an {@link InputMethod_TextConfig} instance which will be get from. 193 * @param enterKeyType Represents a pointer to an {@link InputMethod_EnterKeyType} instance. 194 * Indicates the enter key type of text Editor 195 * @return Returns a specific error code. 196 * {@link IME_ERR_OK} - success. 197 * {@link IME_ERR_NULL_POINTER} - unexpected null pointer. 198 * Specific error codes can be referenced {@link InputMethod_ErrorCode}. 199 * @since 12 200 */ 201 InputMethod_ErrorCode OH_TextConfig_GetEnterKeyType( 202 InputMethod_TextConfig *config, InputMethod_EnterKeyType *enterKeyType); 203 /** 204 * @brief Get is preview text supported from TextConfig. 205 * 206 * @param config Represents a pointer to an {@link InputMethod_TextConfig} instance which will be get from. 207 * @param supported Indicates whether the preview text is supported. 208 * @return Returns a specific error code. 209 * {@link IME_ERR_OK} - success. 210 * {@link IME_ERR_NULL_POINTER} - unexpected null pointer. 211 * Specific error codes can be referenced {@link InputMethod_ErrorCode}. 212 * @since 12 213 */ 214 InputMethod_ErrorCode OH_TextConfig_IsPreviewTextSupported(InputMethod_TextConfig *config, bool *supported); 215 /** 216 * @brief Get cursor info from TextConfig. 217 * 218 * @param config Represents a pointer to an {@link InputMethod_TextConfig} instance which will be get from. 219 * @param cursorInfo Represents a pointer to an {@link InputMethod_CursorInfo} instance. 220 * @return Returns a specific error code. 221 * {@link IME_ERR_OK} - success. 222 * {@link IME_ERR_NULL_POINTER} - unexpected null pointer. 223 * Specific error codes can be referenced {@link InputMethod_ErrorCode}. 224 * @since 12 225 */ 226 InputMethod_ErrorCode OH_TextConfig_GetCursorInfo(InputMethod_TextConfig *config, InputMethod_CursorInfo **cursorInfo); 227 228 /** 229 * @brief Get text avoid information from text configuration. 230 * 231 * @param config Indicates the text configuration. 232 * @param avoidInfo Indicates the text avoid information. 233 * @return Returns a specific error code. 234 * {@link IME_ERR_OK} - success. 235 * {@link IME_ERR_NULL_POINTER} - unexpected null pointer. 236 * Specific error codes can be referenced {@link InputMethod_ErrorCode}. 237 *@since 12 238 */ 239 InputMethod_ErrorCode OH_TextConfig_GetTextAvoidInfo( 240 InputMethod_TextConfig *config, InputMethod_TextAvoidInfo **avoidInfo); 241 242 /** 243 * @brief Get selection from TextConfig. 244 * 245 * @param config Represents a pointer to an {@link InputMethod_TextConfig} instance which will be get from. 246 * @param start Represents selection start position. 247 * @param end Represents selection end position. 248 * @return Returns a specific error code. 249 * {@link IME_ERR_OK} - success. 250 * {@link IME_ERR_NULL_POINTER} - unexpected null pointer. 251 * Specific error codes can be referenced {@link InputMethod_ErrorCode}. 252 * @since 12 253 */ 254 InputMethod_ErrorCode OH_TextConfig_GetSelection(InputMethod_TextConfig *config, int32_t *start, int32_t *end); 255 256 /** 257 * @brief Get window id from TextConfig. 258 * 259 * @param config Represents a pointer to an {@link InputMethod_TextConfig} instance which will be get from. 260 * @param windowId The window ID of the application currently bound to the input method. 261 * @return Returns a specific error code. 262 * {@link IME_ERR_OK} - success. 263 * {@link IME_ERR_NULL_POINTER} - unexpected null pointer. 264 * Specific error codes can be referenced {@link InputMethod_ErrorCode}. 265 * @since 12 266 */ 267 InputMethod_ErrorCode OH_TextConfig_GetWindowId(InputMethod_TextConfig *config, int32_t *windowId); 268 269 /** 270 * @brief Obtains the placeholder text of an InputMethod_TextConfig instance. 271 * 272 * @param config Pointer to the InputMethod_TextConfig instance. 273 * @param placeholder Pointer to the placeholder text. The memory of this pointer is maintained by the caller. 274 * @param length Pointer to the length of the placeholder text, in double bytes. The length includes the null character 275 * of the string. 276 * 1) As an input parameter, <b>length</b> indicates the available length of the memory to which <b>placeholder</b> 277 * points. As an output parameter, it indicates the actual length of the placeholder text. 278 * 2) If <b>placeholder</b> is a null pointer and <b>length</b> points to valid memory, <b>length</b> will be set to 279 * the actual length of the placeholder text, and an error will be return. 280 * 3) If both <b>placeholder</b> and <b>length</b> point to valid memory, but the value of <b>length</b> is less 281 * than the actual length of the placeholder text, <b>length</b> will be set to the actual length of the 282 * placeholder text, and an error will be return. 283 * @return Returns a specific error code. 284 * {@link IME_ERR_OK} - success. 285 * {@link IME_ERR_PARAMCHECK} - parameter check failed. 286 * {@link IME_ERR_NULL_POINTER} - unexpected null pointer. 287 * Specific error codes can be referenced {@link InputMethod_ErrorCode}. 288 * @since 20 289 */ 290 InputMethod_ErrorCode OH_TextConfig_GetPlaceholder(InputMethod_TextConfig *config, char16_t *placeholder, 291 size_t *length); 292 293 /** 294 * @brief Obtains the ability name of an InputMethod_TextConfig instance. 295 * 296 * @param config Pointer to the InputMethod_TextConfig instance. 297 * @param abilityName Pointer to the ability name. The memory of this pointer is maintained by the caller. 298 * @param length Pointer to the length of the ability name, in double bytes. The length includes the null character of 299 * the string. 300 * 1) As an input parameter, <b>length</b> indicates the available length of the memory to which <b>abilityName</b> 301 * points. As an output parameter, it indicates the actual length of the ability name. 302 * 2) If <b>abilityName</b> is a null pointer and <b>length</b> points to valid memory, <b>length</b> will be set to 303 * the actual length of the ability name, and an error will be return. 304 * 3) If both <b>abilityName</b> and <b>length</b> point to valid memory, but the value of <b>length</b> is less 305 * than the actual length of the ability name, <b>length</b> will be set to the actual length of the ability 306 * name, and an error will be return. 307 * @return Returns a specific error code. 308 * {@link IME_ERR_OK} - success. 309 * {@link IME_ERR_PARAMCHECK} - parameter check failed. 310 * {@link IME_ERR_NULL_POINTER} - unexpected null pointer. 311 * Specific error codes can be referenced {@link InputMethod_ErrorCode}. 312 * @since 20 313 */ 314 InputMethod_ErrorCode OH_TextConfig_GetAbilityName(InputMethod_TextConfig *config, char16_t *abilityName, 315 size_t *length); 316 #ifdef __cplusplus 317 } 318 #endif /* __cplusplus */ 319 /** @} */ 320 #endif // OHOS_INPUTMETHOD_TEXT_CONFIG_CAPI_H