ism/src/scim_hotkey.h

   1 /**
   2  * @file scim_hotkey.h
   3  * @brief Defines the scim::HotkeyMatcher and scim::IMEngineHotkeyMatcher classes.
   4  */
   5
   6 /* ISF is based on SCIM 1.4.7 and extended for supporting more mobile fitable. */
   7
   8 /*
   9  * Smart Common Input Method
  10  *
  11  * Copyright (c) 2005 James Su <suzhe@tsinghua.org.cn>
  12  *
  13  *
  14  * This library is free software; you can redistribute it and/or
  15  * modify it under the terms of the GNU Lesser General Public
  16  * License as published by the Free Software Foundation; either
  17  * version 2 of the License, or (at your option) any later version.
  18  *
  19  * This library is distributed in the hope that it will be useful,
  20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22  * GNU Lesser General Public License for more details.
  23  *
  24  * You should have received a copy of the GNU Lesser General Public
  25  * License along with this program; if not, write to the
  26  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  27  * Boston, MA  02111-1307  USA
  28  *
  29  * $Id: scim_hotkey.h,v 1.5 2005/10/06 18:02:06 liuspider Exp $
  30  */
  31
  32 #ifndef __SCIM_HOTKEY_H
  33 #define __SCIM_HOTKEY_H
  34
  35 namespace scim {
  36 /**
  37  * @addtogroup Accessories
  38  * @ingroup InputServiceFramework
  39  * @{
  40  */
  41
  42 /**
  43  * @brief This class is used to match a KeyEvent among a set of hotkeys.
  44  *
  45  * This class keeps the key event history so that it can match any kind of
  46  * key events, including key release events, correctly.
  47  *
  48  * If there are large amount of hotkeys to be matched, this class can provide
  49  * very good performance.
  50  */
  51 class HotkeyMatcher
  52 {
  53     class HotkeyMatcherImpl;
  54
  55     HotkeyMatcherImpl *m_impl;
  56
  57     HotkeyMatcher (const HotkeyMatcher &);
  58     const HotkeyMatcher & operator = (const HotkeyMatcher &);
  59
  60 public:
  61     /**
  62      * @brief Constructor
  63      */
  64     HotkeyMatcher ();
  65
  66     /**
  67      * @brief Destructor.
  68      */
  69     ~HotkeyMatcher ();
  70
  71     /**
  72      * @brief Add a Hotkey into this HotkeyMatcher.
  73      *
  74      * If a same Hotkey was already added, then it'll be replaced by this new one.
  75      *
  76      * @param key A Hotkey to be added.
  77      * @param id  An id to be binded to this Hotkey.
  78      */
  79     void add_hotkey        (const KeyEvent     &key,  int id);
  80
  81     /**
  82      * @brief Add a set of Hotkeys into this HotkeyMatcher.
  83      *
  84      * If a same Hotkey in the list was already added, then it'll be replaced by the new one.
  85      *
  86      * @param keys A set of Hotkeys to be added.
  87      * @param id  An id to be binded to these Hotkeys.
  88      */
  89     void add_hotkeys       (const KeyEventList &keys, int id);
  90
  91     /**
  92      * @brief Find all Hotkeys binded to a specific id.
  93      *
  94      * @param id The id to be found.
  95      * @param keys A KeyEventList object to hold all KeyEvents binded to the id.
  96      * @return The number of Hotkeys found.
  97      */
  98     size_t find_hotkeys     (int id, KeyEventList &keys) const;
  99
 100     /**
 101      * @brief Get all Hotkeys added into this HotkeyMatcher.
 102      *
 103      * @param keys A KeyEventList object to hold all KeyEvents.
 104      * @param ids  A int list to hold all corresponding IDs.
 105      *
 106      * @return The number of available Hotkeys.
 107      */
 108     size_t get_all_hotkeys  (KeyEventList &keys, std::vector <int> &ids) const;
 109
 110     /**
 111      * @brief Reset the HotkeyMatcher.
 112      *
 113      * The KeyEvent queue will be cleared, all state will be reset.
 114      * The Hotkeys which were already added will not be touched.
 115      */
 116     void reset              (void);
 117
 118     /**
 119      * @brief Clear all Hotkeys.
 120      */
 121     void clear              (void);
 122
 123     /**
 124      * @brief Push a KeyEvent into the queue.
 125      *
 126      * This KeyEvent will be matched against the available Hotkeys immediately.
 127      *
 128      * @param key The key to be pushed into.
 129      */
 130     void push_key_event     (const KeyEvent &key);
 131
 132     /**
 133      * @brief Check if the last KeyEvent pushed by push_key_event () matched with any Hotkey.
 134      *
 135      * @return true If the KeyEvent matched with a Hotkey.
 136      */
 137     bool is_matched         (void) const;
 138
 139     /**
 140      * @brief Get the match result.
 141      *
 142      * @return The corresponding id of the matched Hotkey. If no Hotkey was matched, return -1.
 143      */
 144     int  get_match_result   (void) const;
 145
 146 };
 147
 148 typedef enum {
 149     NEWISE_T,
 150     HELPER_T,
 151     IMENGINE_T
 152 } ISE_TYPE;
 153
 154 typedef struct {
 155     String uuid;
 156     ISE_TYPE type;
 157 } ISEInfo;
 158
 159 /**
 160  * @brief This class hold all Hotkeys for each IMEngines.
 161  */
 162 class IMEngineHotkeyMatcher
 163 {
 164     class IMEngineHotkeyMatcherImpl;
 165
 166     IMEngineHotkeyMatcherImpl *m_impl;
 167
 168     IMEngineHotkeyMatcher (const IMEngineHotkeyMatcher &);
 169     const IMEngineHotkeyMatcher & operator = (const IMEngineHotkeyMatcher &);
 170
 171 public:
 172     IMEngineHotkeyMatcher       ();
 173     ~IMEngineHotkeyMatcher      ();
 174
 175     /**
 176      * @brief Load all Hotkeys for IMEngines from Config.
 177      *
 178      * @param config The Config object in which the Hotkeys are stored.
 179      */
 180     void   load_hotkeys        (const ConfigPointer &config);
 181
 182     /**
 183      * @brief Save all Hotkeys for IMEngines to Config.
 184      *
 185      * @param config Store all Hotkeys to this Config object.
 186      */
 187     void   save_hotkeys        (const ConfigPointer &config) const;
 188
 189     /**
 190      * @brief Add a Hotkey for an IMEngine into this IMEngineHotkeyMatcher.
 191      *
 192      * @param key  The Hotkey.
 193      * @param uuid The UUID of the corresponding IMEngine.
 194      */
 195     void   add_hotkey          (const KeyEvent &key, const String &uuid, const ISE_TYPE &type);
 196
 197     /**
 198      * @brief Add a set of Hotkeys for an IMEngine into this IMEngineHotkeyMatcher.
 199      *
 200      * @param keys  The Hotkeys.
 201      * @param uuid The UUID of the corresponding IMEngine.
 202      */
 203     void   add_hotkeys         (const KeyEventList &keys, const String &uuid, const ISE_TYPE &type);
 204
 205     /**
 206      * @brief Find all Hotkeys binded to a specific IMEngine UUID.
 207      *
 208      * @param uuid The IMEngine uuid to be found.
 209      * @param keys A KeyEventList object to hold all KeyEvents binded to the uuid.
 210      * @return The number of Hotkeys found.
 211      */
 212     size_t find_hotkeys        (const String &uuid, KeyEventList &keys) const;
 213
 214     /**
 215      * @brief Get all hotkeys in this IMEngineHotkeyMatcher.
 216      *
 217      * @param keys   A list of all Hotkeys.
 218      * @param uuids  A list of all corresponding IMEngine UUIDs.
 219      * @return the number of hotkeys found.
 220      */
 221     size_t get_all_hotkeys     (KeyEventList &keys, std::vector <String> &uuids) const;
 222
 223     /**
 224      * @brief Reset the IMEngineHotkeyMatcher.
 225      *
 226      * The KeyEvent queue will be cleared, all state will be reset.
 227      * The Hotkeys which were already added will not be touched.
 228      */
 229     void   reset                (void);
 230
 231     /**
 232      * @brief Clear all Hotkeys and reset the IMEngineHotkeyMatcher.
 233      */
 234     void   clear                (void);
 235
 236     /**
 237      * @brief Push a KeyEvent into the queue.
 238      *
 239      * This KeyEvent will be matched against the available Hotkeys immediately.
 240      *
 241      * @param key The key to be pushed into.
 242      */
 243     void   push_key_event       (const KeyEvent &key);
 244
 245     /**
 246      * @brief Check if the last KeyEvent pushed by push_key_event () matched with any Hotkey.
 247      *
 248      * @return true If the KeyEvent matched with a Hotkey.
 249      */
 250     bool   is_matched           (void) const;
 251
 252     /**
 253      * @brief Get the match result.
 254      *
 255      * @return The corresponding UUID of the matched Hotkey. If no Hotkey was matched, return null string.
 256      */
 257     ISEInfo get_match_result   (void) const;
 258 };
 259
 260 /**
 261  * @brief FrontEnd actions which could be binded with Hotkeys.
 262  */
 263 enum FrontEndHotkeyAction
 264 {
 265     SCIM_FRONTEND_HOTKEY_NOOP               = 0,    /**< No action */
 266     SCIM_FRONTEND_HOTKEY_TRIGGER            = 1,    /**< Turn on/off the input method. */
 267     SCIM_FRONTEND_HOTKEY_ON                 = 2,    /**< Turn on the input method. */
 268     SCIM_FRONTEND_HOTKEY_OFF                = 3,    /**< Turn off the input method. */
 269     SCIM_FRONTEND_HOTKEY_NEXT_FACTORY       = 4,    /**< Switch current Input Context to use the next available IMEngine Factory. */
 270     SCIM_FRONTEND_HOTKEY_PREVIOUS_FACTORY   = 5,    /**< Switch current Input Context to use the previous available IMEngine Factory. */
 271     SCIM_FRONTEND_HOTKEY_SHOW_FACTORY_MENU  = 6     /**< Show a menu of all available IMEngine Factories. */
 272 };
 273
 274 /**
 275  * @brief This class hold all FrontEnd specific Hotkeys, such as trigger keys, on/off keys, etc.
 276  */
 277 class FrontEndHotkeyMatcher
 278 {
 279     class FrontEndHotkeyMatcherImpl;
 280
 281     FrontEndHotkeyMatcherImpl *m_impl;
 282
 283     FrontEndHotkeyMatcher (const FrontEndHotkeyMatcher &);
 284     const FrontEndHotkeyMatcher & operator = (const FrontEndHotkeyMatcher &);
 285
 286 public:
 287     FrontEndHotkeyMatcher       ();
 288     ~FrontEndHotkeyMatcher      ();
 289
 290     /**
 291      * @brief Load all FrontEnd specific Hotkeys from Config.
 292      *
 293      * @param config The Config object in which the Hotkeys are stored.
 294      */
 295     void   load_hotkeys        (const ConfigPointer &config);
 296
 297     /**
 298      * @brief Save all FrontEnd specific Hotkeys to Config.
 299      *
 300      * @param config Store all Hotkeys to this Config object.
 301      */
 302     void   save_hotkeys        (const ConfigPointer &config) const;
 303
 304     /**
 305      * @brief Add a Hotkey for an FrontEnd into this FrontEndHotkeyMatcher.
 306      *
 307      * @param key  The Hotkey.
 308      * @param action The action to do when the hotkey is matched.
 309      */
 310     void   add_hotkey          (const KeyEvent &key, FrontEndHotkeyAction action);
 311
 312     /**
 313      * @brief Add a set of Hotkeys for an FrontEnd into this FrontEndHotkeyMatcher.
 314      *
 315      * @param keys  The Hotkeys.
 316      * @param action The action to do when the hotkey is matched.
 317      */
 318     void   add_hotkeys         (const KeyEventList &keys, FrontEndHotkeyAction action);
 319
 320     /**
 321      * @brief Find all Hotkeys binded to a specific action.
 322      *
 323      * @param action The action to be found.
 324      * @param keys A KeyEventList object to hold all KeyEvents binded to the action.
 325      * @return The number of Hotkeys found.
 326      */
 327     size_t find_hotkeys        (FrontEndHotkeyAction action, KeyEventList &keys) const;
 328
 329     /**
 330      * @brief Get all hotkeys in this FrontEndHotkeyMatcher.
 331      *
 332      * @param keys   A list of all Hotkeys.
 333      * @param actions  A list of all corresponding actions
 334      */
 335     size_t get_all_hotkeys     (KeyEventList &keys, std::vector <FrontEndHotkeyAction> &actions) const;
 336
 337     /**
 338      * @brief Reset the FrontEndHotkeyMatcher.
 339      *
 340      * The KeyEvent queue will be cleared, all state will be reset.
 341      * The Hotkeys which were already added will not be touched.
 342      */
 343     void   reset                (void);
 344
 345     /**
 346      * @brief Clear all Hotkeys and reset the FrontEndHotkeyMatcher.
 347      */
 348     void   clear                (void);
 349
 350     /**
 351      * @brief Push a KeyEvent into the queue.
 352      *
 353      * This KeyEvent will be matched against the available Hotkeys immediately.
 354      *
 355      * @param key The key to be pushed into.
 356      */
 357     void   push_key_event       (const KeyEvent &key);
 358
 359     /**
 360      * @brief Check if the last KeyEvent pushed by push_key_event () matched with any Hotkey.
 361      *
 362      * @return true If the KeyEvent matched with a Hotkey.
 363      */
 364     bool   is_matched           (void) const;
 365
 366     /**
 367      * @brief Get the match result.
 368      *
 369      * @return The corresponding action of the matched Hotkey.
 370      */
 371     FrontEndHotkeyAction get_match_result   (void) const;
 372 };
 373
 374 /** @} */
 375
 376 } // namespace scim
 377
 378 #endif //__SCIM_HOTKEY_H
 379
 380 /*
 381 vi:ts=4:nowrap:ai:expandtab
 382 */
 383