widget/gtk/nsGtkKeyUtils.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* vim:expandtab:shiftwidth=4:tabstop=4:
   3  */
   4 /* This Source Code Form is subject to the terms of the Mozilla Public
   5  * License, v. 2.0. If a copy of the MPL was not distributed with this
   6  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   7
   8 #ifndef __nsGdkKeyUtils_h__
   9 #define __nsGdkKeyUtils_h__
  10
  11 #include "nsTArray.h"
  12 #include "mozilla/EventForwards.h"
  13
  14 #include <gdk/gdk.h>
  15
  16 namespace mozilla {
  17 namespace widget {
  18
  19 /**
  20  *  KeymapWrapper is a wrapper class of GdkKeymap.  GdkKeymap doesn't support
  21  *  all our needs, therefore, we need to access lower level APIs.
  22  *  But such code is usually complex and might be slow.  Against such issues,
  23  *  we should cache some information.
  24  *
  25  *  This class provides only static methods.  The methods is using internal
  26  *  singleton instance which is initialized by default GdkKeymap.  When the
  27  *  GdkKeymap is destroyed, the singleton instance will be destroyed.
  28  */
  29
  30 class KeymapWrapper
  31 {
  32 public:
  33     /**
  34      * Compute an our DOM keycode from a GDK keyval.
  35      */
  36     static uint32_t ComputeDOMKeyCode(const GdkEventKey* aGdkKeyEvent);
  37
  38     /**
  39      * Compute a DOM key name index from aGdkKeyEvent.
  40      */
  41     KeyNameIndex ComputeDOMKeyNameIndex(const GdkEventKey* aGdkKeyEvent);
  42
  43     /**
  44      * Modifier is list of modifiers which we support in widget level.
  45      */
  46     enum Modifier {
  47         NOT_MODIFIER       = 0x0000,
  48         CAPS_LOCK          = 0x0001,
  49         NUM_LOCK           = 0x0002,
  50         SCROLL_LOCK        = 0x0004,
  51         SHIFT              = 0x0008,
  52         CTRL               = 0x0010,
  53         ALT                = 0x0020,
  54         META               = 0x0040,
  55         SUPER              = 0x0080,
  56         HYPER              = 0x0100,
  57         LEVEL3             = 0x0200,
  58         LEVEL5             = 0x0400
  59     };
  60
  61     /**
  62      * Modifiers is used for combination of Modifier.
  63      * E.g., |Modifiers modifiers = (SHIFT | CTRL);| means Shift and Ctrl.
  64      */
  65     typedef uint32_t Modifiers;
  66
  67     /**
  68      * GetCurrentModifierState() returns current modifier key state.
  69      * The "current" means actual state of hardware keyboard when this is
  70      * called.  I.e., if some key events are not still dispatched by GDK,
  71      * the state may mismatch with GdkEventKey::state.
  72      *
  73      * @return                  Current modifier key state.
  74      */
  75     static guint GetCurrentModifierState();
  76
  77     /**
  78      * AreModifiersCurrentlyActive() checks the "current" modifier state
  79      * on aGdkWindow with the keymap of the singleton instance.
  80      *
  81      * @param aModifiers        One or more of Modifier values except
  82      *                          NOT_MODIFIER.
  83      * @return                  TRUE if all of modifieres in aModifiers are
  84      *                          active.  Otherwise, FALSE.
  85      */
  86     static bool AreModifiersCurrentlyActive(Modifiers aModifiers);
  87
  88     /**
  89      * AreModifiersActive() just checks whether aModifierState indicates
  90      * all modifiers in aModifiers are active or not.
  91      *
  92      * @param aModifiers        One or more of Modifier values except
  93      *                          NOT_MODIFIER.
  94      * @param aModifierState    GDK's modifier states.
  95      * @return                  TRUE if aGdkModifierType indecates all of
  96      *                          modifiers in aModifier are active.
  97      *                          Otherwise, FALSE.
  98      */
  99     static bool AreModifiersActive(Modifiers aModifiers,
 100                                    guint aModifierState);
 101
 102     /**
 103      * InitInputEvent() initializes the aInputEvent with aModifierState.
 104      */
 105     static void InitInputEvent(WidgetInputEvent& aInputEvent,
 106                                guint aModifierState);
 107
 108     /**
 109      * InitKeyEvent() intializes aKeyEvent's modifier key related members
 110      * and keycode related values.
 111      *
 112      * @param aKeyEvent         It's an WidgetKeyboardEvent which needs to be
 113      *                          initialized.
 114      * @param aGdkKeyEvent      A native GDK key event.
 115      */
 116     static void InitKeyEvent(WidgetKeyboardEvent& aKeyEvent,
 117                              GdkEventKey* aGdkKeyEvent);
 118
 119     /**
 120      * IsKeyPressEventNecessary() returns TRUE when aGdkKeyEvent should cause
 121      * a DOM keypress event.  Otherwise, FALSE.
 122      */
 123     static bool IsKeyPressEventNecessary(GdkEventKey* aGdkKeyEvent);
 124
 125 protected:
 126
 127     /**
 128      * GetInstance() returns a KeymapWrapper instance.
 129      *
 130      * @return                  A singleton instance of KeymapWrapper.
 131      */
 132     static KeymapWrapper* GetInstance();
 133
 134     KeymapWrapper();
 135     ~KeymapWrapper();
 136
 137     bool mInitialized;
 138
 139     /**
 140      * Initializing methods.
 141      */
 142     void Init();
 143     void InitXKBExtension();
 144     void InitBySystemSettings();
 145
 146     /**
 147      * mModifierKeys stores each hardware key information.
 148      */
 149     struct ModifierKey {
 150         guint mHardwareKeycode;
 151         guint mMask;
 152
 153         ModifierKey(guint aHardwareKeycode) :
 154           mHardwareKeycode(aHardwareKeycode), mMask(0)
 155         {
 156         }
 157     };
 158     nsTArray<ModifierKey> mModifierKeys;
 159
 160     /**
 161      * GetModifierKey() returns modifier key information of the hardware
 162      * keycode.  If the key isn't a modifier key, returns nullptr.
 163      */
 164     ModifierKey* GetModifierKey(guint aHardwareKeycode);
 165
 166     /**
 167      * mModifierMasks is bit masks for each modifier.  The index should be one
 168      * of ModifierIndex values.
 169      */
 170     enum ModifierIndex {
 171         INDEX_NUM_LOCK,
 172         INDEX_SCROLL_LOCK,
 173         INDEX_ALT,
 174         INDEX_META,
 175         INDEX_SUPER,
 176         INDEX_HYPER,
 177         INDEX_LEVEL3,
 178         INDEX_LEVEL5,
 179         COUNT_OF_MODIFIER_INDEX
 180     };
 181     guint mModifierMasks[COUNT_OF_MODIFIER_INDEX];
 182
 183     guint GetModifierMask(Modifier aModifier) const;
 184
 185     /**
 186      * @param aGdkKeyval        A GDK defined modifier key value such as
 187      *                          GDK_Shift_L.
 188      * @return                  Returns Modifier values for aGdkKeyval.
 189      *                          If the given key code isn't a modifier key,
 190      *                          returns NOT_MODIFIER.
 191      */
 192     static Modifier GetModifierForGDKKeyval(guint aGdkKeyval);
 193
 194 #ifdef PR_LOGGING
 195     static const char* GetModifierName(Modifier aModifier);
 196 #endif // PR_LOGGING
 197
 198     /**
 199      * mGdkKeymap is a wrapped instance by this class.
 200      */
 201     GdkKeymap* mGdkKeymap;
 202
 203     /**
 204      * The base event code of XKB extension.
 205      */
 206     int mXKBBaseEventCode;
 207
 208     /**
 209      * Pointer of the singleton instance.
 210      */
 211     static KeymapWrapper* sInstance;
 212
 213     /**
 214      * Signal handlers.
 215      */
 216     static void OnKeysChanged(GdkKeymap* aKeymap, KeymapWrapper* aKeymapWrapper);
 217     static void OnDestroyKeymap(KeymapWrapper* aKeymapWrapper,
 218                                 GdkKeymap *aGdkKeymap);
 219
 220     /**
 221      * GetCharCodeFor() Computes what character is inputted by the key event
 222      * with aModifierState and aGroup.
 223      *
 224      * @param aGdkKeyEvent      Native key event, must not be nullptr.
 225      * @param aModifierState    Combination of GdkModifierType which you
 226      *                          want to test with aGdkKeyEvent.
 227      * @param aGroup            Set group in the mGdkKeymap.
 228      * @return                  charCode which is inputted by aGdkKeyEvent.
 229      *                          If failed, this returns 0.
 230      */
 231     static uint32_t GetCharCodeFor(const GdkEventKey *aGdkKeyEvent);
 232     uint32_t GetCharCodeFor(const GdkEventKey *aGdkKeyEvent,
 233                             guint aModifierState,
 234                             gint aGroup);
 235
 236     /**
 237      * GetKeyLevel() returns level of the aGdkKeyEvent in mGdkKeymap.
 238      *
 239      * @param aGdkKeyEvent      Native key event, must not be nullptr.
 240      * @return                  Using level.  Typically, this is 0 or 1.
 241      *                          If failed, this returns -1.
 242      */
 243     gint GetKeyLevel(GdkEventKey *aGdkKeyEvent);
 244
 245     /**
 246      * GetFirstLatinGroup() returns group of mGdkKeymap which can input an
 247      * ASCII character by GDK_A.
 248      *
 249      * @return                  group value of GdkEventKey.
 250      */
 251     gint GetFirstLatinGroup();
 252
 253     /**
 254      * IsLatinGroup() checkes whether the keyboard layout of aGroup is
 255      * ASCII alphabet inputtable or not.
 256      *
 257      * @param aGroup            The group value of GdkEventKey.
 258      * @return                  TRUE if the keyboard layout can input
 259      *                          ASCII alphabet.  Otherwise, FALSE.
 260      */
 261     bool IsLatinGroup(guint8 aGroup);
 262
 263     /**
 264      * IsBasicLatinLetterOrNumeral() Checks whether the aCharCode is an
 265      * alphabet or a numeric character in ASCII.
 266      *
 267      * @param aCharCode         Charcode which you want to test.
 268      * @return                  TRUE if aCharCode is an alphabet or a numeric
 269      *                          in ASCII range.  Otherwise, FALSE.
 270      */
 271     static bool IsBasicLatinLetterOrNumeral(uint32_t aCharCode);
 272
 273     /**
 274      * GetGDKKeyvalWithoutModifier() returns the keyval for aGdkKeyEvent when
 275      * ignoring the modifier state except NumLock. (NumLock is a key to change
 276      * some key's meaning.)
 277      */
 278     static guint GetGDKKeyvalWithoutModifier(const GdkEventKey *aGdkKeyEvent);
 279
 280     /**
 281      * GetDOMKeyCodeFromKeyPairs() returns DOM keycode for aGdkKeyval if
 282      * it's in KeyPair table.
 283      */
 284     static uint32_t GetDOMKeyCodeFromKeyPairs(guint aGdkKeyval);
 285
 286     /**
 287      * InitKeypressEvent() intializes keyCode, charCode and
 288      * alternativeCharCodes of keypress event.
 289      *
 290      * @param aKeyEvent         An NS_KEY_PRESS event, must not be nullptr.
 291      *                          The modifier related members and keyCode must
 292      *                          be initialized already.
 293      * @param aGdkKeyEvent      A native key event which causes dispatching
 294      *                          aKeyEvent.
 295      */
 296     void InitKeypressEvent(WidgetKeyboardEvent& aKeyEvent,
 297                            GdkEventKey* aGdkKeyEvent);
 298 };
 299
 300 } // namespace widget
 301 } // namespace mozilla
 302
 303 #endif /* __nsGdkKeyUtils_h__ */