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 Sends the selected item index in the candidate list.
 253  *
 254  * @since_tizen 3.0
 255  *
 256  * @privilege %http://tizen.org/privilege/ime
 257  *
 258  * @param[in] index the selected index in the candidate list
 259  *
 260  * @return 0 on success, otherwise a negative error value
 261  * @retval #IME_ERROR_NONE No error
 262  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 263  * @retval #IME_ERROR_NOT_RUNNING IME main loop isn't started yet
 264  */
 265 int ime_select_candidate(unsigned int index);
 266
 267 /**
 268  * @brief Sends the input context event.
 269  *
 270  * @since_tizen 3.0
 271  *
 272  * @privilege %http://tizen.org/privilege/ime
 273  *
 274  * @param[in] type the event type
 275  * @param[in] value the event value
 276  *
 277  * @return 0 on success, otherwise a negative error value
 278  * @retval #IME_ERROR_NONE No error
 279  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 280  * @retval #IME_ERROR_NOT_RUNNING IME main loop isn't started yet
 281  */
 282 int ime_update_input_context(unsigned int type, unsigned int value);
 283
 284 /**
 285  * @brief Requests IME to initialize explicitly.
 286  *
 287  * @details When using ime_run API, the initialize / prepare / finalize procedures
 288  * are processed automatically inside the IME application loop.
 289  * But in case of not using ime_run API, which means the IME application has
 290  * its own main loop, these procedures need to be requested explicitly.
 291  *
 292  * @since_tizen 4.0
 293  *
 294  * @privilege %http://tizen.org/privilege/ime
 295  *
 296  * @return 0 on success, otherwise a negative error value
 297  * @retval #IME_ERROR_NONE No error
 298  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 299  */
 300 int ime_initialize(void);
 301
 302 /**
 303  * @brief Requests IME to prepare resources such as IME window and socket connection.
 304  *
 305  * @details Like ime_initialize() function, this procedure is automatically processed
 306  * when using ime_run() API. Call this function only when ime_run() is not used and
 307  * the IME application has to handle main loop by itself.
 308  *
 309  * @since_tizen 4.0
 310  *
 311  * @privilege %http://tizen.org/privilege/ime
 312  *
 313  * @return 0 on success, otherwise a negative error value
 314  * @retval #IME_ERROR_NONE No error
 315  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 316  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
 317  */
 318 int ime_prepare(void);
 319
 320 /**
 321  * @brief Requests IME to finalize explicitly.
 322  *
 323  * @since_tizen 4.0
 324  *
 325  * @privilege %http://tizen.org/privilege/ime
 326  *
 327  * @return 0 on success, otherwise a negative error value
 328  * @retval #IME_ERROR_NONE No error
 329  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 330  */
 331 int ime_finalize(void);
 332
 333 /**
 334  * @brief Sets flag whether IME is called from dotnet.
 335  *
 336  * @since_tizen 4.0
 337  *
 338  * @privilege %http://tizen.org/privilege/ime
 339  *
 340  * @param[in] set Set with Dotnet mode
 341  * @return 0 on success, otherwise a negative error value
 342  * @retval #IME_ERROR_NONE No error
 343  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 344  */
 345 int ime_set_dotnet_flag(bool set);
 346
 347 /**
 348  * @brief Sets flag whether creating IME window should be defered until there is a access request.
 349  *
 350  * @since_tizen 5.0
 351  *
 352  * @privilege %http://tizen.org/privilege/ime
 353  *
 354  * @param[in] flag true if deferring window creation is desired
 355  * @return 0 on success, otherwise a negative error value
 356  * @retval #IME_ERROR_NONE No error
 357  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 358  */
 359 int ime_set_window_creation_defer_flag(bool flag);
 360
 361 /**
 362  * @brief Sets @c ime_optimization_hint_set_cb() event callback function.
 363  *
 364  * @since_tizen 5.0
 365  *
 366  * @privilege %http://tizen.org/privilege/ime
 367  *
 368  * @remarks The ime_optimization_hint_set_cb() callback function is called when an optimization hint is set
 369  *
 370  * @param[in] callback_func @c ime_optimization_hint_set_cb() event callback function
 371  * @param[in] user_data User data to be passed to the callback function
 372  *
 373  * @return 0 on success, otherwise a negative error value
 374  * @retval #IME_ERROR_NONE No error
 375  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 376  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
 377  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
 378  *
 379  * @post The ime_run() function should be called to start to run IME application's main loop.
 380  *
 381  * @see ime_run()
 382  */
 383 int ime_event_set_optimization_hint_set_cb(ime_optimization_hint_set_cb callback_func, void *user_data);
 384
 385 #ifdef __cplusplus
 386 }
 387 #endif
 388
 389 #endif /* __TIZEN_UIX_INPUTMETHOD_INTERNAL_H__ */
 390