remote_input/include/remote_input.h

   1 /*
   2  * Copyright (c) 2019 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_REMOTE_INPUT_H__
  18 #define __TIZEN_UIX_REMOTE_INPUT_H__
  19
  20
  21 /**
  22  * @file remote_input.h
  23  * @brief This file contains remote input APIs and related enumeration.
  24  */
  25
  26 #include <tizen.h>
  27 #include <Ecore_IMF.h>
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 /**
  34  * @addtogroup CAPI_UIX_INPUTMETHOD_MODULE
  35  * @{
  36  */
  37
  38
  39 /**
  40  * @platform
  41  * @brief Enumeration for remote input function error.
  42  * @since_tizen 5.5
  43  */
  44 typedef enum {
  45     REMOTE_INPUT_ERROR_NONE = TIZEN_ERROR_NONE,                     /**< Successful */
  46     REMOTE_INPUT_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  47     REMOTE_INPUT_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */
  48     REMOTE_INPUT_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY,         /**< Out of Memory */
  49     REMOTE_INPUT_OPERATION_FAILED,                                  /**< Operation failed */
  50 } remote_input_error_e;
  51
  52 /**
  53  * @platform
  54  * @brief Enumeration for key types.
  55  * @since_tizen 5.5
  56  * @see remote_input_send_key_event()
  57  */
  58 typedef enum {
  59     REMOTE_INPUT_KEY_ENTER = 0, /**< Enter key */
  60     REMOTE_INPUT_KEY_SPACE,     /**< Space key */
  61     REMOTE_INPUT_KEY_BACKSPACE, /**< Backspace key */
  62     REMOTE_INPUT_KEY_ESC,       /**< Escape key */
  63     REMOTE_INPUT_KEY_UP,        /**< Up key */
  64     REMOTE_INPUT_KEY_DOWN,      /**< Down key */
  65     REMOTE_INPUT_KEY_LEFT,      /**< LEFT key */
  66     REMOTE_INPUT_KEY_RIGHT,     /**< Right key */
  67     REMOTE_INPUT_KEY_PAGE_UP,   /**< Page up key */
  68     REMOTE_INPUT_KEY_PAGE_DOWN, /**< Page down key */
  69     REMOTE_INPUT_KEY_SELECT,    /**< Select key */
  70     REMOTE_INPUT_KEY_CANCEL,    /**< Cancel key */
  71 } remote_input_key_type_e;
  72
  73 /**
  74  * @platform
  75  * @brief Enumeration for input resources.
  76  * @since_tizen 5.5
  77  * @see remote_input_resource_changed_cb()
  78  */
  79 typedef enum {
  80     REMOTE_INPUT_RESOURCE_LOCAL = 0, /**< Input event from IME, H/W keyboard */
  81     REMOTE_INPUT_RESOURCE_REMOTE,    /**< Input event from remote input API */
  82 } remote_input_resource_e;
  83
  84 /**
  85  * @platform
  86  * @brief Handle of the remote input.
  87  * @since_tizen 5.5
  88  */
  89 typedef struct remote_input_s *remote_input_h;
  90
  91 /**
  92  * @platform
  93  * @brief Called when an associated text field has focus.
  94  * @since_tizen 5.5
  95  * @param[in] user_data User data to be passed to the callback function
  96  * @pre The callback can be registered using remote_input_focus_in_callback_set() function.
  97  * @see remote_input_focus_in_callback_set()
  98  * @see remote_input_focus_in_callback_unset()
  99  */
 100 typedef void (*remote_input_focus_in_cb)(void *user_data);
 101
 102 /**
 103  * @platform
 104  * @brief Called when an associated text field loses focus.
 105  * @since_tizen 5.5
 106  * @param[in] user_data User data to be passed to the callback function
 107  * @pre The callback can be registered using remote_input_focus_out_callback_set() function.
 108  * @see remote_input_focus_out_callback_set()
 109  * @see remote_input_focus_out_callback_unset()
 110  */
 111 typedef void (*remote_input_focus_out_cb)(void *user_data);
 112
 113 /**
 114  * @platform
 115  * @brief Called when an associated text field requests the input panel to set its attributes.
 116  * @since_tizen 5.5
 117  * @remarks This callback will be called after remote_input_focus_in_cb().
 118  *          It can be called again when the associated text field's attributes are changed.
 119  *          Remote IME application should configure its input panel with various attributes.
 120  * @param[in] user_data User data to be passed to the callback function
 121  * @pre The callback can be registered using remote_input_metadata_updated_callback_set() function.
 122  * @see remote_input_metadata_updated_callback_set()
 123  * @see remote_input_metadata_updated_callback_unset()
 124  * @see remote_input_get_input_hint()
 125  * @see remote_input_get_layout()
 126  * @see remote_input_get_layout_variation()
 127  * @see remote_input_get_autocapital_type()
 128  * @see remote_input_get_return_key_state()
 129  * @see remote_input_get_return_key_type()
 130  */
 131 typedef void (*remote_input_metadata_updated_cb)(void *user_data);
 132
 133 /**
 134  * @platform
 135  * @brief Called when an associated text field responds to a request with the surrounding text.
 136  * @since_tizen 5.5
 137  * @remarks This callback will be called after remote_input_metadata_updated_cb().
 138  *          It can be called again when the text or the cursor position in the associated text field is changed.
 139  *          @a text can be used only in the callback. To use outside, make a copy.
 140  * @param[in] text The UTF-8 string requested
 141  * @param[in] cursor_pos The cursor position
 142  * @param[in] user_data User data to be passed to the callback function
 143  * @pre The callback can be registered using remote_input_text_updated_callback_set() function.
 144  * @see remote_input_text_updated_callback_set()
 145  * @see remote_input_text_updated_callback_unset()
 146  */
 147 typedef void (*remote_input_text_updated_cb)(const char *text, int cursor_pos, void *user_data);
 148
 149 /**
 150  * @platform
 151  * @brief Called when the input resource is changed.
 152  * @since_tizen 5.5
 153  * @param[in] resource The input resource
 154  * @param[in] user_data User data to be passed to the callback function
 155  * @pre The callback can be registered using remote_input_resource_changed_callback_set() function.
 156  * @see remote_input_resource_changed_callback_set()
 157  * @see remote_input_resource_changed_callback_unset()
 158  */
 159 typedef void (*remote_input_resource_changed_cb)(remote_input_resource_e resource, void *user_data);
 160
 161 /**
 162  * @platform
 163  * @brief Creates a remote input handle.
 164  * @since_tizen 5.5
 165  * @privlevel platform
 166  * @privilege %http://tizen.org/privilege/internal/default/platform
 167  * @remarks If the function succeeds, @a remote_handle must be released with remote_input_destroy().
 168  * @param[out] remote_handle The remote input handle
 169  * @return 0 on success, otherwise a negative error value
 170  * @retval #REMOTE_INPUT_ERROR_NONE Successful
 171  * @retval #REMOTE_INPUT_INVALID_PARAMETER Invalid parameter
 172  * @retval #REMOTE_INPUT_PERMISSION_DENIED Permission denied
 173  * @retval #REMOTE_INPUT_OUT_OF_MEMORY Out of memory
 174  * @retval #REMOTE_INPUT_OPERATION_FAILED Operation failure
 175  * @see remote_input_destroy()
 176  */
 177 int remote_input_create(remote_input_h *remote_handle);
 178
 179 /**
 180  * @platform
 181  * @brief Destroys a remote input handle.
 182  * @since_tizen 5.5
 183  * @param[in] remote_handle The remote input handle
 184  * @return 0 on success, otherwise a negative error value
 185  * @retval #REMOTE_INPUT_ERROR_NONE Successful
 186  * @retval #REMOTE_INPUT_INVALID_PARAMETER Invalid parameter
 187  * @retval #REMOTE_INPUT_OPERATION_FAILED Operation failed
 188  * @see remote_input_create()
 189  */
 190 int remote_input_destroy(remote_input_h remote_handle);
 191
 192 /**
 193  * @platform
 194  * @brief Sets a callback function to be called when an associated text field has focus.
 195  * @since_tizen 5.5
 196  * @param[in] remote_handle The remote input handle
 197  * @param[in] callback The callback function to register
 198  * @param[in] user_data User data to be passed to the callback function
 199  * @return 0 on success, otherwise a negative error value
 200  * @retval #REMOTE_INPUT_ERROR_NONE Successful
 201  * @retval #REMOTE_INPUT_INVALID_PARAMETER Invalid parameter
 202  * @see remote_input_focus_in_callback_unset()
 203  */
 204 int remote_input_focus_in_callback_set(remote_input_h remote_handle, remote_input_focus_in_cb callback, void *user_data);
 205
 206 /**
 207  * @platform
 208  * @brief Unsets the callback function.
 209  * @since_tizen 5.5
 210  * @param[in] remote_handle The remote input handle
 211  * @return 0 on success, otherwise a negative error value
 212  * @retval #REMOTE_INPUT_ERROR_NONE Successful
 213  * @retval #REMOTE_INPUT_INVALID_PARAMETER Invalid parameter
 214  * @see remote_input_focus_in_callback_set()
 215  */
 216 int remote_input_focus_in_callback_unset(remote_input_h remote_handle);
 217
 218 /**
 219  * @platform
 220  * @brief Sets a callback function to be called when an associated text field loses focus.
 221  * @since_tizen 5.5
 222  * @param[in] remote_handle The remote input handle
 223  * @param[in] callback The callback function to register
 224  * @param[in] user_data User data to be passed to the callback function
 225  * @return 0 on success, otherwise a negative error value
 226  * @retval #REMOTE_INPUT_ERROR_NONE Successful
 227  * @retval #REMOTE_INPUT_INVALID_PARAMETER Invalid parameter
 228  * @see remote_input_focus_out_callback_unset()
 229  */
 230 int remote_input_focus_out_callback_set(remote_input_h remote_handle, remote_input_focus_out_cb callback, void *user_data);
 231
 232 /**
 233  * @platform
 234  * @brief Unsets the callback function.
 235  * @since_tizen 5.5
 236  * @param[in] remote_handle The remote input handle
 237  * @return 0 on success, otherwise a negative error value
 238  * @retval #REMOTE_INPUT_ERROR_NONE Successful
 239  * @retval #REMOTE_INPUT_INVALID_PARAMETER Invalid parameter
 240  * @see remote_input_focus_out_callback_set()
 241  */
 242 int remote_input_focus_out_callback_unset(remote_input_h remote_handle);
 243
 244 /**
 245  * @platform
 246  * @brief Sets a callback function to be called when an associated text field requests the input panel to set its attributes.
 247  * @since_tizen 5.5
 248  * @param[in] remote_handle The remote input handle
 249  * @param[in] callback The callback function to register
 250  * @param[in] user_data User data to be passed to the callback function
 251  * @return 0 on success, otherwise a negative error value
 252  * @retval #REMOTE_INPUT_ERROR_NONE Successful
 253  * @retval #REMOTE_INPUT_INVALID_PARAMETER Invalid parameter
 254  * @see remote_input_metadata_updated_callback_unset()
 255  */
 256 int remote_input_metadata_updated_callback_set(remote_input_h remote_handle, remote_input_metadata_updated_cb callback, void *user_data);
 257
 258 /**
 259  * @platform
 260  * @brief Unsets the callback function.
 261  * @since_tizen 5.5
 262  * @param[in] remote_handle The remote input handle
 263  * @return 0 on success, otherwise a negative error value
 264  * @retval #REMOTE_INPUT_ERROR_NONE Successful
 265  * @retval #REMOTE_INPUT_INVALID_PARAMETER Invalid parameter
 266  * @see remote_input_metadata_updated_callback_set()
 267  */
 268 int remote_input_metadata_updated_callback_unset(remote_input_h remote_handle);
 269
 270 /**
 271  * @platform
 272  * @brief Sets a callback function to be called when an associated text field responds to a request with the surrounding text.
 273  * @since_tizen 5.5
 274  * @param[in] remote_handle The remote input handle
 275  * @param[in] callback The callback function to register
 276  * @param[in] user_data User data to be passed to the callback function
 277  * @return 0 on success, otherwise a negative error value
 278  * @retval #REMOTE_INPUT_ERROR_NONE Successful
 279  * @retval #REMOTE_INPUT_INVALID_PARAMETER Invalid parameter
 280  * @see remote_input_text_updated_callback_unset()
 281  */
 282 int remote_input_text_updated_callback_set(remote_input_h remote_handle, remote_input_text_updated_cb callback, void *user_data);
 283
 284 /**
 285  * @platform
 286  * @brief Unsets the callback function.
 287  * @since_tizen 5.5
 288  * @param[in] remote_handle The remote input handle
 289  * @return 0 on success, otherwise a negative error value
 290  * @retval #REMOTE_INPUT_ERROR_NONE Successful
 291  * @retval #REMOTE_INPUT_INVALID_PARAMETER Invalid parameter
 292  * @see remote_input_text_updated_callback_set()
 293  */
 294 int remote_input_text_updated_callback_unset(remote_input_h remote_handle);
 295
 296 /**
 297  * @platform
 298  * @brief Sets a callback function to be called when the input resource is changed.
 299  * @since_tizen 5.5
 300  * @param[in] remote_handle The remote input handle
 301  * @param[in] callback The callback function to register
 302  * @param[in] user_data User data to be passed to the callback function
 303  * @return 0 on success, otherwise a negative error value
 304  * @retval #REMOTE_INPUT_ERROR_NONE Successful
 305  * @retval #REMOTE_INPUT_INVALID_PARAMETER Invalid parameter
 306  * @see remote_input_resource_changed_callback_unset()
 307  */
 308 int remote_input_resource_changed_callback_set(remote_input_h remote_handle, remote_input_resource_changed_cb callback, void *user_data);
 309
 310 /**
 311  * @platform
 312  * @brief Unsets the callback function.
 313  * @since_tizen 5.5
 314  * @param[in] remote_handle The remote input handle
 315  * @return 0 on success, otherwise a negative error value
 316  * @retval #REMOTE_INPUT_ERROR_NONE Successful
 317  * @retval #REMOTE_INPUT_INVALID_PARAMETER Invalid parameter
 318  * @see remote_input_resource_changed_callback_set()
 319  */
 320 int remote_input_resource_changed_callback_unset(remote_input_h remote_handle);
 321
 322 /**
 323  * @platform
 324  * @brief Gets the input hint information.
 325  * @details Each edit field has various attributes for input panel.
 326  *          This function can be called to get the input hint information in remote_input_metadata_updated_cb() callback function.
 327  * @since_tizen 5.5
 328  * @remarks @a input_hint is a bit-wise value which recommends the input panel provide an auto completion and so on
 329  *          if it is capable of supporting such features.
 330  * @param[in] remote_handle The remote input handle
 331  * @param[out] input_hint Input hint information
 332  * @return 0 on success, otherwise a negative error value
 333  * @retval #REMOTE_INPUT_ERROR_NONE Successful
 334  * @retval #REMOTE_INPUT_INVALID_PARAMETER Invalid parameter
 335  * @post Remote input panel UI should be drawn or operated by this information accordingly.
 336  * @see remote_input_metadata_updated_cb()
 337  */
 338 int remote_input_get_input_hint(remote_input_h remote_handle, Ecore_IMF_Input_Hints *input_hint);
 339
 340 /**
 341  * @platform
 342  * @brief Gets the layout information.
 343  * @details Each edit field has various attributes for input panel.
 344  *          This function can be called to get the layout information in remote_input_metadata_updated_cb() callback function.
 345  * @since_tizen 5.5
 346  * @param[in] remote_handle The remote input handle
 347  * @param[out] layout Layout information
 348  * @return 0 on success, otherwise a negative error value
 349  * @retval #REMOTE_INPUT_ERROR_NONE Successful
 350  * @retval #REMOTE_INPUT_INVALID_PARAMETER Invalid parameter
 351  * @post Remote input panel UI should be drawn or operated by this information accordingly.
 352  * @see remote_input_metadata_updated_cb()
 353  */
 354 int remote_input_get_layout(remote_input_h remote_handle, Ecore_IMF_Input_Panel_Layout *layout);
 355
 356 /**
 357  * @platform
 358  * @brief Gets the layout variation information.
 359  * @details Each edit field has various attributes for input panel.
 360  *          This function can be called to get the layout variation information in remote_input_metadata_updated_cb() callback function.
 361  * @since_tizen 5.5
 362  * @param[in] remote_handle The remote input handle
 363  * @param[out] variation The layout variation
 364  * @return 0 on success, otherwise a negative error value
 365  * @retval #REMOTE_INPUT_ERROR_NONE Successful
 366  * @retval #REMOTE_INPUT_INVALID_PARAMETER Invalid parameter
 367  * @post Remote input panel UI should be drawn or operated by this information accordingly.
 368  * @see remote_input_metadata_updated_cb()
 369  */
 370 int remote_input_get_layout_variation(remote_input_h remote_handle, int *variation);
 371
 372 /**
 373  * @platform
 374  * @brief Gets the autocapital type information.
 375  * @details Each edit field has various attributes for input panel.
 376  *          This function can be called to get the autocapital type information in remote_input_metadata_updated_cb() callback function.
 377  * @since_tizen 5.5
 378  * @param[in] remote_handle The remote input handle
 379  * @param[out] autocapital_type autocapital_type Autocapital type information
 380  * @return 0 on success, otherwise a negative error value
 381  * @retval #REMOTE_INPUT_ERROR_NONE Successful
 382  * @retval #REMOTE_INPUT_INVALID_PARAMETER Invalid parameter
 383  * @post Remote input panel UI should be drawn or operated by this information accordingly.
 384  * @see remote_input_metadata_updated_cb()
 385  */
 386 int remote_input_get_autocapital_type(remote_input_h remote_handle, Ecore_IMF_Autocapital_Type *autocapital_type);
 387
 388 /**
 389  * @platform
 390  * @brief Gets the return key state information.
 391  * @details Each edit field has various attributes for input panel.
 392  *          This function can be called to get the return key state information in remote_input_metadata_updated_cb() callback function.
 393  * @since_tizen 5.5
 394  * @param[in] remote_handle The remote input handle
 395  * @param[out] return_key_state The return key state information \n @c true to enable return key button, @c false to disable return key button
 396  * @return 0 on success, otherwise a negative error value
 397  * @retval #REMOTE_INPUT_ERROR_NONE Successful
 398  * @retval #REMOTE_INPUT_INVALID_PARAMETER Invalid parameter
 399  * @post Remote input panel UI should be drawn or operated by this information accordingly.
 400  * @see remote_input_metadata_updated_cb()
 401  */
 402 int remote_input_get_return_key_state(remote_input_h remote_handle, bool *return_key_state);
 403
 404 /**
 405  * @platform
 406  * @brief Gets the return key label type information.
 407  * @details Each edit field has various attributes for input panel.
 408  *          This function can be called to get the return key label type information in remote_input_metadata_updated_cb() callback function.
 409  * @since_tizen 5.5
 410  * @param[in] remote_handle The remote input handle
 411  * @param[out] return_key_type The return key label type information
 412  * @return 0 on success, otherwise a negative error value
 413  * @retval #REMOTE_INPUT_ERROR_NONE Successful
 414  * @retval #REMOTE_INPUT_INVALID_PARAMETER Invalid parameter
 415  * @post Remote input panel UI should be drawn or operated by this information accordingly.
 416  * @see remote_input_metadata_updated_cb()
 417  */
 418 int remote_input_get_return_key_type(remote_input_h remote_handle, Ecore_IMF_Input_Panel_Return_Key_Type *return_key_type);
 419
 420 /**
 421  * @platform
 422  * @brief Sends a key event to the associated text field.
 423  * @since_tizen 5.5
 424  * @remarks This function must be used if an associated text field has focus.
 425  *          Otherwise, #REMOTE_INPUT_OPERATION_FAILED will be returned.
 426  * @param[in] remote_handle The remote input handle
 427  * @param[in] key The key type
 428  * @return 0 on success, otherwise a negative error value
 429  * @retval #REMOTE_INPUT_ERROR_NONE Successful
 430  * @retval #REMOTE_INPUT_INVALID_PARAMETER Invalid parameter
 431  * @retval #REMOTE_INPUT_OPERATION_FAILED Operation failure
 432  */
 433 int remote_input_send_key_event(remote_input_h remote_handle, remote_input_key_type_e key);
 434
 435 /**
 436  * @platform
 437  * @brief Sends a commit string to the associated text field.
 438  * @since_tizen 5.5
 439  * @remarks This function must be used if an associated text field has focus.
 440  *          Otherwise, #REMOTE_INPUT_OPERATION_FAILED will be returned.
 441  * @param[in] remote_handle The remote input handle
 442  * @param[in] text The UTF-8 string to be committed
 443  * @return 0 on success, otherwise a negative error value
 444  * @retval #REMOTE_INPUT_ERROR_NONE Successful
 445  * @retval #REMOTE_INPUT_INVALID_PARAMETER Invalid parameter
 446  * @retval #REMOTE_INPUT_OPERATION_FAILED Operation failure
 447  */
 448 int remote_input_send_commit_string(remote_input_h remote_handle, const char *text);
 449
 450 /**
 451  * @platform
 452  * @brief Updates a preedit string to the associated text field.
 453  * @since_tizen 5.5
 454  * @remarks This function must be used if an associated text field has focus.
 455  *          Otherwise, #REMOTE_INPUT_OPERATION_FAILED will be returned.
 456  * @param[in] remote_handle The remote input handle
 457  * @param[in] text The UTF-8 string to be committed
 458  * @param[in] cursor_pos The cursor position; -1 means at the end of line
 459  * @return 0 on success, otherwise a negative error value
 460  * @retval #REMOTE_INPUT_ERROR_NONE Successful
 461  * @retval #REMOTE_INPUT_INVALID_PARAMETER Invalid parameter
 462  * @retval #REMOTE_INPUT_OPERATION_FAILED Operation failure
 463  */
 464 int remote_input_update_preedit_string(remote_input_h remote_handle, const char *text, int cursor_pos);
 465
 466 /**
 467  * @platform
 468  * @brief Requests to delete surrounding text.
 469  * @since_tizen 5.5
 470  * @remarks This function must be used if an associated text field has focus.
 471  *          Otherwise, #REMOTE_INPUT_OPERATION_FAILED will be returned.
 472  * @param[in] remote_handle The remote input handle
 473  * @param[in] offset The offset value from the cursor position
 474  * @param[in] len The length of the text to delete
 475  * @return 0 on success, otherwise a negative error value
 476  * @retval #REMOTE_INPUT_ERROR_NONE Successful
 477  * @retval #REMOTE_INPUT_INVALID_PARAMETER Invalid parameter
 478  * @retval #REMOTE_INPUT_OPERATION_FAILED Operation failure
 479  */
 480 int remote_input_delete_surrounding_text(remote_input_h remote_handle, int offset, int len);
 481
 482
 483 /**
 484  * @}
 485  */
 486
 487 #ifdef __cplusplus
 488 }
 489 #endif
 490
 491 #endif /* __TIZEN_UIX_REMOTE_INPUT_H__ */
 492