include/inputmethod.h

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