inputmethod/include/inputmethod_internal.h

   1 /*
   2  * Copyright (c) 2014-2017 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the License);
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __TIZEN_UIX_INPUTMETHOD_INTERNAL_H__
  18 #define __TIZEN_UIX_INPUTMETHOD_INTERNAL_H__
  19
  20 /**
  21  * @file inputmethod_internal.h
  22  * @brief This file contains input method internal APIs and related enumeration.
  23  */
  24
  25 #include <tizen.h>
  26 #include <Eina.h>
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 /**
  33  * @brief Enumeration for input method optimization hint.
  34  *
  35  * @since_tizen 5.0
  36  */
  37 typedef enum {
  38         IME_OPTIMIZATION_HINT_NONE = 0, /**< No hint provided */
  39         IME_OPTIMIZATION_HINT_SHOW_PREPARE, /**< This IME is going to be displayed on screen soon */
  40 } ime_optimization_hint_e;
  41
  42 typedef struct _ime_context *ime_context_h;
  43
  44 /**
  45  * @brief Called when an caps mode is changed.
  46  *
  47  * @since_tizen 3.0
  48  *
  49  * @privilege %http://tizen.org/privilege/ime
  50  *
  51  * @param[in] mode caps mode
  52  * @param[in] user_data User data to be passed from the callback registration function
  53  */
  54 typedef void (*ime_caps_mode_changed_cb)(int mode, void *user_data);
  55
  56 /**
  57  * @brief Called when a candidate list provided by IMEngine should be shown.
  58  *
  59  * @since_tizen 3.0
  60  *
  61  * @privilege %http://tizen.org/privilege/ime
  62  *
  63  * @param[in] context_id The input context identification value of an associated text input UI control
  64  * @param[in] user_data User data to be passed from the callback registration function
  65  */
  66 typedef void (*ime_candidate_show_cb)(int context_id, void *user_data);
  67
  68 /**
  69  * @brief Called when a candidate list provided by IMEngine should be hidden.
  70  *
  71  * @since_tizen 3.0
  72  *
  73  * @privilege %http://tizen.org/privilege/ime
  74  *
  75  * @param[in] context_id The input context identification value of an associated text input UI control
  76  * @param[in] user_data User data to be passed from the callback registration function
  77  */
  78 typedef void (*ime_candidate_hide_cb)(int context_id, void *user_data);
  79
  80 /**
  81  * @brief Called when a candidate list provided by IMEngine is changed.
  82  *
  83  * @since_tizen 3.0
  84  *
  85  * @privilege %http://tizen.org/privilege/ime
  86  *
  87  * @remarks @a list should not be released.
  88  *
  89  * @param[in] list candidate list
  90  * @param[in] user_data User data to be passed from the callback registration function
  91  */
  92 typedef void (*ime_lookup_table_changed_cb)(Eina_List *list, void *user_data);
  93
  94 /**
  95  * @brief Called when a optimization hint value is set.
  96  *
  97  * @since_tizen 5.0
  98  *
  99  * @privilege %http://tizen.org/privilege/ime
 100  *
 101  * @param[in] hint The hint value used for optimization
 102  * @param[in] user_data User data to be passed from the callback registration function
 103  */
 104 typedef void (*ime_optimization_hint_set_cb)(ime_optimization_hint_e hint, void *user_data);
 105
 106 /**
 107  * @brief Sets @c ime_caps_mode_changed_cb() event callback function.
 108  *
 109  * @since_tizen 3.0
 110  *
 111  * @privilege %http://tizen.org/privilege/ime
 112  *
 113  * @remarks The ime_caps_mode_changed_cb() callback function is called when an associated text input
 114  * UI control sends the change of caps mode.
 115  *
 116  * @param[in] callback_func @c ime_caps_mode_changed_cb() event callback function
 117  * @param[in] user_data User data to be passed to the callback function
 118  *
 119  * @return 0 on success, otherwise a negative error value
 120  * @retval #IME_ERROR_NONE No error
 121  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 122  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
 123  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
 124  *
 125  * @post The ime_run() function should be called to start to run IME application's main loop.
 126  *
 127  * @see ime_run()
 128  */
 129 int ime_event_set_caps_mode_changed_cb(ime_caps_mode_changed_cb callback_func, void *user_data);
 130
 131 /**
 132  * @brief Sets @c ime_candidate_show_cb() event callback function.
 133  *
 134  * @since_tizen 3.0
 135  *
 136  * @privilege %http://tizen.org/privilege/ime
 137  *
 138  * @param[in] callback_func @c ime_candidate_show_cb() event callback function
 139  * @param[in] user_data User data to be passed to the callback function
 140  *
 141  * @return 0 on success, otherwise a negative error value
 142  * @retval #IME_ERROR_NONE No error
 143  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 144  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
 145  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
 146  *
 147  * @post The ime_run() function should be called to start to run IME application's main loop.
 148  *
 149  * @see ime_run()
 150  */
 151 int ime_event_set_candidate_show_cb(ime_candidate_show_cb callback_func, void *user_data);
 152
 153 int ime_event_set_candidate_hide_cb(ime_candidate_hide_cb callback_func, void *user_data);
 154
 155 /**
 156  * @brief Sets @c ime_lookup_table_changed_cb() event callback function.
 157  *
 158  * @since_tizen 3.0
 159  *
 160  * @privilege %http://tizen.org/privilege/ime
 161  *
 162  * @remarks The ime_lookup_table_changed_cb() callback function is called when an associated text input
 163  * UI control sends the change of caps mode.
 164  *
 165  * @param[in] callback_func @c ime_lookup_table_changed_cb() event callback function
 166  * @param[in] user_data User data to be passed to the callback function
 167  *
 168  * @return 0 on success, otherwise a negative error value
 169  * @retval #IME_ERROR_NONE No error
 170  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 171  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
 172  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
 173  *
 174  * @post The ime_run() function should be called to start to run IME application's main loop.
 175  *
 176  * @see ime_run()
 177  */
 178 int ime_event_set_lookup_table_changed_cb(ime_lookup_table_changed_cb callback_func, void *user_data);
 179
 180 /**
 181  * @brief Gets the caps mode information from the given input context.
 182  *
 183  * @details Each edit field has various attributes for input panel. This function can be
 184  * called to get the caps mode information in ime_show_cb() callback function.
 185  *
 186  * @since_tizen 3.0
 187  *
 188  * @privilege %http://tizen.org/privilege/ime
 189  *
 190  * @param[in] context The input context information of an associated text input UI control
 191  * @param[out] caps_mode Caps mode information \n @c true to turn on shift mode
 192  * text feature if available, @c false to disable the predictive text feature
 193  *
 194  * @return 0 on success, otherwise a negative error value
 195  * @retval #IME_ERROR_NONE No error
 196  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 197  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
 198  * @retval #IME_ERROR_NOT_RUNNING IME main loop isn't started yet
 199  *
 200  * @post Input panel UI should be drawn or operated by this information accordingly.
 201  *
 202  * @see ime_show_cb()
 203  */
 204 int ime_context_get_caps_mode(ime_context_h context, bool *caps_mode);
 205
 206 /**
 207  * @brief Sets keyboard engine.
 208  *
 209  * @since_tizen 3.0
 210  *
 211  * @privilege %http://tizen.org/privilege/ime
 212  *
 213  * @param[in] engine_id The engine UUID
 214  *
 215  * @return 0 on success, otherwise a negative error value
 216  * @retval #IME_ERROR_NONE No error
 217  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 218  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
 219  * @retval #IME_ERROR_NOT_RUNNING IME main loop isn't started yet
 220  */
 221 int ime_set_imengine(const char *engine_id);
 222
 223 /**
 224  * @brief Flushes state in Input Method engine.
 225  *
 226  * @since_tizen 3.0
 227  *
 228  * @privilege %http://tizen.org/privilege/ime
 229  *
 230  * @return 0 on success, otherwise a negative error value
 231  * @retval #IME_ERROR_NONE No error
 232  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 233  * @retval #IME_ERROR_NOT_RUNNING IME main loop isn't started yet
 234  */
 235 int ime_flush_imengine(void);
 236
 237 /**
 238  * @brief Resets state in Input Method engine.
 239  *
 240  * @since_tizen 3.0
 241  *
 242  * @privilege %http://tizen.org/privilege/ime
 243  *
 244  * @return 0 on success, otherwise a negative error value
 245  * @retval #IME_ERROR_NONE No error
 246  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 247  * @retval #IME_ERROR_NOT_RUNNING IME main loop isn't started yet
 248  */
 249 int ime_reset_imengine(void);
 250
 251 /**
 252  * @brief Send an Event to IMEngine
 253  *
 254  * @since_tizen 5.5
 255  *
 256  * @privilege %http://tizen.org/privilege/ime
 257  *
 258  * @return 0 on success, otherwise a negative error value
 259  * @param[in] command The command to be sent.
 260  * @param[in] value The value corresponding to the command.
 261  */
 262 int ime_send_imengine_event(int command, unsigned int value);
 263
 264 /**
 265  * @brief Sends the selected item index in the candidate list.
 266  *
 267  * @since_tizen 3.0
 268  *
 269  * @privilege %http://tizen.org/privilege/ime
 270  *
 271  * @param[in] index the selected index in the candidate list
 272  *
 273  * @return 0 on success, otherwise a negative error value
 274  * @retval #IME_ERROR_NONE No error
 275  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 276  * @retval #IME_ERROR_NOT_RUNNING IME main loop isn't started yet
 277  */
 278 int ime_select_candidate(unsigned int index);
 279
 280 /**
 281  * @brief Sends the input context event.
 282  *
 283  * @since_tizen 3.0
 284  *
 285  * @privilege %http://tizen.org/privilege/ime
 286  *
 287  * @param[in] type the event type
 288  * @param[in] value the event value
 289  *
 290  * @return 0 on success, otherwise a negative error value
 291  * @retval #IME_ERROR_NONE No error
 292  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 293  * @retval #IME_ERROR_NOT_RUNNING IME main loop isn't started yet
 294  */
 295 int ime_update_input_context(unsigned int type, unsigned int value);
 296
 297 /**
 298  * @brief Requests IME to initialize explicitly.
 299  *
 300  * @details When using ime_run() API, the initialize / prepare / finalize procedures
 301  * are processed automatically inside the IME application loop.
 302  * But in case of not using ime_run() API, which means the IME application has
 303  * its own main loop, these procedures need to be requested explicitly.
 304  *
 305  * @since_tizen 4.0
 306  *
 307  * @privilege %http://tizen.org/privilege/ime
 308  *
 309  * @return 0 on success, otherwise a negative error value
 310  * @retval #IME_ERROR_NONE No error
 311  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 312  */
 313 int ime_initialize(void);
 314
 315 /**
 316  * @brief Requests IME to prepare resources such as IME window and socket connection.
 317  *
 318  * @details Like ime_initialize() function, this procedure is automatically processed
 319  * when using ime_run() API. Call this function only when ime_run() is not used and
 320  * the IME application has to handle main loop by itself.
 321  *
 322  * @since_tizen 4.0
 323  *
 324  * @privilege %http://tizen.org/privilege/ime
 325  *
 326  * @return 0 on success, otherwise a negative error value
 327  * @retval #IME_ERROR_NONE No error
 328  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 329  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
 330  */
 331 int ime_prepare(void);
 332
 333 /**
 334  * @brief Requests IME to finalize explicitly.
 335  *
 336  * @since_tizen 4.0
 337  *
 338  * @privilege %http://tizen.org/privilege/ime
 339  *
 340  * @return 0 on success, otherwise a negative error value
 341  * @retval #IME_ERROR_NONE No error
 342  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 343  */
 344 int ime_finalize(void);
 345
 346 /**
 347  * @brief Sets flag whether IME is called from dotnet.
 348  *
 349  * @since_tizen 4.0
 350  *
 351  * @privilege %http://tizen.org/privilege/ime
 352  *
 353  * @param[in] set Set with Dotnet mode
 354  * @return 0 on success, otherwise a negative error value
 355  * @retval #IME_ERROR_NONE No error
 356  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 357  */
 358 int ime_set_dotnet_flag(bool set);
 359
 360 /**
 361  * @brief Sets flag whether creating IME window should be deferred until there is a access request.
 362  *
 363  * @since_tizen 5.0
 364  *
 365  * @privilege %http://tizen.org/privilege/ime
 366  *
 367  * @param[in] flag true if deferring window creation is desired
 368  * @return 0 on success, otherwise a negative error value
 369  * @retval #IME_ERROR_NONE No error
 370  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 371  */
 372 int ime_set_window_creation_defer_flag(bool flag);
 373
 374 /**
 375  * @brief Sets @c ime_optimization_hint_set_cb() event callback function.
 376  *
 377  * @since_tizen 5.0
 378  *
 379  * @privilege %http://tizen.org/privilege/ime
 380  *
 381  * @remarks The ime_optimization_hint_set_cb() callback function is called when an optimization hint is set
 382  *
 383  * @param[in] callback_func @c ime_optimization_hint_set_cb() event callback function
 384  * @param[in] user_data User data to be passed to the callback function
 385  *
 386  * @return 0 on success, otherwise a negative error value
 387  * @retval #IME_ERROR_NONE No error
 388  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 389  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
 390  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
 391  *
 392  * @post The ime_run() function should be called to start to run IME application's main loop.
 393  *
 394  * @see ime_run()
 395  */
 396 int ime_event_set_optimization_hint_set_cb(ime_optimization_hint_set_cb callback_func, void *user_data);
 397
 398 #ifdef __cplusplus
 399 }
 400 #endif
 401
 402 #endif /* __TIZEN_UIX_INPUTMETHOD_INTERNAL_H__ */
 403