inputmethod/include/inputmethod.h

   1 /*
   2  * Copyright (c) 2014-2021 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_H__
  18 #define __TIZEN_UIX_INPUTMETHOD_H__
  19
  20 /**
  21  * @file inputmethod.h
  22  * @brief This file contains input method APIs and related enumeration.
  23  */
  24
  25 #include <tizen.h>
  26 #include <inputmethod_keydef.h>
  27 #include <inputmethod_device_event.h>
  28
  29 #include <Ecore_IMF.h>
  30 #include <Evas.h>
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /**
  37  * @addtogroup CAPI_UIX_INPUTMETHOD_MODULE
  38  * @{
  39  */
  40
  41 /**
  42  * @brief Enumeration for input method function error.
  43  *
  44  * @since_tizen 2.4
  45  */
  46 typedef enum {
  47         IME_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
  48         IME_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  49         IME_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */
  50         IME_ERROR_NO_CALLBACK_FUNCTION = TIZEN_ERROR_IME | 0x0001, /**< Necessary callback function is not set */
  51         IME_ERROR_NOT_RUNNING = TIZEN_ERROR_IME | 0x0002, /**< IME main loop is not started yet */
  52         IME_ERROR_OPERATION_FAILED = TIZEN_ERROR_IME | 0x0003, /**< Operation failed */
  53         IME_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< out of memory */
  54 } ime_error_e;
  55
  56 /**
  57  * @brief Enumeration of the option window type.
  58  *
  59  * @since_tizen 2.4
  60  *
  61  * @see ime_option_window_created_cb()
  62  */
  63 typedef enum {
  64         IME_OPTION_WINDOW_TYPE_KEYBOARD,  /**< Open from Keyboard */
  65         IME_OPTION_WINDOW_TYPE_SETTING_APPLICATION, /**< Open from Setting application */
  66 } ime_option_window_type_e;
  67
  68 /**
  69  * @brief Enumeration of layout variation.
  70  *
  71  * @since_tizen 2.4
  72  *
  73  * @see ime_context_get_layout_variation()
  74  */
  75 typedef enum {
  76         IME_LAYOUT_NORMAL_VARIATION_NORMAL = 0, /**< The plain normal layout */
  77         IME_LAYOUT_NORMAL_VARIATION_FILENAME, /**< Filename layout; symbols such as '/', '*', '\', '|', '&lt;', '&gt;', '?', '&quot;' and ':' should be disabled */
  78         IME_LAYOUT_NORMAL_VARIATION_PERSON_NAME, /**< The name of a person */
  79         IME_LAYOUT_NUMBERONLY_VARIATION_NORMAL = 0, /**< The plain normal number layout */
  80         IME_LAYOUT_NUMBERONLY_VARIATION_SIGNED, /**< The number layout to allow a negative sign */
  81         IME_LAYOUT_NUMBERONLY_VARIATION_DECIMAL, /**< The number layout to allow decimal point to provide fractional value */
  82         IME_LAYOUT_NUMBERONLY_VARIATION_SIGNED_AND_DECIMAL, /**< The number layout to allow decimal point and negative sign */
  83         IME_LAYOUT_PASSWORD_VARIATION_NORMAL = 0, /**< The normal password layout */
  84         IME_LAYOUT_PASSWORD_VARIATION_NUMBERONLY, /**< The password layout to allow only number */
  85 } ime_layout_variation_e;
  86
  87 /**
  88  * @brief Enumeration of string attribute type.
  89  *
  90  * @since_tizen 2.4
  91  *
  92  * @remarks Currently, a font style is available to use.
  93  *
  94  * @see #ime_preedit_attribute
  95  * @see ime_update_preedit_string()
  96  */
  97 typedef enum {
  98         IME_ATTR_NONE, /**< No attribute */
  99         IME_ATTR_FONTSTYLE, /**< A font style attribute, e.g., underline, etc. */
 100 } ime_attribute_type;
 101
 102 /**
 103  * @brief Enumeration containing input panel events.
 104  *
 105  * @since_tizen 5.5
 106  *
 107  * @see ime_update_input_panel_event()
 108  */
 109 typedef enum {
 110         IME_EVENT_TYPE_LANGUAGE = 1, /**< The language of the input panel */
 111         IME_EVENT_TYPE_SHIFT_MODE, /**< The shift key state of the input panel */
 112         IME_EVENT_TYPE_GEOMETRY, /**< The size of the input panel */
 113 } ime_event_type_e;
 114
 115 /**
 116  * @brief Value for #IME_ATTR_FONTSTYLE. Draw a line under the text.
 117  * @since_tizen 2.4
 118  */
 119 #define IME_ATTR_FONTSTYLE_UNDERLINE    1
 120
 121 /**
 122  * @brief Value for #IME_ATTR_FONTSTYLE. Draw text in highlighted color.
 123  * @since_tizen 2.4
 124  */
 125 #define IME_ATTR_FONTSTYLE_HIGHLIGHT    2
 126
 127 /**
 128  * @brief Value for #IME_ATTR_FONTSTYLE. Draw text in reversal color.
 129  * @since_tizen 2.4
 130  */
 131 #define IME_ATTR_FONTSTYLE_REVERSAL     4
 132
 133 /**
 134  * @brief The structure type to contain the attributes for preedit string.
 135  *
 136  * @since_tizen 2.4
 137  *
 138  * @remarks A preedit string may have one or more different attributes. This structure describes each attribute of the string.
 139  *
 140  * @see ime_update_preedit_string()
 141  * @see #ime_attribute_type
 142  */
 143 typedef struct {
 144         unsigned int start; /**< The start position in the string of this attribute */
 145         unsigned int length; /**< The character length of this attribute, the range is [start, start+length] */
 146         ime_attribute_type type; /**< The type of this attribute */
 147         unsigned int value; /**< The value of this attribute */
 148 } ime_preedit_attribute;
 149
 150 /**
 151  * @brief Handle of an associated text input UI control's input context.
 152  *
 153  * @details This is one of parameters of ime_show_cb() callback function. IME application
 154  * should configure its input panel with this structure information.
 155  *
 156  * @since_tizen 2.4
 157  *
 158  * @see ime_context_get_layout()
 159  * @see ime_context_get_layout_variation()
 160  * @see ime_context_get_cursor_position()
 161  * @see ime_context_get_autocapital_type()
 162  * @see ime_context_get_return_key_type()
 163  * @see ime_context_get_return_key_state()
 164  * @see ime_context_get_prediction_mode()
 165  * @see ime_context_get_password_mode()
 166  * @see ime_context_get_input_hint()
 167  * @see ime_context_get_bidi_direction()
 168  * @see ime_context_get_language()
 169  */
 170 typedef struct _ime_context *ime_context_h;
 171
 172 /**
 173  * @brief Handle of the device information of the key event.
 174  *
 175  * @details This is one of parameters of ime_process_key_event_cb() callback function. IME application
 176  * may distinguish the key event by using this if necessary.
 177  *
 178  * @since_tizen 2.4
 179  *
 180  * @see ime_process_key_event_cb()
 181  * @see ime_device_info_get_name()
 182  * @see ime_device_info_get_class()
 183  * @see ime_device_info_get_subclass()
 184  */
 185 typedef struct _ime_device_info *ime_device_info_h;
 186
 187 /**
 188  * @brief Called when the input panel is created.
 189  *
 190  * @since_tizen 2.4
 191  *
 192  * @privlevel public
 193  *
 194  * @privilege %http://tizen.org/privilege/ime
 195  *
 196  * @remarks This callback function is mandatory and must be registered using ime_run(). The
 197  * ime_get_main_window() can be used to get the created input panel window.
 198  *
 199  * @param[in] user_data User data to be passed from the callback registration function
 200  *
 201  * @pre The ime_run() function calls this callback function.
 202  *
 203  * @see ime_run()
 204  * @see ime_set_size()
 205  * @see ime_get_main_window()
 206  */
 207 typedef void (*ime_create_cb)(void *user_data);
 208
 209 /**
 210  * @brief Called when the input panel is terminated.
 211  *
 212  * @since_tizen 2.4
 213  *
 214  * @privlevel public
 215  *
 216  * @privilege %http://tizen.org/privilege/ime
 217  *
 218  * @remarks This callback function is mandatory and must be registered using ime_run(). The
 219  * ime_get_main_window() can be used to get the created input panel window.
 220  *
 221  * @param[in] user_data User data to be passed from the callback registration function
 222  *
 223  * @see ime_run()
 224  * @see ime_get_main_window()
 225  */
 226 typedef void (*ime_terminate_cb)(void *user_data);
 227
 228 /**
 229  * @brief Called when an associated text input UI control requests the input panel to show itself.
 230  *
 231  * @since_tizen 2.4
 232  *
 233  * @privlevel public
 234  *
 235  * @privilege %http://tizen.org/privilege/ime
 236  *
 237  * @remarks This callback function is mandatory and must be registered using ime_run().
 238  * IME application should configure its input panel with #ime_context_h structure information.
 239  * The ime_get_main_window() can be used to get the created input panel window.
 240  * @a context should not be released.
 241  *
 242  * @param[in] context_id The input context identification value of an associated text input UI control
 243  * @param[in] context The input context information handle
 244  * @param[in] user_data User data to be passed from the callback registration function
 245  *
 246  * @see ime_run()
 247  * @see ime_get_main_window()
 248  * @see ime_context_get_layout()
 249  * @see ime_context_get_layout_variation()
 250  * @see ime_context_get_cursor_position()
 251  * @see ime_context_get_autocapital_type()
 252  * @see ime_context_get_return_key_type()
 253  * @see ime_context_get_return_key_state()
 254  * @see ime_context_get_prediction_mode()
 255  * @see ime_context_get_password_mode()
 256  * @see ime_context_get_input_hint()
 257  * @see ime_context_get_bidi_direction()
 258  * @see ime_context_get_language()
 259  */
 260 typedef void (*ime_show_cb)(int context_id, ime_context_h context, void *user_data);
 261
 262 /**
 263  * @brief Called when an associated text input UI control requests the input panel to hide itself.
 264  *
 265  * @since_tizen 2.4
 266  *
 267  * @privlevel public
 268  *
 269  * @privilege %http://tizen.org/privilege/ime
 270  *
 271  * @remarks This callback function is mandatory and must be registered using ime_run(). The
 272  * ime_get_main_window() can be used to get the created input panel window.
 273  *
 274  * @param[in] context_id The input context identification value of an associated text input UI control
 275  * @param[in] user_data User data to be passed from the callback registration function
 276  *
 277  * @see ime_run()
 278  * @see ime_get_main_window()
 279  */
 280 typedef void (*ime_hide_cb)(int context_id, void *user_data);
 281
 282 /**
 283  * @brief Called when an associated text input UI control has focus.
 284  *
 285  * @since_tizen 2.4
 286  *
 287  * @privlevel public
 288  *
 289  * @privilege %http://tizen.org/privilege/ime
 290  *
 291  * @param[in] context_id The input context identification value of an associated text input UI control
 292  * @param[in] user_data User data to be passed from the callback registration function
 293  *
 294  * @pre The callback can be registered using ime_event_set_focus_in_cb() function.
 295  *
 296  * @see ime_event_set_focus_in_cb()
 297  */
 298 typedef void (*ime_focus_in_cb)(int context_id, void *user_data);
 299
 300 /**
 301  * @brief Called when an associated text input UI control loses focus.
 302  *
 303  * @since_tizen 2.4
 304  *
 305  * @privlevel public
 306  *
 307  * @privilege %http://tizen.org/privilege/ime
 308  *
 309  * @param[in] context_id The input context identification value of an associated text input UI control
 310  * @param[in] user_data User data to be passed from the callback registration function
 311  *
 312  * @pre The callback can be registered using ime_event_set_focus_out_cb() function.
 313  *
 314  * @see ime_event_set_focus_out_cb()
 315  */
 316 typedef void (*ime_focus_out_cb)(int context_id, void *user_data);
 317
 318 /**
 319  * @brief Called when an associated text input UI control responds to a request with the surrounding text.
 320  *
 321  * @since_tizen 2.4
 322  *
 323  * @privlevel public
 324  *
 325  * @privilege %http://tizen.org/privilege/ime
 326  *
 327  * @remarks The ime_request_surrounding_text() must be called to invoke this callback function, asynchronously.
 328  * @remarks @a text can be used only in the callback. To use outside, make a copy.
 329  *
 330  * @param[in] context_id The input context identification value of an associated text input UI control
 331  * @param[in] text The UTF-8 string requested
 332  * @param[in] cursor_pos The cursor position
 333  * @param[in] user_data User data to be passed from the callback registration function
 334  *
 335  * @pre The callback can be registered using ime_event_set_surrounding_text_updated_cb() function.
 336  *
 337  * @see ime_event_set_surrounding_text_updated_cb()
 338  * @see ime_request_surrounding_text()
 339  */
 340 typedef void (*ime_surrounding_text_updated_cb)(int context_id, const char *text, int cursor_pos, void *user_data);
 341
 342 /**
 343  * @brief Called to reset the input context of an associated text input UI control.
 344  *
 345  * @since_tizen 2.4
 346  *
 347  * @privlevel public
 348  *
 349  * @privilege %http://tizen.org/privilege/ime
 350  *
 351  * @param[in] user_data User data to be passed from the callback registration function
 352  *
 353  * @pre The callback can be registered using ime_event_set_input_context_reset_cb() function.
 354  *
 355  * @see ime_event_set_input_context_reset_cb()
 356  */
 357 typedef void (*ime_input_context_reset_cb)(void *user_data);
 358
 359 /**
 360  * @brief Called when the position of the cursor in an associated text input UI control changes.
 361  *
 362  * @since_tizen 2.4
 363  *
 364  * @privlevel public
 365  *
 366  * @privilege %http://tizen.org/privilege/ime
 367  *
 368  * @param[in] cursor_pos The cursor position
 369  * @param[in] user_data User data to be passed from the callback registration function
 370  *
 371  * @pre The callback can be registered using ime_event_set_cursor_position_updated_cb() function.
 372  *
 373  * @see ime_event_set_cursor_position_updated_cb()
 374  */
 375 typedef void (*ime_cursor_position_updated_cb)(int cursor_pos, void *user_data);
 376
 377 /**
 378  * @brief Called when an associated text input UI control requests the language from the input panel.
 379  *
 380  * @since_tizen 2.4
 381  *
 382  * @privlevel public
 383  *
 384  * @privilege %http://tizen.org/privilege/ime
 385  *
 386  * @remarks The allocated @a lang_code will be released internally.
 387  *
 388  * @param[in] user_data User data to be passed from the callback registration function
 389  * @param[out] lang_code Input panel's current input language code (e.g., &quot;en_US&quot;)
 390  *
 391  * @pre The callback can be registered using ime_event_set_language_requested_cb() function.
 392  *
 393  * @see ime_event_set_language_requested_cb()
 394  */
 395 typedef void (*ime_language_requested_cb)(void *user_data, char **lang_code);
 396
 397 /**
 398  * @brief Called to set the preferred language to the input panel.
 399  *
 400  * @since_tizen 2.4
 401  *
 402  * @privlevel public
 403  *
 404  * @privilege %http://tizen.org/privilege/ime
 405  *
 406  * @remarks @a language information is already set to the input panel when it is shown
 407  * through #ime_context_h. This callback function will be only called when the client
 408  * application changes the edit field's language attribute after the input panel is shown.
 409  *
 410  * @param[in] language The preferred language that the client application wants
 411  * @param[in] user_data User data to be passed from the callback registration function
 412  *
 413  * @pre The callback can be registered using ime_event_set_language_set_cb() function.
 414  *
 415  * @see ime_event_set_language_set_cb()
 416  */
 417 typedef void (*ime_language_set_cb)(Ecore_IMF_Input_Panel_Lang language, void *user_data);
 418
 419 /**
 420  * @brief Called to set the application specific data to deliver to the input panel.
 421  *
 422  * @details This function is used by the applications to deliver the specific data to the input panel.
 423  * The data format MUST be negotiated by both application and input panel.
 424  *
 425  * @since_tizen 2.4
 426  *
 427  * @privlevel public
 428  *
 429  * @privilege %http://tizen.org/privilege/ime
 430  *
 431  * @remarks @a data should not be released.
 432  *
 433  * @param[in] data The specific data to be set to the input panel
 434  * @param[in] data_length The length of data, in bytes, to send to the input panel
 435  * @param[in] user_data User data to be passed from the callback registration function
 436  *
 437  * @pre The callback can be registered using ime_event_set_imdata_set_cb() function.
 438  *
 439  * @see ime_event_set_imdata_set_cb()
 440  */
 441 typedef void (*ime_imdata_set_cb)(void *data, unsigned int data_length, void *user_data);
 442
 443 /**
 444  * @brief Called when an associated text input UI control requests the application specific data from the input panel.
 445  *
 446  * @details This function is used by the applications to request the specific data from the input panel.
 447  * The data format MUST be negotiated by both application and input panel.
 448  *
 449  * @since_tizen 2.4
 450  *
 451  * @privlevel public
 452  *
 453  * @privilege %http://tizen.org/privilege/ime
 454  *
 455  * @remarks The allocated @a data and @a data_length will be released internally.
 456  *
 457  * @param[in] user_data User data to be passed from the callback registration function
 458  * @param[out] data Input panel's data to be set to the application
 459  * @param[out] data_length The length of data, in bytes, to send to the application
 460  *
 461  * @pre The callback can be registered using ime_event_set_imdata_requested_cb() function.
 462  *
 463  * @see ime_event_set_imdata_requested_cb()
 464  */
 465 typedef void (*ime_imdata_requested_cb)(void *user_data, void **data, unsigned int *data_length);
 466
 467 /**
 468  * @brief Called when an associated text input UI control requests the input panel to set its layout.
 469  *
 470  * @since_tizen 2.4
 471  *
 472  * @privlevel public
 473  *
 474  * @privilege %http://tizen.org/privilege/ime
 475  *
 476  * @remarks @a layout information is already set to the input panel when it is shown
 477  * through #ime_context_h. This callback function will be only called when the client
 478  * application changes the edit field's layout attribute after the input panel is shown.
 479  *
 480  * @param[in] layout The input panel layout
 481  * @param[in] user_data User data to be passed from the callback registration function
 482  *
 483  * @pre The callback can be registered using ime_event_set_layout_set_cb() function.
 484  *
 485  * @see ime_event_set_layout_set_cb()
 486  */
 487 typedef void (*ime_layout_set_cb)(Ecore_IMF_Input_Panel_Layout layout, void *user_data);
 488
 489 /**
 490  * @brief Called when an associated text input UI control requests the input panel to set input hint.
 491  *
 492  * @since_tizen 6.5
 493  *
 494  * @privlevel public
 495  *
 496  * @privilege %http://tizen.org/privilege/ime
 497  *
 498  * @remarks @a input_hint information is already set to the input panel when it is shown
 499  * through #ime_context_h. This callback function will be only called when the client
 500  * application changes the edit field's input hint attribute after the input panel is shown.
 501  *
 502  * @param[in] input_hint The input hint
 503  * @param[in] user_data User data to be passed from the callback registration function
 504  *
 505  * @pre The callback can be registered using ime_event_set_input_hint_set_cb() function.
 506  *
 507  * @see ime_event_set_input_hint_set_cb()
 508  */
 509 typedef void (*ime_input_hint_set_cb)(Ecore_IMF_Input_Hints input_hint, void *user_data);
 510
 511 /**
 512  * @brief Called when an associated text input UI control requests the input panel to set the @c Return key label.
 513  * The input panel can show text or image on the @c Return button according to the @c Return key action.
 514  *
 515  * @since_tizen 2.4
 516  *
 517  * @privlevel public
 518  *
 519  * @privilege %http://tizen.org/privilege/ime
 520  *
 521  * @remarks @a type information is already set to the input panel when it is shown
 522  * through #ime_context_h. This callback function will be only called when the client
 523  * application changes the edit field's @c Return key type attribute after the input panel
 524  * is shown.
 525  *
 526  * @param[in] type The type of @c Return key on the input panel
 527  * @param[in] user_data User data to be passed from the callback registration function
 528  *
 529  * @pre The callback can be registered using ime_event_set_return_key_type_set_cb() function.
 530  *
 531  * @see ime_event_set_return_key_type_set_cb()
 532  */
 533 typedef void (*ime_return_key_type_set_cb)(Ecore_IMF_Input_Panel_Return_Key_Type type, void *user_data);
 534
 535 /**
 536  * @brief Called when an associated text input UI control requests the input panel to enable
 537  * or disable the @c Return key state.
 538  *
 539  * @since_tizen 2.4
 540  *
 541  * @privlevel public
 542  *
 543  * @privilege %http://tizen.org/privilege/ime
 544  *
 545  * @remarks @a disabled information is already set to the input panel when it is shown
 546  * through #ime_context_h. This callback function will be only called when the client
 547  * application changes the edit field's @c Return key disable attribute after the input panel
 548  * is shown.
 549  *
 550  * @param[in] disabled The Boolean state to disable @c Return key. The @c Return key is enabled by default
 551  * @param[in] user_data User data to be passed from the callback registration function
 552  *
 553  * @pre The callback can be registered using ime_event_set_return_key_state_set_cb() function.
 554  *
 555  * @see ime_event_set_return_key_state_set_cb()
 556  */
 557 typedef void (*ime_return_key_state_set_cb)(bool disabled, void *user_data);
 558
 559 /**
 560  * @brief Called when an associated text input UI control requests the position and size from the input panel.
 561  *
 562  * @since_tizen 2.4
 563  *
 564  * @privlevel public
 565  *
 566  * @privilege %http://tizen.org/privilege/ime
 567  *
 568  * @remarks @a x, @a y, @a w, and @a h should not be released.
 569  *
 570  * @param[in] user_data User data to be passed from the callback registration function
 571  * @param[out] x The x position in screen
 572  * @param[out] y The y position in screen
 573  * @param[out] w The window width
 574  * @param[out] h The window height
 575  *
 576  * @pre The callback can be registered using ime_event_set_geometry_requested_cb() function.
 577  *
 578  * @see ime_event_set_geometry_requested_cb()
 579  */
 580 typedef void (*ime_geometry_requested_cb)(void *user_data, int *x, int *y, int *w, int *h);
 581
 582 /**
 583  * @brief Called when a key event is received from external devices or ime_send_key_event().
 584  *
 585  * @details This function processes the key event before an associated text input UI control does.
 586  *
 587  * @since_tizen 2.4
 588  *
 589  * @privlevel public
 590  *
 591  * @privilege %http://tizen.org/privilege/ime
 592  *
 593  * @remarks If the key event is from the external device, @a dev_info will have its name, class and subclass information.
 594  * @a dev_info should not be released by the application. The platform manages the handle; the handle is released when ime_process_key_event_cb() exits.
 595  *
 596  * @param[in] key_code The key code to be sent
 597  * @param[in] key_mask The modifier key mask
 598  * @param[in] dev_info The device information handle
 599  * @param[in] user_data User data to be passed from the callback registration function
 600  *
 601  * @return @c true if the event was processed, otherwise the event was not processed and was forwarded to the client application.
 602  *
 603  * @pre The callback should be registered using ime_event_set_process_key_event_cb() function.
 604  *
 605  * @see ime_event_set_process_key_event_cb()
 606  * @see ime_device_info_get_name()
 607  * @see ime_device_info_get_class()
 608  * @see ime_device_info_get_subclass()
 609  * @see ime_send_key_event()
 610  * @see ime_commit_string()
 611  * @see ime_show_preedit_string()
 612  * @see ime_hide_preedit_string()
 613  * @see ime_update_preedit_string()
 614  */
 615 typedef bool (*ime_process_key_event_cb)(ime_key_code_e key_code, ime_key_mask_e key_mask, ime_device_info_h dev_info, void *user_data);
 616
 617 /**
 618  * @brief Called when a key event is received with a keycode from external devices or ime_send_key_event().
 619  *
 620  * @details This function processes a key event with a keycode before an associated UI control for the text input deals with the key event.
 621  *
 622  * @since_tizen 5.5
 623  *
 624  * @privlevel public
 625  *
 626  * @privilege %http://tizen.org/privilege/ime
 627  *
 628  * @remarks If the key event is from the external device, @a dev_info will have its name, class and subclass information.
 629  * @a dev_info should not be released by the application. The platform manages the handle; the handle is released when ime_process_key_event_with_keycode_cb() exits.
 630  *
 631  * @param[in] key_code The X11 key code to be sent
 632  * @param[in] key_sym The key symbol to be sent
 633  * @param[in] key_mask The modifier key mask
 634  * @param[in] dev_info The device information handle
 635  * @param[in] user_data User data to be passed from the callback registration function
 636  *
 637  * @return @c true if the event was processed, otherwise @c false. When @c false returns, the event was not processed and was forwarded to the client application.
 638  *
 639  * @pre The callback should be registered using ime_event_set_process_key_event_with_keycode_cb() function.
 640  *
 641  * @see ime_event_set_process_key_event_with_keycode_cb()
 642  * @see ime_device_info_get_name()
 643  * @see ime_device_info_get_class()
 644  * @see ime_device_info_get_subclass()
 645  * @see ime_send_key_event()
 646  * @see ime_commit_string()
 647  * @see ime_show_preedit_string()
 648  * @see ime_hide_preedit_string()
 649  * @see ime_update_preedit_string()
 650  */
 651 typedef bool (*ime_process_key_event_with_keycode_cb)(unsigned int key_code, ime_key_code_e key_sym, ime_key_mask_e key_mask, ime_device_info_h dev_info, void *user_data);
 652
 653 /**
 654  * @brief Called when the system display language is changed.
 655  *
 656  * @since_tizen 2.4
 657  *
 658  * @privlevel public
 659  *
 660  * @privilege %http://tizen.org/privilege/ime
 661  *
 662  * @param[in] language The language code
 663  * @param[in] user_data User data to be passed from the callback registration function
 664  *
 665  * @pre The callback can be registered using ime_event_set_display_language_changed_cb() function.
 666  *
 667  * @see ime_event_set_display_language_changed_cb()
 668  */
 669 typedef void (*ime_display_language_changed_cb)(const char *language, void *user_data);
 670
 671 /**
 672  * @brief Called when the device is rotated.
 673  *
 674  * @since_tizen 2.4
 675  *
 676  * @privlevel public
 677  *
 678  * @privilege %http://tizen.org/privilege/ime
 679  *
 680  * @param[in] degree The rotation degree
 681  * @param[in] user_data User data to be passed from the callback registration function
 682  *
 683  * @pre The callback can be registered using ime_event_set_rotation_degree_changed_cb() function.
 684  *
 685  * @see ime_event_set_rotation_degree_changed_cb()
 686  */
 687 typedef void (*ime_rotation_degree_changed_cb)(int degree, void *user_data);
 688
 689 /**
 690  * @brief Called when Accessibility in Settings application is on or off.
 691  *
 692  * @since_tizen 2.4
 693  *
 694  * @privlevel public
 695  *
 696  * @privilege %http://tizen.org/privilege/ime
 697  *
 698  * @param[in] state Accessibility option state
 699  * @param[in] user_data User data to be passed from the callback registration function
 700  *
 701  * @pre The callback can be registered using ime_event_set_accessibility_state_changed_cb() function.
 702  *
 703  * @see ime_event_set_accessibility_state_changed_cb()
 704  */
 705 typedef void (*ime_accessibility_state_changed_cb)(bool state, void *user_data);
 706
 707 /**
 708  * @brief Called to create the option window.
 709  *
 710  * @since_tizen 2.4
 711  *
 712  * @privlevel public
 713  *
 714  * @privilege %http://tizen.org/privilege/ime
 715  *
 716  * @remarks if Input panel requests to open the option window, @a type will be #IME_OPTION_WINDOW_TYPE_KEYBOARD.
 717  * And if Settings application requests to open it, @a type will be #IME_OPTION_WINDOW_TYPE_SETTING_APPLICATION.
 718  * The @a window should not be released. The @a window can be used until ime_option_window_destroyed_cb() will be called.
 719  *
 720  * @param[in] window The created window object
 721  * @param[in] type The type of option window
 722  * @param[in] user_data User data to be passed from the callback registration function
 723  *
 724  * @pre The callback can be registered using ime_event_set_option_window_created_cb() function. The
 725  * ime_create_option_window() calls this callback function or Settings application can call this callback function.
 726  *
 727  * @see ime_event_set_option_window_created_cb()
 728  * @see ime_create_option_window()
 729  */
 730 typedef void (*ime_option_window_created_cb)(Evas_Object *window, ime_option_window_type_e type, void *user_data);
 731
 732 /**
 733  * @brief Called to destroy the option window.
 734  *
 735  * @since_tizen 2.4
 736  *
 737  * @privlevel public
 738  *
 739  * @privilege %http://tizen.org/privilege/ime
 740  *
 741  * @remarks The @a window should be released using evas_object_del().
 742  *
 743  * @param[in] window The window object to destroy
 744  * @param[in] user_data User data to be passed to the callback function
 745  *
 746  * @pre The callback can be registered using ime_event_set_option_window_destroyed_cb() function.
 747  * ime_destroy_option_window() calls this callback function.
 748  *
 749  * @see ime_event_set_option_window_destroyed_cb()
 750  */
 751 typedef void (*ime_option_window_destroyed_cb)(Evas_Object *window, void *user_data);
 752
 753 /**
 754  * @brief Called to set the prediction hint string to deliver to the input panel.
 755  *
 756  * @since_tizen 4.0
 757  *
 758  * @privlevel public
 759  *
 760  * @privilege %http://tizen.org/privilege/ime
 761  *
 762  * @remarks @a prediction_hint is valid only in the callback. To use outside the callback, make a copy.
 763  * This function is used by the applications to deliver the prediction hint message to the input panel.
 764  *
 765  * @param[in] prediction_hint The prediction hint to be set to the input panel
 766  * @param[in] user_data User data to be passed to the callback function
 767  *
 768  * @pre The callback can be registered using ime_event_set_prediction_hint_set_cb() function.
 769  *
 770  * @see ime_event_set_prediction_hint_set_cb()
 771  */
 772 typedef void (*ime_prediction_hint_set_cb)(const char *prediction_hint, void *user_data);
 773
 774 /**
 775  * @brief Called when an associated text input UI control requests the text entry to set the MIME type.
 776  *
 777  * @since_tizen 4.0
 778  *
 779  * @privlevel public
 780  *
 781  * @privilege %http://tizen.org/privilege/ime
 782  *
 783  * @remarks @a mime_type is valid only in the callback. To use outside the callback, make a copy.
 784  * This function is used by the applications to deliver the MIME type to the input panel.
 785  *
 786  * @param[in] mime_type The MIME type to be set to the input panel
 787  * @param[in] user_data User data to be passed to the callback function
 788  *
 789  * @pre The callback can be registered using ime_event_set_mime_type_set_request_cb() function.
 790  *
 791  * @see ime_event_set_mime_type_set_request_cb()
 792  */
 793 typedef void (*ime_mime_type_set_request_cb)(const char *mime_type, void *user_data);
 794
 795 /**
 796  * @brief Called to set key-value pairs of predicting messages to deliver to the input panel.
 797  *
 798  * @since_tizen 5.0
 799  *
 800  * @privlevel public
 801  *
 802  * @privilege %http://tizen.org/privilege/ime
 803  *
 804  * @remarks @a key and @a value is valid only in the callback. To use outside the callback, make a copy.
 805  * This function is used by applications to deliver predicted hint messages to the input panel.
 806  *
 807  * @param[in] key The prediction hint key to be set to the input panel
 808  * @param[in] value The prediction hint value to be set to the input panel
 809  * @param[in] user_data User data to be passed to the callback function
 810  *
 811  * @pre The callback can be registered using ime_event_set_prediction_hint_data_set_cb() function.
 812  *
 813  * @see ime_event_set_prediction_hint_data_set_cb()
 814  */
 815 typedef void (*ime_prediction_hint_data_set_cb)(const char *key, const char *value, void *user_data);
 816
 817 /**
 818  * @brief The structure type to contain the set of the essential callback functions for IME application lifecycle and appearance.
 819  *
 820  * @since_tizen 2.4
 821  *
 822  * @remarks These four callback functions are mandatory for IME application.
 823  *
 824  * @see ime_run()
 825  */
 826 typedef struct {
 827         ime_create_cb create;       /**< Called when the input panel is created */
 828         ime_terminate_cb terminate; /**< Called when the input panel is terminated */
 829         ime_show_cb show;           /**< Called when the input panel is requested to show itself */
 830         ime_hide_cb hide;           /**< Called when the input panel is requested to hide itself */
 831 } ime_callback_s;
 832
 833 /**
 834  * @brief Runs the main loop of IME application.
 835  *
 836  * @details This function starts to run IME application's main loop. The ime_create_cb()
 837  * callback function is called to initialize IME application before the main loop starts up. And
 838  * the ime_terminate_cb() callback function is called when IME application is terminated.
 839  *
 840  * @since_tizen 2.4
 841  *
 842  * @privlevel public
 843  *
 844  * @privilege %http://tizen.org/privilege/ime
 845  *
 846  * @remarks IME application MUST implement ime_app_main() function which is the main
 847  * entry point of IME application. In ime_app_main() function, the ime_run()
 848  * function MUST be called with the necessary callback functions; ime_create_cb(),
 849  * ime_terminate_cb(), ime_show_cb(), and ime_hide_cb() callback functions
 850  * are mandatory for IME application.
 851  *
 852  * @param[in] basic_cb The structure pointer of the essential callback functions
 853  * @param[in] user_data User data to be passed to the callback functions
 854  *
 855  * @return 0 if IME application ends successfully, otherwise a negative error value
 856  * @retval #IME_ERROR_NONE No error
 857  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
 858  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
 859  * @retval #IME_ERROR_NO_CALLBACK_FUNCTION Necessary callback function is not set
 860  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
 861  *
 862  * @pre The ime_event_set_***() functions can be called to set the event handling callback functions.
 863  *
 864  * @see #ime_callback_s
 865  * @see ime_event_set_focus_in_cb()
 866  * @see ime_event_set_focus_out_cb()
 867  * @see ime_event_set_surrounding_text_updated_cb()
 868  * @see ime_event_set_input_context_reset_cb()
 869  * @see ime_event_set_cursor_position_updated_cb()
 870  * @see ime_event_set_language_requested_cb()
 871  * @see ime_event_set_language_set_cb()
 872  * @see ime_event_set_imdata_set_cb()
 873  * @see ime_event_set_layout_set_cb()
 874  * @see ime_event_set_return_key_type_set_cb()
 875  * @see ime_event_set_return_key_state_set_cb()
 876  * @see ime_event_set_geometry_requested_cb()
 877  * @see ime_event_set_display_language_changed_cb()
 878  * @see ime_event_set_rotation_degree_changed_cb()
 879  * @see ime_event_set_accessibility_state_changed_cb()
 880  * @see ime_event_set_option_window_created_cb()
 881  * @see ime_event_set_option_window_destroyed_cb()
 882  * @see ime_event_set_prediction_hint_set_cb()
 883  *
 884  * @code
 885  static void inputmethod_create_cb(void *user_data);
 886  static void inputmethod_terminate_cb(void *user_data);
 887  static void inputmethod_show_cb(int context_id, ime_context_h context, void *user_data);
 888  static void inputmethod_hide_cb(int context_id, void *user_data);
 889  static void inputmethod_focus_in_cb(int context_id, void *user_data);
 890  static void inputmethod_focus_out_cb(int context_id, void *user_data);
 891  static void inputmethod_cursor_position_updated_cb(int cursor_pos, void *user_data);
 892
 893  static void inputmethod_create_cb(void *user_data)
 894  {
 895          Evas_Object *ime_win = NULL;
 896
 897          ime_set_size(480, 400, 800, 400);
 898          ime_win = ime_get_main_window();
 899          if (ime_win) {
 900                  // Prepare before showing IME window.
 901          }
 902  }
 903
 904  static void inputmethod_show_cb(int context_id, ime_context_h context, void *user_data)
 905  {
 906          Ecore_IMF_Input_Panel_Layout layout;
 907          ime_layout_variation_e layout_variation;
 908          Evas_Object *ime_win;
 909
 910          ime_context_get_layout(context, &layout);
 911          ime_context_get_layout_variation(context, &layout_variation);
 912
 913          ime_win = ime_get_main_window();
 914          if (ime_win) {
 915                  // Compose IME UI properly with the context information and show.
 916
 917                  evas_object_show(ime_win);
 918          }
 919  }
 920
 921  static void inputmethod_hide_cb(int context_id, void *user_data)
 922  {
 923          Evas_Object *ime_win = ime_get_main_window();
 924          if (ime_win) {
 925                  evas_object_hide(ime_win);
 926          }
 927  }
 928
 929  void ime_app_main(int argc, char **argv)
 930  {
 931          ime_callback_s basic_callback = {
 932                  inputmethod_create_cb,
 933                  inputmethod_terminate_cb,
 934                  inputmethod_show_cb,
 935                  inputmethod_hide_cb,
 936          };
 937
 938          ime_event_set_focus_in_cb(inputmethod_focus_in_cb, NULL);
 939          ime_event_set_focus_out_cb(inputmethod_focus_out_cb, NULL);
 940          ime_event_set_cursor_position_updated_cb(inputmethod_cursor_position_updated_cb, NULL);
 941
 942          ime_run(&basic_callback, NULL);
 943  }
 944  * @endcode
 945  */
 946 int ime_run(ime_callback_s *basic_cb, void *user_data);
 947
 948 /**
 949  * @brief Sets @c focus_in event callback function.
 950  *
 951  * @since_tizen 2.4
 952  *
 953  * @privlevel public
 954  *
 955  * @privilege %http://tizen.org/privilege/ime
 956  *
 957  * @remarks The ime_focus_in_cb() callback function is called when an associated text input
 958  * UI control has focus.
 959  *
 960  * @param[in] callback_func @c focus_in event callback function
 961  * @param[in] user_data User data to be passed to the callback function
 962  *
 963  * @return 0 on success, otherwise a negative error value
 964  * @retval #IME_ERROR_NONE No error
 965  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
 966  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
 967  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
 968  *
 969  * @post The ime_run() function should be called to start the IME application's main loop.
 970  *
 971  * @see ime_focus_in_cb()
 972  * @see ime_run()
 973  */
 974 int ime_event_set_focus_in_cb(ime_focus_in_cb callback_func, void *user_data);
 975
 976 /**
 977  * @brief Sets @c focus_out event callback function.
 978  *
 979  * @since_tizen 2.4
 980  *
 981  * @privlevel public
 982  *
 983  * @privilege %http://tizen.org/privilege/ime
 984  *
 985  * @remarks The ime_focus_out_cb() callback function is called when an associated text input
 986  * UI control loses focus.
 987  *
 988  * @param[in] callback_func @c focus_out event callback function
 989  * @param[in] user_data User data to be passed to the callback function
 990  *
 991  * @return 0 on success, otherwise a negative error value
 992  * @retval #IME_ERROR_NONE No error
 993  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
 994  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
 995  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
 996  *
 997  * @post The ime_run() function should be called to start the IME application's main loop.
 998  *
 999  * @see ime_focus_out_cb()
1000  * @see ime_run()
1001  */
1002 int ime_event_set_focus_out_cb(ime_focus_out_cb callback_func, void *user_data);
1003
1004 /**
1005  * @brief Sets @c surrounding_text_updated event callback function.
1006  *
1007  * @since_tizen 2.4
1008  *
1009  * @privlevel public
1010  *
1011  * @privilege %http://tizen.org/privilege/ime
1012  *
1013  * @remarks The ime_surrounding_text_updated_cb() callback function is called when an
1014  * associated text input UI control responds to a request with the surrounding text.
1015  *
1016  * @param[in] callback_func @c surrounding_text_updated event callback function
1017  * @param[in] user_data User data to be passed to the callback function
1018  *
1019  * @return 0 on success, otherwise a negative error value
1020  * @retval #IME_ERROR_NONE No error
1021  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1022  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1023  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
1024  *
1025  * @post The ime_run() function should be called to start the IME application's main loop.
1026  *
1027  * @see ime_surrounding_text_updated_cb()
1028  * @see ime_run()
1029  */
1030 int ime_event_set_surrounding_text_updated_cb(ime_surrounding_text_updated_cb callback_func, void *user_data);
1031
1032 /**
1033  * @brief Sets @c input_context_reset event callback function.
1034  *
1035  * @since_tizen 2.4
1036  *
1037  * @privlevel public
1038  *
1039  * @privilege %http://tizen.org/privilege/ime
1040  *
1041  * @remarks The ime_input_context_reset_cb() callback function is called to reset the input
1042  * context of an associated text input UI control.
1043  *
1044  * @param[in] callback_func @c input_context_reset event callback function
1045  * @param[in] user_data User data to be passed to the callback function
1046  *
1047  * @return 0 on success, otherwise a negative error value
1048  * @retval #IME_ERROR_NONE No error
1049  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1050  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1051  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
1052  *
1053  * @post The ime_run() function should be called to start the IME application's main loop.
1054  *
1055  * @see ime_input_context_reset_cb()
1056  * @see ime_run()
1057  */
1058 int ime_event_set_input_context_reset_cb(ime_input_context_reset_cb callback_func, void *user_data);
1059
1060 /**
1061  * @brief Sets @c cursor_position_updated event callback function.
1062  *
1063  * @since_tizen 2.4
1064  *
1065  * @privlevel public
1066  *
1067  * @privilege %http://tizen.org/privilege/ime
1068  *
1069  * @remarks The ime_cursor_position_updated_cb() callback function is called when the position
1070  * of the cursor in an associated text input UI control changes.
1071  *
1072  * @param[in] callback_func @c cursor_position_updated event callback function
1073  * @param[in] user_data User data to be passed to the callback function
1074  *
1075  * @return 0 on success, otherwise a negative error value
1076  * @retval #IME_ERROR_NONE No error
1077   * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1078  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1079  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
1080  *
1081  * @post The ime_run() function should be called to start the IME application's main loop.
1082  *
1083  * @see ime_cursor_position_updated_cb()
1084  * @see ime_run()
1085  */
1086 int ime_event_set_cursor_position_updated_cb(ime_cursor_position_updated_cb callback_func, void *user_data);
1087
1088 /**
1089  * @brief Sets @c language_requested event callback function.
1090  *
1091  * @since_tizen 2.4
1092  *
1093  * @privlevel public
1094  *
1095  * @privilege %http://tizen.org/privilege/ime
1096  *
1097  * @remarks The ime_language_requested_cb() callback function is called when an associated
1098  * text input UI control requests the language from the input panel.
1099  *
1100  * @param[in] callback_func @c language_requested event callback function
1101  * @param[in] user_data User data to be passed to the callback function
1102  *
1103  * @return 0 on success, otherwise a negative error value
1104  * @retval #IME_ERROR_NONE No error
1105  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1106  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1107  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
1108  *
1109  * @post The ime_run() function should be called to start the IME application's main loop.
1110  *
1111  * @see ime_language_requested_cb()
1112  * @see ime_run()
1113  */
1114 int ime_event_set_language_requested_cb(ime_language_requested_cb callback_func, void *user_data);
1115
1116 /**
1117  * @brief Sets @c language_set event callback function.
1118  *
1119  * @since_tizen 2.4
1120  *
1121  * @privlevel public
1122  *
1123  * @privilege %http://tizen.org/privilege/ime
1124  *
1125  * @remarks The ime_language_set_cb() callback function is called to set the preferred
1126  * language to the input panel.
1127  *
1128  * @param[in] callback_func @c language_set event callback function
1129  * @param[in] user_data User data to be passed to the callback function
1130  *
1131  * @return 0 on success, otherwise a negative error value
1132  * @retval #IME_ERROR_NONE No error
1133  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1134  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1135  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
1136  *
1137  * @post The ime_run() function should be called to start the IME application's main loop.
1138  *
1139  * @see ime_language_set_cb()
1140  * @see ime_run()
1141  */
1142 int ime_event_set_language_set_cb(ime_language_set_cb callback_func, void *user_data);
1143
1144 /**
1145  * @brief Sets @c imdata_set event callback function.
1146  *
1147  * @since_tizen 2.4
1148  *
1149  * @privlevel public
1150  *
1151  * @privilege %http://tizen.org/privilege/ime
1152  *
1153  * @remarks The ime_imdata_set_cb() callback function is called to set the application
1154  * specific data to deliver to the input panel.
1155  *
1156  * @param[in] callback_func @c imdata_set event callback function
1157  * @param[in] user_data User data to be passed to the callback function
1158  *
1159  * @return 0 on success, otherwise a negative error value
1160  * @retval #IME_ERROR_NONE No error
1161  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1162  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1163  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
1164  *
1165  * @post The ime_run() function should be called to start the IME application's main loop.
1166  *
1167  * @see ime_imdata_set_cb()
1168  * @see ime_event_set_imdata_requested_cb()
1169  * @see ime_run()
1170  */
1171 int ime_event_set_imdata_set_cb(ime_imdata_set_cb callback_func, void *user_data);
1172
1173 /**
1174  * @brief Sets @c imdata_requested event callback function.
1175  *
1176  * @since_tizen 2.4
1177  *
1178  * @privlevel public
1179  *
1180  * @privilege %http://tizen.org/privilege/ime
1181  *
1182  * @remarks The ime_imdata_requested_cb() callback function is called when an associated
1183  * text input UI control requests the application specific data from the input panel.
1184  *
1185  * @param[in] callback_func @c imdata_requested event callback function
1186  * @param[in] user_data User data to be passed to the callback function
1187  *
1188  * @return 0 on success, otherwise a negative error value
1189  * @retval #IME_ERROR_NONE No error
1190  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1191  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1192  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
1193  *
1194  * @post The ime_run() function should be called to start the IME application's main loop.
1195  *
1196  * @see ime_imdata_requested_cb()
1197  * @see ime_event_set_imdata_set_cb()
1198  * @see ime_run()
1199  */
1200 int ime_event_set_imdata_requested_cb(ime_imdata_requested_cb callback_func, void *user_data);
1201
1202 /**
1203  * @brief Sets @c layout_set event callback function.
1204  *
1205  * @since_tizen 2.4
1206  *
1207  * @privlevel public
1208  *
1209  * @privilege %http://tizen.org/privilege/ime
1210  *
1211  * @remarks The ime_layout_set_cb() callback function is called when an associated text input
1212  * UI control requests the input panel to set its layout.
1213  *
1214  * @param[in] callback_func @c layout_set event callback function
1215  * @param[in] user_data User data to be passed to the callback function
1216  *
1217  * @return 0 on success, otherwise a negative error value
1218  * @retval #IME_ERROR_NONE No error
1219  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1220  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1221  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
1222  *
1223  * @post The ime_run() function should be called to start the IME application's main loop.
1224  *
1225  * @see ime_layout_set_cb()
1226  * @see ime_run()
1227  */
1228 int ime_event_set_layout_set_cb(ime_layout_set_cb callback_func, void *user_data);
1229
1230 /**
1231  * @brief Sets @c return_key_type_set event callback function.
1232  *
1233  * @since_tizen 2.4
1234  *
1235  * @privlevel public
1236  *
1237  * @privilege %http://tizen.org/privilege/ime
1238  *
1239  * @remarks The ime_return_key_type_set_cb() callback function is called when an associated
1240  * text input UI control requests the input panel to set the @c Return key label.
1241  *
1242  * @param[in] callback_func @c return_key_type_set event callback function
1243  * @param[in] user_data User data to be passed to the callback function
1244  *
1245  * @return 0 on success, otherwise a negative error value
1246  * @retval #IME_ERROR_NONE No error
1247  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1248  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1249  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
1250  *
1251  * @post The ime_run() function should be called to start the IME application's main loop.
1252  *
1253  * @see ime_return_key_type_set_cb()
1254  * @see ime_run()
1255  */
1256 int ime_event_set_return_key_type_set_cb(ime_return_key_type_set_cb callback_func, void *user_data);
1257
1258 /**
1259  * @brief Sets @c return_key_state_set event callback function.
1260  *
1261  * @since_tizen 2.4
1262  *
1263  * @privlevel public
1264  *
1265  * @privilege %http://tizen.org/privilege/ime
1266  *
1267  * @remarks The ime_return_key_state_set_cb() callback function is called when an associated
1268  * text input UI control requests the input panel to enable or disable the @c Return key state.
1269  *
1270  * @param[in] callback_func @c return_key_state_set event callback function
1271  * @param[in] user_data User data to be passed to the callback function
1272  *
1273  * @return 0 on success, otherwise a negative error value
1274  * @retval #IME_ERROR_NONE No error
1275  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1276  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1277  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
1278  *
1279  * @post The ime_run() function should be called to start the IME application's main loop.
1280  *
1281  * @see ime_return_key_state_set_cb()
1282  * @see ime_run()
1283  */
1284 int ime_event_set_return_key_state_set_cb(ime_return_key_state_set_cb callback_func, void *user_data);
1285
1286 /**
1287  * @brief Sets @c geometry_requested event callback function.
1288  *
1289  * @since_tizen 2.4
1290  *
1291  * @privlevel public
1292  *
1293  * @privilege %http://tizen.org/privilege/ime
1294  *
1295  * @remarks The ime_geometry_requested_cb() callback function is called when an associated
1296  * text input UI control requests the position and size from the input panel.
1297  *
1298  * @param[in] callback_func @c geometry_requested event callback function
1299  * @param[in] user_data User data to be passed to the callback function
1300  *
1301  * @return 0 on success, otherwise a negative error value
1302  * @retval #IME_ERROR_NONE No error
1303  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1304  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1305  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
1306  *
1307  * @post The ime_run() function should be called to start the IME application's main loop.
1308  *
1309  * @see ime_geometry_requested_cb()
1310  * @see ime_run()
1311  */
1312 int ime_event_set_geometry_requested_cb(ime_geometry_requested_cb callback_func, void *user_data);
1313
1314 /**
1315  * @brief Sets @c process_key_event event callback function.
1316  *
1317  * @since_tizen 2.4
1318  *
1319  * @privlevel public
1320  *
1321  * @privilege %http://tizen.org/privilege/ime
1322  *
1323  * @remarks The ime_process_key_event_cb() callback function is called when the key event
1324  * is received from the external keyboard devices or ime_send_key_event() function.
1325  *
1326  * @param[in] callback_func @c process_key_event event callback function
1327  * @param[in] user_data User data to be passed to the callback function
1328  *
1329  * @return 0 on success, otherwise a negative error value
1330  * @retval #IME_ERROR_NONE No error
1331  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1332  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1333  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
1334  *
1335  * @post The ime_run() function should be called to start the IME application's main loop.
1336  *
1337  * @see ime_process_key_event_cb()
1338  * @see ime_run()
1339  *
1340  * @code
1341  static void inputmethod_create_cb(void *user_data);
1342  static void inputmethod_terminate_cb(void *user_data);
1343  static void inputmethod_show_cb(int context_id, ime_context_h context, void *user_data);
1344  static void inputmethod_hide_cb(int context_id, void *user_data);
1345
1346  static bool inputmethod_process_key_event_cb(ime_key_code_e keycode, ime_key_mask_e keymask, void *user_data);
1347  {
1348          if (keymask & IME_KEY_MASK_CONTROL) {
1349                  return false; // e.g., Control+C key event would be forwarded to UI control of the client application
1350          }
1351          if (keymask & IME_KEY_MASK_ALT) {
1352                  return false;
1353          }
1354
1355          if (!(keymask & IME_KEY_MASK_RELEASED)) { // The key is pressed
1356                  if (keycode == IME_KEY_1) {
1357                          ime_update_preedit_string("1"); // Show "1" preedit string
1358                          return true;
1359                  }
1360                  else if (keycode == IME_KEY_2) {
1361                          ime_commit_string("12"); // Input "12" string
1362                          return true;
1363                  }
1364          }
1365
1366          return false;
1367  }
1368
1369  void ime_app_main(int argc, char **argv)
1370  {
1371          ime_callback_s basic_callback = {
1372                  inputmethod_create_cb,
1373                  inputmethod_terminate_cb,
1374                  inputmethod_show_cb,
1375                  inputmethod_hide_cb,
1376          };
1377
1378          ime_event_set_process_key_event_cb(inputmethod_process_key_event_cb, NULL);
1379
1380          ime_run(&basic_callback, NULL);
1381  }
1382  * @endcode
1383  */
1384 int ime_event_set_process_key_event_cb(ime_process_key_event_cb callback_func, void *user_data);
1385
1386 /**
1387  * @brief Sets @c process_key_event_with_keycode callback function to handle the key event with a keycode.
1388  *
1389  * @since_tizen 5.5
1390  *
1391  * @privlevel public
1392  *
1393  * @privilege %http://tizen.org/privilege/ime
1394  *
1395  * @remarks The ime_process_key_event_with_keycode_cb() callback function is called when the key event
1396  * is received from external keyboard devices or ime_send_key_event().
1397  *
1398  * @param[in] callback_func @c process_key_event_with_keycode() event callback function
1399  * @param[in] user_data User data to be passed to the callback function
1400  *
1401  * @return 0 on success, otherwise a negative error value
1402  * @retval #IME_ERROR_NONE No error
1403  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1404  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1405  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
1406  *
1407  * @post The ime_run() function should be called to start the IME application's main loop.
1408  *
1409  * @see ime_process_key_event_with_keycode_cb()
1410  * @see ime_run()
1411  */
1412 int ime_event_set_process_key_event_with_keycode_cb(ime_process_key_event_with_keycode_cb callback_func, void *user_data);
1413
1414 /**
1415  * @brief Sets @c display_language_changed event callback function.
1416  *
1417  * @since_tizen 2.4
1418  *
1419  * @privlevel public
1420  *
1421  * @privilege %http://tizen.org/privilege/ime
1422  *
1423  * @remarks The ime_display_language_changed_cb() callback function is called when the system
1424  * display language is changed.
1425  *
1426  * @param[in] callback_func @c display_language_changed event callback function
1427  * @param[in] user_data User data to be passed to the callback function
1428  *
1429  * @return 0 on success, otherwise a negative error value
1430  * @retval #IME_ERROR_NONE No error
1431  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1432  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1433  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
1434  *
1435  * @post The ime_run() function should be called to start the IME application's main loop.
1436  *
1437  * @see ime_display_language_changed_cb()
1438  * @see ime_run()
1439  */
1440 int ime_event_set_display_language_changed_cb(ime_display_language_changed_cb callback_func, void *user_data);
1441
1442 /**
1443  * @brief Sets @c rotation_degree_changed event callback function.
1444  *
1445  * @since_tizen 2.4
1446  *
1447  * @privlevel public
1448  *
1449  * @privilege %http://tizen.org/privilege/ime
1450  *
1451  * @remarks The ime_rotation_degree_changed_cb() callback function is called when the device
1452  * is rotated.
1453  *
1454  * @param[in] callback_func @c rotation_degree_changed event callback function
1455  * @param[in] user_data User data to be passed to the callback function
1456  *
1457  * @return 0 on success, otherwise a negative error value
1458  * @retval #IME_ERROR_NONE No error
1459  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1460  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1461  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
1462  *
1463  * @post The ime_run() function should be called to start the IME application's main loop.
1464  *
1465  * @see ime_rotation_degree_changed_cb()
1466  * @see ime_run()
1467  */
1468 int ime_event_set_rotation_degree_changed_cb(ime_rotation_degree_changed_cb callback_func, void *user_data);
1469
1470 /**
1471  * @brief Sets @c accessibility_state_changed event callback function.
1472  *
1473  * @since_tizen 2.4
1474  *
1475  * @privlevel public
1476  *
1477  * @privilege %http://tizen.org/privilege/ime
1478  *
1479  * @remarks The ime_accessibility_state_changed_cb() callback function is called when
1480  * Accessibility in Settings application is on or off.
1481  *
1482  * @param[in] callback_func @c accessibility_state_changed event callback function
1483  * @param[in] user_data User data to be passed to the callback function
1484  *
1485  * @return 0 on success, otherwise a negative error value
1486  * @retval #IME_ERROR_NONE No error
1487  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1488  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1489  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
1490  *
1491  * @post The ime_run() function should be called to start the IME application's main loop.
1492  *
1493  * @see ime_accessibility_state_changed_cb()
1494  * @see ime_run()
1495  */
1496 int ime_event_set_accessibility_state_changed_cb(ime_accessibility_state_changed_cb callback_func, void *user_data);
1497
1498 /**
1499  * @brief Sets @c option_window_created event callback function.
1500  *
1501  * @since_tizen 2.4
1502  *
1503  * @privlevel public
1504  *
1505  * @privilege %http://tizen.org/privilege/ime
1506  *
1507  * @remarks The ime_option_window_created_cb() callback function is called to create the option window.
1508  *
1509  * @param[in] callback_func @c option_window_created event callback function
1510  * @param[in] user_data User data to be passed to the callback function
1511  *
1512  * @return 0 on success, otherwise a negative error value
1513  * @retval #IME_ERROR_NONE No error
1514  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1515  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1516  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
1517  *
1518  * @post The ime_run() function should be called to start the IME application's main loop.
1519  *
1520  * @see ime_option_window_created_cb()
1521  * @see ime_run()
1522  */
1523 int ime_event_set_option_window_created_cb(ime_option_window_created_cb callback_func, void *user_data);
1524
1525 /**
1526  * @brief Sets @c option_window_destroyed event callback function.
1527  *
1528  * @since_tizen 2.4
1529  *
1530  * @privlevel public
1531  *
1532  * @privilege %http://tizen.org/privilege/ime
1533  *
1534  * @remarks The ime_option_window_destroyed_cb() callback function is called to destroy the option window.
1535  *
1536  * @param[in] callback_func @c option_window_destroyed event callback function
1537  * @param[in] user_data User data to be passed to the callback function
1538  *
1539  * @return 0 on success, otherwise a negative error value
1540  * @retval #IME_ERROR_NONE No error
1541  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1542  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1543  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
1544  *
1545  * @post The ime_run() function should be called to start the IME application's main loop.
1546  *
1547  * @see ime_option_window_destroyed_cb()
1548  * @see ime_run()
1549  */
1550 int ime_event_set_option_window_destroyed_cb(ime_option_window_destroyed_cb callback_func, void *user_data);
1551
1552 /**
1553  * @brief Sends a key event to the associated text input UI control.
1554  *
1555  * @details This function sends key down or up event with key mask to the client application.
1556  * If @a forward_key is @c true, this key event goes to the edit field directly. And if @a forward_key
1557  * is @c false, the ime_process_key_event_cb() callback function receives the key event before the edit field.
1558  *
1559  * @since_tizen 2.4
1560  *
1561  * @privlevel public
1562  *
1563  * @privilege %http://tizen.org/privilege/ime
1564  *
1565  * @param[in] keycode The key code to be sent
1566  * @param[in] keymask The modifier key mask
1567  * @param[in] forward_key The flag to send the key event directly to the edit field
1568  *
1569  * @return 0 on success, otherwise a negative error value
1570  * @retval #IME_ERROR_NONE No error
1571  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1572  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
1573  *
1574  * @post If @a forward_key is @c false, the ime_process_key_event_cb() callback function can compose the text with the key events.
1575  *
1576  * @see ime_key_code_e
1577  * @see ime_key_mask_e
1578  * @see ime_process_key_event_cb()
1579  */
1580 int ime_send_key_event(ime_key_code_e keycode, ime_key_mask_e keymask, bool forward_key);
1581
1582 /**
1583  * @brief Sends the text to the associated text input UI control.
1584  *
1585  * @since_tizen 2.4
1586  *
1587  * @privlevel public
1588  *
1589  * @privilege %http://tizen.org/privilege/ime
1590  *
1591  * @param[in] str The UTF-8 string to be committed
1592  *
1593  * @return 0 on success, otherwise a negative error value
1594  * @retval #IME_ERROR_NONE No error
1595  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1596  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1597  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
1598  *
1599  * @see ime_show_preedit_string()
1600  * @see ime_hide_preedit_string()
1601  * @see ime_update_preedit_string()
1602  */
1603 int ime_commit_string(const char *str);
1604
1605 /**
1606  * @brief Requests to show preedit string.
1607  *
1608  * @since_tizen 2.4
1609  *
1610  * @privlevel public
1611  *
1612  * @privilege %http://tizen.org/privilege/ime
1613  *
1614  * @return 0 on success, otherwise a negative error value
1615  * @retval #IME_ERROR_NONE No error
1616  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1617  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
1618  *
1619  * @see ime_commit_string()
1620  * @see ime_hide_preedit_string()
1621  * @see ime_update_preedit_string()
1622  */
1623 int ime_show_preedit_string(void);
1624
1625 /**
1626  * @brief Requests to hide preedit string.
1627  *
1628  * @since_tizen 2.4
1629  *
1630  * @privlevel public
1631  *
1632  * @privilege %http://tizen.org/privilege/ime
1633  *
1634  * @return 0 on success, otherwise a negative error value
1635  * @retval #IME_ERROR_NONE No error
1636  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1637  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
1638  *
1639  * @see ime_commit_string()
1640  * @see ime_show_preedit_string()
1641  * @see ime_update_preedit_string()
1642  */
1643 int ime_hide_preedit_string(void);
1644
1645 /**
1646  * @brief Updates a new preedit string.
1647  *
1648  * @since_tizen 2.4
1649  *
1650  * @privlevel public
1651  *
1652  * @privilege %http://tizen.org/privilege/ime
1653  *
1654  * @param[in] str The UTF-8 string to be updated in preedit
1655  * @param[in] attrs The Eina_List which has #ime_preedit_attribute lists; @a str can be composed of multiple
1656  * string attributes: underline, highlight color and reversal color. The @a attrs will be released internally
1657  * on success and it can be NULL if no attributes to set
1658  *
1659  * @return 0 on success, otherwise a negative error value
1660  * @retval #IME_ERROR_NONE No error
1661  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1662  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1663  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
1664  *
1665  * @post This function is supposed to be followed by the ime_show_preedit_string() function.
1666  *
1667  * @see #ime_preedit_attribute
1668  * @see ime_commit_string()
1669  * @see ime_show_preedit_string()
1670  * @see ime_hide_preedit_string()
1671  * @see ime_update_preedit_cursor()
1672  *
1673  * @code
1674  {
1675          int ret;
1676          Eina_List *list = NULL;
1677
1678          ime_preedit_attribute *attr = calloc(1, sizeof(ime_preedit_attribute));
1679          attr->start = 0;
1680          attr->length = 1;
1681          attr->type = IME_ATTR_FONTSTYLE;
1682          attr->value = IME_ATTR_FONTSTYLE_UNDERLINE;
1683          list = eina_list_append(list, attr);
1684
1685          attr = calloc(1, sizeof(ime_preedit_attribute));
1686          attr->start = 1;
1687          attr->length = 1;
1688          attr->type = IME_ATTR_FONTSTYLE;
1689          attr->value = IME_ATTR_FONTSTYLE_HIGHLIGHT;
1690          list = eina_list_append(list, attr);
1691
1692          attr = calloc(1, sizeof(ime_preedit_attribute));
1693          attr->start = 2;
1694          attr->length = 1;
1695          attr->type = IME_ATTR_FONTSTYLE;
1696          attr->value = IME_ATTR_FONTSTYLE_REVERSAL;
1697          list = eina_list_append(list, attr);
1698
1699          ret = ime_update_preedit_string("abcd", list);
1700          if (ret != IME_ERROR_NONE) {
1701                  EINA_LIST_FREE(list, attr)
1702                          free(attr);
1703          }
1704  }
1705  * @endcode
1706  */
1707 int ime_update_preedit_string(const char *str, Eina_List *attrs);
1708
1709 /**
1710  * @brief Updates the cursor position in the preedit string.
1711  *
1712  * @since_tizen 6.5
1713  *
1714  * @privlevel public
1715  *
1716  * @privilege %http://tizen.org/privilege/ime
1717  *
1718  * @param[in] pos The cursor position in the preedit string
1719  *
1720  * @return 0 on success, otherwise a negative error value
1721  * @retval #IME_ERROR_NONE No error
1722  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1723  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
1724  *
1725  * @post This function is supposed to be followed by the ime_update_preedit_string() function.
1726  *
1727  * @see ime_show_preedit_string()
1728  * @see ime_hide_preedit_string()
1729  * @see ime_update_preedit_string()
1730  *
1731  * @code
1732  {
1733          int ret;
1734          Eina_List *list = NULL;
1735
1736          ime_preedit_attribute *attr = calloc(1, sizeof(ime_preedit_attribute));
1737          attr->start = 0;
1738          attr->length = 1;
1739          attr->type = IME_ATTR_FONTSTYLE;
1740          attr->value = IME_ATTR_FONTSTYLE_UNDERLINE;
1741          list = eina_list_append(list, attr);
1742
1743          attr = calloc(1, sizeof(ime_preedit_attribute));
1744          attr->start = 1;
1745          attr->length = 3;
1746          attr->type = IME_ATTR_FONTSTYLE;
1747          attr->value = IME_ATTR_FONTSTYLE_REVERSAL;
1748          list = eina_list_append(list, attr);
1749
1750          ret = ime_update_preedit_string("abcd", list);
1751          if (ret != IME_ERROR_NONE) {
1752                  EINA_LIST_FREE(list, attr)
1753                          free(attr);
1754          }
1755          ret = ime_update_preedit_cursor(1);
1756  }
1757  * @endcode
1758  */
1759 int ime_update_preedit_cursor(unsigned int pos);
1760
1761 /**
1762  * @brief Requests the surrounding text from the position of the cursor, asynchronously.
1763  *
1764  * @since_tizen 2.4
1765  *
1766  * @privlevel public
1767  *
1768  * @privilege %http://tizen.org/privilege/ime
1769  *
1770  * @param[in] maxlen_before The maximum length of string to be retrieved before the cursor; -1 means unlimited
1771  * @param[in] maxlen_after The maximum length of string to be retrieved after the cursor; -1 means unlimited
1772  *
1773  * @return 0 on success, otherwise a negative error value
1774  * @retval #IME_ERROR_NONE No error
1775  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1776  * @retval #IME_ERROR_NO_CALLBACK_FUNCTION Necessary callback function is not set
1777  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
1778  *
1779  * @pre The ime_surrounding_text_updated_cb() callback function MUST be set by ime_event_set_surrounding_text_updated_cb().
1780  *
1781  * @post The requested surrounding text can be received using the ime_surrounding_text_updated_cb() callback function.
1782  *
1783  * @see ime_delete_surrounding_text()
1784  * @see ime_event_set_surrounding_text_updated_cb()
1785  * @see ime_surrounding_text_updated_cb()
1786  */
1787 int ime_request_surrounding_text(int maxlen_before, int maxlen_after);
1788
1789 /**
1790  * @brief Requests to delete surrounding text.
1791  *
1792  * @since_tizen 2.4
1793  *
1794  * @privlevel public
1795  *
1796  * @privilege %http://tizen.org/privilege/ime
1797  *
1798  * @param[in] offset The offset value from the cursor position (in characters not bytes). For example, please use -3 if you want to remove 3 characters in front of current cursor position.
1799  * @param[in] len The length of the text to delete (in characters not bytes)
1800  *
1801  * @return 0 on success, otherwise a negative error value
1802  * @retval #IME_ERROR_NONE No error
1803  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1804  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1805  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
1806  *
1807  * @see ime_request_surrounding_text()
1808  */
1809 int ime_delete_surrounding_text(int offset, int len);
1810
1811 /**
1812  * @brief Gets the surrounding text from the position of the cursor, synchronously.
1813  *
1814  * @since_tizen 3.0
1815  *
1816  * @privlevel public
1817  *
1818  * @privilege %http://tizen.org/privilege/ime
1819  *
1820  * @remarks @a text must be released using free().
1821  *
1822  * @param[in] maxlen_before The maximum length of string to be retrieved before the cursor; -1 means unlimited
1823  * @param[in] maxlen_after The maximum length of string to be retrieved after the cursor; -1 means unlimited
1824  * @param[out] text The surrounding text
1825  * @param[out] cursor_pos The cursor position
1826  *
1827  * @return 0 on success, otherwise a negative error value
1828  * @retval #IME_ERROR_NONE No error
1829  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1830  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1831  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
1832  * @retval #IME_ERROR_OUT_OF_MEMORY Failed to obtain text due to out of memory
1833  *
1834  * @see ime_delete_surrounding_text()
1835  */
1836 int ime_get_surrounding_text(int maxlen_before, int maxlen_after, char **text, int *cursor_pos);
1837
1838 /**
1839  * @brief Requests to set selection.
1840  *
1841  * @since_tizen 3.0
1842  *
1843  * @privlevel public
1844  *
1845  * @privilege %http://tizen.org/privilege/ime
1846  *
1847  * @param[in] start The start cursor position in text (in characters not bytes)
1848  * @param[in] end The end cursor position in text (in characters not bytes)
1849  *
1850  * @return 0 on success, otherwise a negative error value
1851  * @retval #IME_ERROR_NONE No error
1852  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1853  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1854  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
1855  */
1856 int ime_set_selection(int start, int end);
1857
1858 /**
1859  * @brief Gets the selected text synchronously.
1860  *
1861  * @details If multi-line text is selected, the result will contain '\n' for each newline character.
1862  * And if the selected text is empty, the result will be an empty string.
1863  *
1864  * @since_tizen 4.0
1865  *
1866  * @privlevel public
1867  *
1868  * @privilege %http://tizen.org/privilege/ime
1869  *
1870  * @remarks @a text must be released using free().
1871  *
1872  * @param[out] text The selected text
1873  *
1874  * @return 0 on success, otherwise a negative error value
1875  * @retval #IME_ERROR_NONE No error
1876  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1877  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1878  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
1879  */
1880 int ime_get_selected_text(char **text);
1881
1882 /**
1883  * @brief Gets the pointer of input panel main window.
1884  *
1885  * @since_tizen 2.4
1886  *
1887  * @privlevel public
1888  *
1889  * @privilege %http://tizen.org/privilege/ime
1890  *
1891  * @remarks The specific error code can be obtained using the get_last_result() method if this function returns NULL.
1892  * @remarks The returned value should not be released. The returned value is managed by the platform and will be released when terminating this process.
1893  *
1894  * @return The input panel main window object on success, otherwise NULL
1895  *
1896  * @exception #IME_ERROR_NONE Successful
1897  * @exception #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1898  * @exception #IME_ERROR_NOT_RUNNING IME main loop is not started yet
1899  * @exception #IME_ERROR_OPERATION_FAILED Operation failed
1900  *
1901  * @see get_last_result()
1902  * @see ime_create_cb()
1903  * @see ime_terminate_cb()
1904  * @see ime_show_cb()
1905  * @see ime_hide_cb()
1906  */
1907 Evas_Object* ime_get_main_window(void);
1908
1909 /**
1910  * @brief Updates the input panel window's size information.
1911  *
1912  * @since_tizen 2.4
1913  *
1914  * @privlevel public
1915  *
1916  * @privilege %http://tizen.org/privilege/ime
1917  *
1918  * @param[in] portrait_width The width in portrait mode
1919  * @param[in] portrait_height The height in portrait mode
1920  * @param[in] landscape_width The width in landscape mode
1921  * @param[in] landscape_height The height in landscape mode
1922  *
1923  * @return 0 on success, otherwise a negative error value
1924  * @retval #IME_ERROR_NONE No error
1925  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1926  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1927  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
1928  *
1929  * @see ime_create_cb()
1930  */
1931 int ime_set_size(int portrait_width, int portrait_height, int landscape_width, int landscape_height);
1932
1933 /**
1934  * @brief Requests to create an option window from the input panel.
1935  *
1936  * @details The input panel can call this function to open the option window. This
1937  * function calls ime_option_window_created_cb() callback function with
1938  * #IME_OPTION_WINDOW_TYPE_KEYBOARD parameter.
1939  *
1940  * @since_tizen 2.4
1941  *
1942  * @privlevel public
1943  *
1944  * @privilege %http://tizen.org/privilege/ime
1945  *
1946  * @return 0 on success, otherwise a negative error value
1947  * @retval #IME_ERROR_NONE No error
1948  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1949  * @retval #IME_ERROR_NO_CALLBACK_FUNCTION Necessary callback function is not set
1950  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
1951  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
1952  *
1953  * @pre The ime_option_window_created_cb() and ime_option_window_destroyed_cb()
1954  * callback functions MUST be set by ime_event_set_option_window_created_cb() and
1955  * ime_event_set_option_window_destroyed_cb() respectively.
1956  *
1957  * @post This function calls ime_option_window_created_cb() callback function to
1958  * create the option window. And ime_destroy_option_window() function can be called
1959  * to close the option window.
1960  *
1961  * @see ime_event_set_option_window_created_cb()
1962  * @see ime_option_window_created_cb()
1963  * @see ime_destroy_option_window()
1964  */
1965 int ime_create_option_window(void);
1966
1967 /**
1968  * @brief Requests to destroy an option window.
1969  *
1970  * @details The input panel can call this function to close the option window which
1971  * is created from either the input panel or Settings application.
1972  *
1973  * @since_tizen 2.4
1974  *
1975  * @privlevel public
1976  *
1977  * @privilege %http://tizen.org/privilege/ime
1978  *
1979  * @param[in] window The option window to destroy
1980  *
1981  * @return 0 on success, otherwise a negative error value
1982  * @retval #IME_ERROR_NONE No error
1983  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
1984  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
1985  * @retval #IME_ERROR_NO_CALLBACK_FUNCTION Necessary callback function is not set
1986  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
1987  *
1988  * @pre The ime_option_window_created_cb() and ime_option_window_destroyed_cb()
1989  * callback functions MUST be set by ime_event_set_option_window_created_cb() and
1990  * ime_event_set_option_window_destroyed_cb() respectively.
1991  *
1992  * @post This function calls ime_option_window_destroyed_cb() callback function
1993  * to destroy the option window.
1994  *
1995  * @see ime_event_set_option_window_destroyed_cb()
1996  * @see ime_option_window_destroyed_cb()
1997  * @see ime_create_option_window()
1998  */
1999 int ime_destroy_option_window(Evas_Object *window);
2000
2001 /**
2002  * @brief Gets the layout information from the given input context.
2003  *
2004  * @details Each edit field has various attributes for input panel. This function can be
2005  * called to get the layout information in ime_show_cb() callback function.
2006  *
2007  * @since_tizen 2.4
2008  *
2009  * @privlevel public
2010  *
2011  * @privilege %http://tizen.org/privilege/ime
2012  *
2013  * @param[in] context The input context information of an associated text input UI control
2014  * @param[out] layout Layout information
2015  *
2016  * @return 0 on success, otherwise a negative error value
2017  * @retval #IME_ERROR_NONE No error
2018  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2019  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
2020  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
2021  *
2022  * @post Input panel UI should be drawn or operated by this information accordingly.
2023  *
2024  * @see ime_show_cb()
2025  * @see ime_layout_set_cb()
2026  */
2027 int ime_context_get_layout(ime_context_h context, Ecore_IMF_Input_Panel_Layout *layout);
2028
2029 /**
2030  * @brief Gets the layout variation information from the given input context.
2031  *
2032  * @details Each edit field has various attributes for input panel. This function can be
2033  * called to get the layout variation information in ime_show_cb() callback function.
2034  *
2035  * @since_tizen 2.4
2036  *
2037  * @privlevel public
2038  *
2039  * @privilege %http://tizen.org/privilege/ime
2040  *
2041  * @param[in] context The input context information of an associated text input UI control
2042  * @param[out] layout_variation Layout variation information
2043  *
2044  * @return 0 on success, otherwise a negative error value
2045  * @retval #IME_ERROR_NONE No error
2046  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2047  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
2048  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
2049  *
2050  * @post Input panel UI should be drawn or operated by this information accordingly.
2051  *
2052  * @see ime_show_cb()
2053  * @see #ime_layout_variation_e
2054  */
2055 int ime_context_get_layout_variation(ime_context_h context, ime_layout_variation_e *layout_variation);
2056
2057 /**
2058  * @brief Gets the cursor position information from the given input context.
2059  *
2060  * @details Each edit field has various attributes for input panel. This function can be
2061  * called to get the cursor position information in ime_show_cb() callback function.
2062  *
2063  * @since_tizen 2.4
2064  *
2065  * @privlevel public
2066  *
2067  * @privilege %http://tizen.org/privilege/ime
2068  *
2069  * @param[in] context The input context information of an associated text input UI control
2070  * @param[out] cursor_pos Cursor position information
2071  *
2072  * @return 0 on success, otherwise a negative error value
2073  * @retval #IME_ERROR_NONE No error
2074  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2075  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
2076  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
2077  *
2078  * @post Input panel UI should be drawn or operated by this information accordingly.
2079  *
2080  * @see ime_show_cb()
2081  * @see ime_cursor_position_updated_cb()
2082  */
2083 int ime_context_get_cursor_position(ime_context_h context, int *cursor_pos);
2084
2085 /**
2086  * @brief Gets the autocapital type information from the given input context.
2087  *
2088  * @details Each edit field has various attributes for input panel. This function can be
2089  * called to get the autocapital type information in ime_show_cb() callback function.
2090  *
2091  * @since_tizen 2.4
2092  *
2093  * @privlevel public
2094  *
2095  * @privilege %http://tizen.org/privilege/ime
2096  *
2097  * @param[in] context The input context information of an associated text input UI control
2098  * @param[out] autocapital_type Autocapital type information
2099  *
2100  * @return 0 on success, otherwise a negative error value
2101  * @retval #IME_ERROR_NONE No error
2102  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2103  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
2104  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
2105  *
2106  * @post Input panel UI should be drawn or operated by this information accordingly.
2107  *
2108  * @see ime_show_cb()
2109  */
2110 int ime_context_get_autocapital_type(ime_context_h context, Ecore_IMF_Autocapital_Type *autocapital_type);
2111
2112 /**
2113  * @brief Gets the @c Return key label type information from the given input context.
2114  *
2115  * @details Each edit field has various attributes for input panel. This function can be
2116  * called to get the @c Return key label type information in ime_show_cb() callback function.
2117  *
2118  * @since_tizen 2.4
2119  *
2120  * @privlevel public
2121  *
2122  * @privilege %http://tizen.org/privilege/ime
2123  *
2124  * @param[in] context The input context information of an associated text input UI control
2125  * @param[out] return_key_type The @c Return key label type information
2126  *
2127  * @return 0 on success, otherwise a negative error value
2128  * @retval #IME_ERROR_NONE No error
2129  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2130  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
2131  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
2132  *
2133  * @post Input panel UI should be drawn or operated by this information accordingly.
2134  *
2135  * @see ime_show_cb()
2136  * @see ime_return_key_type_set_cb()
2137  */
2138 int ime_context_get_return_key_type(ime_context_h context, Ecore_IMF_Input_Panel_Return_Key_Type *return_key_type);
2139
2140 /**
2141  * @brief Gets the @c Return key state information from the given input context.
2142  *
2143  * @details Each edit field has various attributes for input panel. This function can be
2144  * called to get the @c Return key state information in ime_show_cb() callback function.
2145  *
2146  * @since_tizen 2.4
2147  *
2148  * @privlevel public
2149  *
2150  * @privilege %http://tizen.org/privilege/ime
2151  *
2152  * @param[in] context The input context information of an associated text input UI control
2153  * @param[out] return_key_state The @c Return key state information \n @c true to enable @c Return key
2154  * button, @c false to disable @c Return key button
2155  *
2156  * @return 0 on success, otherwise a negative error value
2157  * @retval #IME_ERROR_NONE No error
2158  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2159  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
2160  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
2161  *
2162  * @post Input panel UI should be drawn or operated by this information accordingly.
2163  *
2164  * @see ime_show_cb()
2165  * @see ime_return_key_state_set_cb()
2166  */
2167 int ime_context_get_return_key_state(ime_context_h context, bool *return_key_state);
2168
2169 /**
2170  * @brief Gets the prediction mode information from the given input context.
2171  *
2172  * @details Each edit field has various attributes for input panel. This function can be
2173  * called to get the prediction mode information in ime_show_cb() callback function.
2174  *
2175  * @since_tizen 2.4
2176  *
2177  * @privlevel public
2178  *
2179  * @privilege %http://tizen.org/privilege/ime
2180  *
2181  * @param[in] context The input context information of an associated text input UI control
2182  * @param[out] prediction_mode Prediction mode information \n @c true to allow the predictive
2183  * text feature if available, @c false to disable the predictive text feature
2184  *
2185  * @return 0 on success, otherwise a negative error value
2186  * @retval #IME_ERROR_NONE No error
2187  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2188  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
2189  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
2190  *
2191  * @post Input panel UI should be drawn or operated by this information accordingly.
2192  *
2193  * @see ime_show_cb()
2194  */
2195 int ime_context_get_prediction_mode(ime_context_h context, bool *prediction_mode);
2196
2197 /**
2198  * @brief Gets the password mode information from the given input context.
2199  *
2200  * @details Each edit field has various attributes for input panel. This function can be
2201  * called to get the password mode information in ime_show_cb() callback function.
2202  *
2203  * @since_tizen 2.4
2204  *
2205  * @privlevel public
2206  *
2207  * @privilege %http://tizen.org/privilege/ime
2208  *
2209  * @remarks If @a password_mode is @c true, the input panel is advised not to support the predictive text.
2210  *
2211  * @param[in] context The input context information of an associated text input UI control
2212  * @param[out] password_mode Password mode information \n @c true to indicate that a password being inputted,
2213  * @c false to indicate non-password edit field.
2214  *
2215  * @return 0 on success, otherwise a negative error value
2216  * @retval #IME_ERROR_NONE No error
2217  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2218  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
2219  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
2220  *
2221  * @post Input panel UI should be drawn or operated by this information accordingly.
2222  *
2223  * @see ime_show_cb()
2224  */
2225 int ime_context_get_password_mode(ime_context_h context, bool *password_mode);
2226
2227 /**
2228  * @brief Gets the input hint information from the given input context.
2229  *
2230  * @details Each edit field has various attributes for input panel. This function can be
2231  * called to get the input hint information in ime_show_cb() callback function.
2232  *
2233  * @since_tizen 2.4
2234  *
2235  * @privlevel public
2236  *
2237  * @privilege %http://tizen.org/privilege/ime
2238  *
2239  * @remarks @a input_hint is a bit-wise value which recommends the input panel provide
2240  * an auto completion and so on if it is capable of supporting such features.
2241  *
2242  * @param[in] context The input context information of an associated text input UI control
2243  * @param[out] input_hint Input hint information
2244  *
2245  * @return 0 on success, otherwise a negative error value
2246  * @retval #IME_ERROR_NONE No error
2247  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2248  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
2249  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
2250  *
2251  * @post Input panel UI should be drawn or operated by this information accordingly.
2252  *
2253  * @see ime_show_cb()
2254  */
2255 int ime_context_get_input_hint(ime_context_h context, Ecore_IMF_Input_Hints *input_hint);
2256
2257 /**
2258  * @brief Gets the text bidirectional information from the given input context.
2259  *
2260  * @details Each edit field has various attributes for input panel. This function can be
2261  * called to get the bidirectional information in ime_show_cb() callback function.
2262  *
2263  * @since_tizen 2.4
2264  *
2265  * @privlevel public
2266  *
2267  * @privilege %http://tizen.org/privilege/ime
2268  *
2269  * @param[in] context The input context information of an associated text input UI control
2270  * @param[out] bidi Text bidirectional information
2271  *
2272  * @return 0 on success, otherwise a negative error value
2273  * @retval #IME_ERROR_NONE No error
2274  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2275  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
2276  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
2277  *
2278  * @post Input panel UI should be drawn or operated by this information accordingly.
2279  *
2280  * @see ime_show_cb()
2281  */
2282 int ime_context_get_bidi_direction(ime_context_h context, Ecore_IMF_BiDi_Direction *bidi);
2283
2284 /**
2285  * @brief Gets the preferred language information from the given input context.
2286  *
2287  * @details Each edit field has various attributes for input panel. This function can be
2288  * called to get the preferred language information in ime_show_cb() callback function.
2289  *
2290  * @since_tizen 2.4
2291  *
2292  * @privlevel public
2293  *
2294  * @privilege %http://tizen.org/privilege/ime
2295  *
2296  * @param[in] context The input context information of an associated text input UI control
2297  * @param[out] language Preferred language information
2298  *
2299  * @return 0 on success, otherwise a negative error value
2300  * @retval #IME_ERROR_NONE No error
2301  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2302  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
2303  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
2304  *
2305  * @post Input panel UI should be drawn or operated by this information accordingly.
2306  *
2307  * @see ime_show_cb()
2308  */
2309 int ime_context_get_language(ime_context_h context, Ecore_IMF_Input_Panel_Lang *language);
2310
2311 /**
2312  * @brief Gets the device name of the key event.
2313  *
2314  * @since_tizen 2.4
2315  *
2316  * @privlevel public
2317  *
2318  * @privilege %http://tizen.org/privilege/ime
2319  *
2320  * @remarks @a dev_name must be released using free().
2321  *
2322  * @param[in] dev_info The device information from the key event
2323  * @param[out] dev_name The name of key input device. This can be an empty string if the device name is not available
2324  *
2325  * @return 0 on success, otherwise a negative error value
2326  * @retval #IME_ERROR_NONE No error
2327  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2328  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
2329  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
2330  *
2331  * @see ime_process_key_event_cb()
2332  * @see ime_device_info_get_class()
2333  * @see ime_device_info_get_subclass()
2334  */
2335 int ime_device_info_get_name(ime_device_info_h dev_info, char **dev_name);
2336
2337 /**
2338  * @brief Gets the device class of the key event.
2339  *
2340  * @since_tizen 2.4
2341  *
2342  * @privlevel public
2343  *
2344  * @privilege %http://tizen.org/privilege/ime
2345  *
2346  * @param[in] dev_info The device information from the key event
2347  * @param[out] dev_class The class of key input device. This can be #ECORE_IMF_DEVICE_CLASS_NONE if the device class is not available
2348  *
2349  * @return 0 on success, otherwise a negative error value
2350  * @retval #IME_ERROR_NONE No error
2351  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2352  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
2353  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
2354  *
2355  * @see ime_process_key_event_cb()
2356  * @see ime_device_info_get_name()
2357  * @see ime_device_info_get_subclass()
2358  */
2359 int ime_device_info_get_class(ime_device_info_h dev_info, Ecore_IMF_Device_Class *dev_class);
2360 /**
2361  * @brief Gets the device subclass of the key event.
2362  *
2363  * @since_tizen 2.4
2364  *
2365  * @privlevel public
2366  *
2367  * @privilege %http://tizen.org/privilege/ime
2368  *
2369  * @param[in] dev_info The device information from the key event
2370  * @param[out] dev_subclass The subclass of key input device. This can be #ECORE_IMF_DEVICE_SUBCLASS_NONE if the device subclass is not available
2371  *
2372  * @return 0 on success, otherwise a negative error value
2373  * @retval #IME_ERROR_NONE No error
2374  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2375  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
2376  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
2377  *
2378  * @see ime_process_key_event_cb()
2379  * @see ime_device_info_get_name()
2380  * @see ime_device_info_get_class()
2381  */
2382 int ime_device_info_get_subclass(ime_device_info_h dev_info, Ecore_IMF_Device_Subclass *dev_subclass);
2383
2384 /**
2385  * @brief Sets prediction hint event callback function.
2386  *
2387  * @since_tizen 4.0
2388  *
2389  * @privlevel public
2390  *
2391  * @privilege %http://tizen.org/privilege/ime
2392  *
2393  * @remarks The ime_prediction_hint_set_cb() callback function is called to set the prediction
2394  * hint string to deliver to the input panel.
2395  *
2396  * @param[in] callback_func The prediction hint event callback function
2397  * @param[in] user_data User data to be passed to the callback function
2398  *
2399  * @return 0 on success, otherwise a negative error value
2400  * @retval #IME_ERROR_NONE No error
2401  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2402  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
2403  *
2404  * @post The ime_run() function should be called to start the IME application's main loop.
2405  *
2406  * @see ime_prediction_hint_set_cb()
2407  * @see ime_run()
2408  */
2409 int ime_event_set_prediction_hint_set_cb(ime_prediction_hint_set_cb callback_func, void *user_data);
2410
2411 /**
2412  * @brief Sets MIME type event callback function.
2413  *
2414  * @since_tizen 4.0
2415  *
2416  * @privlevel public
2417  *
2418  * @privilege %http://tizen.org/privilege/ime
2419  *
2420  * @remarks The ime_mime_type_set_request_cb() callback function is called when an associated text input
2421  * UI control requests the text entry to set the MIME type.
2422  *
2423  * @param[in] callback_func MIME type event callback function
2424  * @param[in] user_data User data to be passed to the callback function
2425  *
2426  * @return 0 on success, otherwise a negative error value
2427  * @retval #IME_ERROR_NONE No error
2428  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2429  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
2430  *
2431  * @post The ime_run() function should be called to start the IME application's main loop.
2432  *
2433  * @see ime_mime_type_set_request_cb()
2434  * @see ime_run()
2435  */
2436 int ime_event_set_mime_type_set_request_cb(ime_mime_type_set_request_cb callback_func, void *user_data);
2437
2438 /**
2439  * @brief Sends a private command to the associated text input UI control.
2440  *
2441  * @details This can be used by IME to deliver specific data to an application.
2442  * The data format MUST be negotiated by both application and IME.
2443  *
2444  * @since_tizen 4.0
2445  *
2446  * @privlevel public
2447  *
2448  * @privilege %http://tizen.org/privilege/ime
2449  *
2450  * @param[in] command The UTF-8 string to be sent
2451  *
2452  * @return 0 on success, otherwise a negative error value
2453  * @retval #IME_ERROR_NONE No error
2454  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2455  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
2456  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
2457  */
2458 int ime_send_private_command(const char *command);
2459
2460 /**
2461  * @brief Commits contents such as image to the associated text input UI control.
2462  *
2463  * @since_tizen 4.0
2464  *
2465  * @privlevel public
2466  *
2467  * @privilege %http://tizen.org/privilege/ime
2468  *
2469  * @param[in] content The content URI to be sent
2470  * @param[in] description The content description
2471  * @param[in] mime_type The MIME type received from the ime_mime_type_set_request_cb()
2472  *
2473  * @return 0 on success, otherwise a negative error value
2474  * @retval #IME_ERROR_NONE No error
2475  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2476  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
2477  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
2478  *
2479  * @see ime_mime_type_set_request_cb()
2480  * @see ime_event_set_mime_type_set_request_cb()
2481  */
2482 int ime_commit_content(const char *content, const char *description, const char *mime_type);
2483
2484 /**
2485  * @brief Sets the floating mode or not.
2486  *
2487  * @since_tizen 4.0
2488  *
2489  * @privlevel public
2490  *
2491  * @privilege %http://tizen.org/privilege/ime
2492  *
2493  * @param[in] floating_mode @c true - floating mode on, @c false - floating mode off
2494  *
2495  * @return 0 on success, otherwise a negative error value
2496  * @retval #IME_ERROR_NONE No error
2497  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2498  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
2499  *
2500  * @see ime_set_floating_drag_start()
2501  * @see ime_set_floating_drag_end()
2502  */
2503 int ime_set_floating_mode(bool floating_mode);
2504
2505 /**
2506  * @brief Allows the floating input panel window to move along with the mouse pointer when the mouse is pressed.
2507  *
2508  * @since_tizen 4.0
2509  *
2510  * @privlevel public
2511  *
2512  * @privilege %http://tizen.org/privilege/ime
2513  *
2514  * @remarks This function can be used in floating mode. If the floating mode is deactivated, calling this function has no effect.
2515  *
2516  * @return 0 on success, otherwise a negative error value
2517  * @retval #IME_ERROR_NONE No error
2518  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2519  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
2520  *
2521  * @pre The floating mode was turned on with ime_set_floating_mode().
2522  *
2523  * @see ime_set_floating_mode()
2524  * @see ime_set_floating_drag_end()
2525  */
2526 int ime_set_floating_drag_start(void);
2527
2528 /**
2529  * @brief Disallows the movement of the floating input panel window with the mouse pointer when the mouse is pressed.
2530  *
2531  * @details This function must be called after invoking ime_set_floating_drag_start(). Otherwise the call is ignored.
2532  *
2533  * @since_tizen 4.0
2534  *
2535  * @privlevel public
2536  *
2537  * @privilege %http://tizen.org/privilege/ime
2538  *
2539  * @remarks This function can be used in floating mode. If the floating mode is deactivated, calling this function has no effect.
2540  *
2541  * @return 0 on success, otherwise a negative error value
2542  * @retval #IME_ERROR_NONE No error
2543  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2544  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
2545  *
2546  * @pre The floating mode was turned on with ime_set_floating_mode().
2547  * @pre ime_set_floating_drag_start() was called before.
2548  *
2549  * @see ime_set_floating_mode()
2550  * @see ime_set_floating_drag_start()
2551  */
2552 int ime_set_floating_drag_end(void);
2553
2554 /**
2555  * @brief Sets a callback function to give a hint about predicted words.
2556  *
2557  * @since_tizen 5.0
2558  *
2559  * @privlevel public
2560  *
2561  * @privilege %http://tizen.org/privilege/ime
2562  *
2563  * @remarks The ime_prediction_hint_data_set_cb() callback function is called to provide the prediction
2564  * hint key and value which can be delivered to the input panel.
2565  *
2566  * @param[in] callback_func The callback function to give hints
2567  * @param[in] user_data User data to be passed to the callback function
2568  *
2569  * @return 0 on success, otherwise a negative error value
2570  * @retval #IME_ERROR_NONE No error
2571  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2572  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
2573  *
2574  * @post The ime_run() function should be called to start the IME application's main loop.
2575  *
2576  * @see ime_prediction_hint_data_set_cb()
2577  * @see ime_run()
2578  */
2579 int ime_event_set_prediction_hint_data_set_cb(ime_prediction_hint_data_set_cb callback_func, void *user_data);
2580
2581 /**
2582  * @brief Sends the request to hide IME.
2583  *
2584  * @since_tizen 5.0
2585  *
2586  * @privlevel public
2587  *
2588  * @privilege %http://tizen.org/privilege/ime
2589  *
2590  * @return 0 on success, otherwise a negative error value
2591  * @retval #IME_ERROR_NONE No error
2592  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2593  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
2594  */
2595 int ime_request_hide(void);
2596
2597 /**
2598  * @brief Updates the state of input panel event.
2599  *
2600  * @since_tizen 5.5
2601  *
2602  * @privlevel public
2603  *
2604  * @privilege %http://tizen.org/privilege/ime
2605  *
2606  * @param[in] type The input panel event type
2607  * @param[in] value The value of event type
2608  *
2609  * @return 0 on success, otherwise a negative error value
2610  * @retval #IME_ERROR_NONE No error
2611  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2612  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
2613  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
2614  *
2615  * @see #ime_event_type_e
2616  */
2617 int ime_update_input_panel_event(ime_event_type_e type, unsigned int value);
2618
2619 /**
2620  * @brief Enables whether candidate strings show or not.
2621  *
2622  * @since_tizen 5.5
2623  *
2624  * @privlevel public
2625  *
2626  * @privilege %http://tizen.org/privilege/ime
2627  *
2628  * @param[in] visible @c true if candidate strings show, @c false otherwise.
2629  *
2630  * @return 0 on success, otherwise a negative error value
2631  * @retval #IME_ERROR_NONE No error
2632  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2633  * @retval #IME_ERROR_NOT_RUNNING IME main loop is not started yet
2634  */
2635 int ime_set_candidate_visibility_state(bool visible);
2636
2637 /**
2638  * @brief Sets @c input_hint_set event callback function.
2639  *
2640  * @since_tizen 6.5
2641  *
2642  * @privlevel public
2643  *
2644  * @privilege %http://tizen.org/privilege/ime
2645  *
2646  * @remarks The ime_input_hint_set_cb() callback function is called to set the input hint
2647  * to deliver to the input panel.
2648  *
2649  * @param[in] callback_func @c input_hint_set event callback function
2650  * @param[in] user_data User data to be passed to the callback function
2651  *
2652  * @return 0 on success, otherwise a negative error value
2653  * @retval #IME_ERROR_NONE No error
2654  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function.
2655  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
2656  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
2657  *
2658  * @post The ime_run() function should be called to start the IME application's main loop.
2659  *
2660  * @see ime_input_hint_set_cb()
2661  * @see ime_run()
2662  */
2663 int ime_event_set_input_hint_set_cb(ime_input_hint_set_cb callback_func, void *user_data);
2664
2665 /**
2666  * @brief Unsets @c input_hint_set event callback function.
2667  *
2668  * @since_tizen 6.5
2669  *
2670  * @privlevel public
2671  *
2672  * @privilege %http://tizen.org/privilege/ime
2673  *
2674  * @remarks The ime_input_hint_set_cb() callback function is called to set the input hint
2675  * to deliver to the input panel.
2676  *
2677  * @return 0 on success, otherwise a negative error value
2678  * @retval #IME_ERROR_NONE No error
2679  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
2680  *
2681  * @see ime_input_hint_set_cb()
2682  * @see ime_event_set_input_hint_set_cb()
2683  */
2684 int ime_event_unset_input_hint_set_cb(void);
2685
2686 /**
2687  * @}
2688  */
2689
2690 #ifdef __cplusplus
2691 }
2692 #endif
2693
2694 #endif /* __TIZEN_UIX_INPUTMETHOD_H__ */
2695