ism/src/isf_control.h

   1 /*
   2  * ISF(Input Service Framework)
   3  *
   4  * ISF is based on SCIM 1.4.7 and extended for supporting more mobile fitable.
   5  * Copyright (c) 2012-2015 Samsung Electronics Co., Ltd.
   6  *
   7  * Contact: Haifeng Deng <haifeng.deng@samsung.com>, Hengliang Luo <hl.luo@samsung.com>
   8  *
   9  * This library is free software; you can redistribute it and/or modify it under
  10  * the terms of the GNU Lesser General Public License as published by the
  11  * Free Software Foundation; either version 2.1 of the License, or (at your option)
  12  * any later version.
  13  *
  14  * This library is distributed in the hope that it will be useful, but WITHOUT ANY
  15  * WARRANTY; without even the implied warranty of MERCHANTABILITY or
  16  * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
  17  * License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public License
  20  * along with this library; if not, write to the Free Software Foundation, Inc., 51
  21  * Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  22  *
  23  */
  24
  25 #ifndef __ISF_CONTROL_H
  26 #define __ISF_CONTROL_H
  27
  28 #include <scim_visibility.h>
  29
  30 #ifdef __cplusplus
  31 extern "C" {
  32 #endif /* __cplusplus */
  33
  34 /////////////////////////////////////////////////////////////////////////////
  35 // Declaration of global data types.
  36 /////////////////////////////////////////////////////////////////////////////
  37 typedef enum
  38 {
  39     HARDWARE_KEYBOARD_ISE = 0,  /* Hardware keyboard ISE */
  40     SOFTWARE_KEYBOARD_ISE       /* Software keyboard ISE */
  41 } ISE_TYPE_T;
  42
  43 /**
  44  * @brief The structure type to contain IME's information.
  45  *
  46  * @since_tizen 2.4
  47  *
  48  * @see isf_control_get_all_ime_info
  49  */
  50 typedef struct {
  51     char appid[128];
  52     char label[256];
  53     bool is_enabled;
  54     bool is_preinstalled;
  55     int has_option; // 0: no keyboard option, 1: keyboard option is available, -1: unknown yet
  56 } ime_info_s;
  57
  58 /////////////////////////////////////////////////////////////////////////////
  59 // Declaration of global functions.
  60 /////////////////////////////////////////////////////////////////////////////
  61 /**
  62  * @deprecated Deprecated since tizen 2.4. [Use isf_control_set_active_ime() instead]
  63  *
  64  * @brief Set active ISE by UUID.
  65  *
  66  * @param uuid The active ISE's UUID.
  67  *
  68  * @return 0 if successfully, otherwise return -1;
  69  */
  70 EXAPI int isf_control_set_active_ise_by_uuid (const char *uuid);
  71
  72 /**
  73  * @deprecated Deprecated since tizen 2.4. [Use isf_control_get_active_ime() instead]
  74  *
  75  * @brief Get active ISE's UUID.
  76  *
  77  * @param uuid The parameter is used to store active ISE's UUID.
  78  *             Application needs free *uuid if it is not used.
  79  *
  80  * @return the length of UUID if successfully, otherwise return -1
  81  */
  82 EXAPI int isf_control_get_active_ise (char **uuid);
  83
  84 /**
  85  * @brief Get the list of all ISEs' UUID.
  86  *
  87  * @param uuid_list The list is used to store all ISEs' UUID.
  88  *                  Application needs free **uuid_list if it is not used.
  89  *
  90  * @return the count of UUID list if successfully, otherwise return -1;
  91  */
  92 EXAPI int isf_control_get_ise_list (char ***uuid_list);
  93
  94 /**
  95  * @brief Get ISE's information according to ISE's UUID.
  96  *
  97  * @param uuid The ISE's UUID.
  98  * @param name     The parameter is used to store ISE's name. Application needs free *name if it is not used.
  99  * @param language The parameter is used to store ISE's language. Application needs free *language if it is not used.
 100  * @param type     The parameter is used to store ISE's type.
 101  * @param option   The parameter is used to store ISE's option.
 102  *
 103  * @return 0 if successfully, otherwise return -1
 104  */
 105 EXAPI int isf_control_get_ise_info (const char *uuid, char **name, char **language, ISE_TYPE_T *type, int *option);
 106
 107 /**
 108  * @brief Get ISE's information according to ISE's UUID.
 109  *
 110  * @param uuid The ISE's UUID.
 111  * @param name     The parameter is used to store ISE's name. Application needs free *name if it is not used.
 112  * @param language The parameter is used to store ISE's language. Application needs free *language if it is not used.
 113  * @param type     The parameter is used to store ISE's type.
 114  * @param option   The parameter is used to store ISE's option.
 115  * @param module_name The parameter is used to store ISE's module file name.
 116  *
 117  * @return 0 if successfully, otherwise return -1
 118  */
 119 EXAPI int isf_control_get_ise_info_and_module_name (const char *uuid, char **name, char **language, ISE_TYPE_T *type, int *option, char **module_name);
 120
 121 /**
 122  * @brief Set active ISE to default ISE.
 123  *
 124  * @return 0 if successfully, otherwise return -1
 125  */
 126 EXAPI int isf_control_set_active_ise_to_default (void);
 127
 128 /**
 129  * @brief Reset all ISEs' options.
 130  *
 131  * @return 0 if successfully, otherwise return -1;
 132  */
 133 EXAPI int isf_control_reset_ise_option (void);
 134
 135 /**
 136  * @brief Set initial ISE by UUID.
 137  *
 138  * @param uuid The initial ISE's UUID.
 139  *
 140  * @return 0 if successfully, otherwise return -1
 141  */
 142 EXAPI int isf_control_set_initial_ise_by_uuid (const char *uuid);
 143
 144 /**
 145  * @brief Get initial ISE UUID.
 146  *
 147  * @param uuid The parameter is used to store initial ISE's UUID.
 148  *             Application needs free *uuid if it is not used.
 149  *
 150  * @return the length of UUID if successfully, otherwise return -1;
 151  */
 152 EXAPI int isf_control_get_initial_ise (char **uuid);
 153
 154 /**
 155  * @deprecated Deprecated since tizen 2.4. [Use isf_control_show_ime_selector() instead]
 156  *
 157  * @brief Show ISE selector.
 158  *
 159  * @return 0 if successfully, otherwise return -1;
 160  */
 161 EXAPI int isf_control_show_ise_selector (void);
 162
 163 /**
 164  * @brief Get the number of S/W or H/W keyboard ISEs
 165  *
 166  * @param type     ISE's type.
 167  *
 168  * @return the count of ISEs if successfully, otherwise return -1;
 169  */
 170 EXAPI int isf_control_get_ise_count (ISE_TYPE_T type);
 171
 172 /**
 173  * @deprecated Deprecated since tizen 2.4. [Use isf_control_open_ime_option_window() instead]
 174  *
 175  * @brief Show ISE's option window.
 176  *
 177  * @return 0 if successfully, otherwise return -1
 178  */
 179 EXAPI int isf_control_show_ise_option_window (void);
 180
 181 /**
 182  * @brief Gets the information of all IME (on-screen keyboard).
 183  *
 184  * @remarks This API should not be used by IME process.
 185  *
 186  * @since_tizen 2.4
 187  *
 188  * @param[out] info The parameter is used to store all IME information. Application needs to free @a *info variable
 189  *
 190  * @return The count of IME on success, otherwise -1
 191  *
 192  * @post The current active IME's has_option variable will have 0 or 1 value. Other IME's has_option variable might be -1 (unknown).
 193  *
 194  * @code
 195      ime_info_s *ime_info = NULL;
 196      int i, cnt = isf_control_get_all_ime_info(&ime_info);
 197      if (ime_info) {
 198          for (i = 0; i < cnt; i++) {
 199              LOGD("%s %s %d %d %d", ime_info[i].appid, ime_info[i].label, ime_info[i].is_enabled, ime_info[i].is_preinstalled, ime_info[i].has_option);
 200          }
 201          free(ime_info);
 202      }
 203  * @endcode
 204  */
 205 EXAPI int isf_control_get_all_ime_info (ime_info_s **info);
 206
 207 /**
 208  * @brief Requests to open the current IME's option window.
 209  *
 210  * @remarks Each IME might have its option (setting) or not. This function should be called only if the current IME provides its option.
 211  *
 212  * @since_tizen 2.4
 213  *
 214  * @return 0 on success, otherwise return -1
 215  *
 216  * @pre The availibility of IME option can be found using isf_control_get_all_ime_info() and isf_control_get_active_ime() functions.
 217  */
 218 EXAPI int isf_control_open_ime_option_window (void);
 219
 220 /**
 221  * @brief Requests to resume the current IME's option window.
 222  *
 223  * @remarks IME needs to show its option window if it has an option window that was created before and not destroyed yet.
 224  *
 225  * @since_tizen 3.0
 226  *
 227  * @return 0 on success, otherwise return -1
 228  *
 229  * @pre The availibility of IME option can be found using isf_control_get_all_ime_info() and isf_control_get_active_ime() functions.
 230  */
 231 EXAPI int isf_control_resume_ime_option_window (void);
 232
 233 /**
 234  * @brief Gets active IME's Application ID.
 235  *
 236  * @since_tizen 2.4
 237  *
 238  * @param[out] appid This is used to store active IME's Application ID. The allocated @a appid needs to be released using free()
 239  *
 240  * @return The length of @a appid on success, otherwise -1
 241  */
 242 EXAPI int isf_control_get_active_ime (char **appid);
 243
 244 /**
 245  * @brief Sets active IME by Application ID.
 246  *
 247  * @since_tizen 2.4
 248  *
 249  * @param[in] appid Application ID of IME to set as active one
 250  *
 251  * @return 0 on success, otherwise return -1
 252  */
 253 EXAPI int isf_control_set_active_ime (const char *appid);
 254
 255 /**
 256  * @brief Sets On/Off of installed IME by Application ID.
 257  *
 258  * @since_tizen 2.4
 259  *
 260  * @param[in] appid Application ID of IME to enable or disable
 261  * @param[in] is_enabled @c true to enable the IME, otherwise @c false
 262  *
 263  * @return 0 on success, otherwise return -1
 264  */
 265 EXAPI int isf_control_set_enable_ime (const char *appid, bool is_enabled);
 266
 267 /**
 268  * @brief Requests to open the installed IME list application.
 269  *
 270  * @remarks This API should not be used by inputmethod-setting application.
 271  *
 272  * @since_tizen 2.4
 273  *
 274  * @return 0 on success, otherwise return -1
 275  */
 276 EXAPI int isf_control_show_ime_list (void);
 277
 278 /**
 279  * @brief Requests to open the IME selector application.
 280  *
 281  * @remarks This API should not be used by inputmethod-setting application.
 282  *
 283  * @since_tizen 2.4
 284  *
 285  * @return 0 on success, otherwise return -1
 286  */
 287 EXAPI int isf_control_show_ime_selector (void);
 288
 289 /**
 290  * @brief Checks if the specific IME is enabled or disabled in the system keyboard setting.
 291  *
 292  * @since_tizen 2.4
 293  *
 294  * @param[in] appid The application ID of the IME
 295  * @param[out] enabled The On (enabled) and Off (disabled) state of the IME
 296  *
 297  * @return 0 on success, otherwise return -1
 298  */
 299 EXAPI int isf_control_is_ime_enabled (const char *appid, bool *enabled);
 300
 301 /**
 302  * @brief Get the recent geometry of S/W keyboard
 303  *
 304  * @remarks If the keyboard has never been shown, this function will return -1 since the framework can't know its size.
 305  * The caller application needs to assume the default height.
 306  *
 307  * @since_tizen 2.4
 308  *
 309  * @param[out] x Pointer to an integer in which to store the X coordinate of the IME that appeared recently.
 310  * @param[out] y Pointer to an integer in which to store the Y coordinate of the IME that appeared recently.
 311  * @param[out] w Pointer to an integer in which to store the width of the IME that appeared recently.
 312  * @param[out] h Pointer to an integer in which to store the height of the IME that appeared recently.
 313  *
 314  * @return 0 if successfully, otherwise return -1;
 315  */
 316 EXAPI int isf_control_get_recent_ime_geometry (int *x, int *y, int *w, int *h);
 317
 318 /**
 319  * @brief Get the recent geometry of S/W keyboard with the rotation mode
 320  *
 321  * @remarks If the keyboard has never been shown, this function will return -1 since the framework can't know its size.
 322  * The caller application needs to assume the default height.
 323  *
 324  * @param[in] angle the rotation angle of application window.
 325  * @param[out] x Pointer to an integer in which to store the X coordinate of the IME that appeared recently.
 326  * @param[out] y Pointer to an integer in which to store the Y coordinate of the IME that appeared recently.
 327  * @param[out] w Pointer to an integer in which to store the width of the IME that appeared recently.
 328  * @param[out] h Pointer to an integer in which to store the height of the IME that appeared recently.
 329  *
 330  * @return 0 if successfully, otherwise return -1;
 331  */
 332 EXAPI int isf_control_get_recent_ime_geometry_with_rotation_angle (int angle, int *x, int *y, int *w, int *h);
 333
 334 /**
 335  * @brief Requests to hide the input panel.
 336  *
 337  * @since_tizen 2.4
 338  *
 339  * @return 0 on success, otherwise return -1
 340  */
 341 EXAPI int isf_control_hide_ime (void);
 342
 343 #ifdef __cplusplus
 344 }
 345 #endif /* __cplusplus */
 346
 347 #endif /* __ISF_CONTROL_H */
 348
 349 /*
 350 vi:ts=4:nowrap:ai:expandtab
 351 */