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