juce/source/src/gui/components/keyboard/juce_KeyPress.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_KEYPRESS_JUCEHEADER__
  27 #define __JUCE_KEYPRESS_JUCEHEADER__
  28
  29 #include "juce_ModifierKeys.h"
  30 #include "../../../text/juce_String.h"
  31
  32
  33 //==============================================================================
  34 /**
  35     Represents a key press, including any modifier keys that are needed.
  36
  37     E.g. a KeyPress might represent CTRL+C, SHIFT+ALT+H, Spacebar, Escape, etc.
  38
  39     @see Component, KeyListener, Button::addShortcut, KeyPressMappingManager
  40 */
  41 class JUCE_API  KeyPress
  42 {
  43 public:
  44     //==============================================================================
  45     /** Creates an (invalid) KeyPress.
  46
  47         @see isValid
  48     */
  49     KeyPress() noexcept;
  50
  51     /** Creates a KeyPress for a key and some modifiers.
  52
  53         e.g.
  54         CTRL+C would be: KeyPress ('c', ModifierKeys::ctrlModifier)
  55         SHIFT+Escape would be: KeyPress (KeyPress::escapeKey, ModifierKeys::shiftModifier)
  56
  57         @param keyCode      a code that represents the key - this value must be
  58                             one of special constants listed in this class, or an
  59                             8-bit character code such as a letter (case is ignored),
  60                             digit or a simple key like "," or ".". Note that this
  61                             isn't the same as the textCharacter parameter, so for example
  62                             a keyCode of 'a' and a shift-key modifier should have a
  63                             textCharacter value of 'A'.
  64         @param modifiers    the modifiers to associate with the keystroke
  65         @param textCharacter    the character that would be printed if someone typed
  66                             this keypress into a text editor. This value may be
  67                             null if the keypress is a non-printing character
  68         @see getKeyCode, isKeyCode, getModifiers
  69     */
  70     KeyPress (int keyCode,
  71               const ModifierKeys& modifiers,
  72               juce_wchar textCharacter) noexcept;
  73
  74     /** Creates a keypress with a keyCode but no modifiers or text character.
  75     */
  76     KeyPress (int keyCode) noexcept;
  77
  78     /** Creates a copy of another KeyPress. */
  79     KeyPress (const KeyPress& other) noexcept;
  80
  81     /** Copies this KeyPress from another one. */
  82     KeyPress& operator= (const KeyPress& other) noexcept;
  83
  84     /** Compares two KeyPress objects. */
  85     bool operator== (const KeyPress& other) const noexcept;
  86
  87     /** Compares two KeyPress objects. */
  88     bool operator!= (const KeyPress& other) const noexcept;
  89
  90     //==============================================================================
  91     /** Returns true if this is a valid KeyPress.
  92
  93         A null keypress can be created by the default constructor, in case it's
  94         needed.
  95     */
  96     bool isValid() const noexcept                               { return keyCode != 0; }
  97
  98     /** Returns the key code itself.
  99
 100         This will either be one of the special constants defined in this class,
 101         or an 8-bit character code.
 102     */
 103     int getKeyCode() const noexcept                             { return keyCode; }
 104
 105     /** Returns the key modifiers.
 106
 107         @see ModifierKeys
 108     */
 109     const ModifierKeys getModifiers() const noexcept            { return mods; }
 110
 111     /** Returns the character that is associated with this keypress.
 112
 113         This is the character that you'd expect to see printed if you press this
 114         keypress in a text editor or similar component.
 115     */
 116     juce_wchar getTextCharacter() const noexcept                { return textCharacter; }
 117
 118     /** Checks whether the KeyPress's key is the same as the one provided, without checking
 119         the modifiers.
 120
 121         The values for key codes can either be one of the special constants defined in
 122         this class, or an 8-bit character code.
 123
 124         @see getKeyCode
 125     */
 126     bool isKeyCode (int keyCodeToCompare) const noexcept        { return keyCode == keyCodeToCompare; }
 127
 128     //==============================================================================
 129     /** Converts a textual key description to a KeyPress.
 130
 131         This attempts to decode a textual version of a keypress, e.g. "CTRL + C" or "SPACE".
 132
 133         This isn't designed to cope with any kind of input, but should be given the
 134         strings that are created by the getTextDescription() method.
 135
 136         If the string can't be parsed, the object returned will be invalid.
 137
 138         @see getTextDescription
 139     */
 140     static const KeyPress createFromDescription (const String& textVersion);
 141
 142     /** Creates a textual description of the key combination.
 143
 144         e.g. "CTRL + C" or "DELETE".
 145
 146         To store a keypress in a file, use this method, along with createFromDescription()
 147         to retrieve it later.
 148     */
 149     String getTextDescription() const;
 150
 151     /** Creates a textual description of the key combination, using unicode icon symbols if possible.
 152
 153         On OSX, this uses the Apple symbols for command, option, shift, etc, instead of the textual
 154         modifier key descriptions that are returned by getTextDescription()
 155     */
 156     String getTextDescriptionWithIcons() const;
 157
 158     //==============================================================================
 159     /** Checks whether the user is currently holding down the keys that make up this
 160         KeyPress.
 161
 162         Note that this will return false if any extra modifier keys are
 163         down - e.g. if the keypress is CTRL+X and the user is actually holding CTRL+ALT+x
 164         then it will be false.
 165     */
 166     bool isCurrentlyDown() const;
 167
 168     /** Checks whether a particular key is held down, irrespective of modifiers.
 169
 170         The values for key codes can either be one of the special constants defined in
 171         this class, or an 8-bit character code.
 172     */
 173     static bool isKeyCurrentlyDown (int keyCode);
 174
 175     //==============================================================================
 176     // Key codes
 177     //
 178     // Note that the actual values of these are platform-specific and may change
 179     // without warning, so don't store them anywhere as constants. For persisting/retrieving
 180     // KeyPress objects, use getTextDescription() and createFromDescription() instead.
 181     //
 182
 183     static const int spaceKey;      /**< key-code for the space bar */
 184     static const int escapeKey;     /**< key-code for the escape key */
 185     static const int returnKey;     /**< key-code for the return key*/
 186     static const int tabKey;        /**< key-code for the tab key*/
 187
 188     static const int deleteKey;     /**< key-code for the delete key (not backspace) */
 189     static const int backspaceKey;  /**< key-code for the backspace key */
 190     static const int insertKey;     /**< key-code for the insert key */
 191
 192     static const int upKey;         /**< key-code for the cursor-up key */
 193     static const int downKey;       /**< key-code for the cursor-down key */
 194     static const int leftKey;       /**< key-code for the cursor-left key */
 195     static const int rightKey;      /**< key-code for the cursor-right key */
 196     static const int pageUpKey;     /**< key-code for the page-up key */
 197     static const int pageDownKey;   /**< key-code for the page-down key */
 198     static const int homeKey;       /**< key-code for the home key */
 199     static const int endKey;        /**< key-code for the end key */
 200
 201     static const int F1Key;         /**< key-code for the F1 key */
 202     static const int F2Key;         /**< key-code for the F2 key */
 203     static const int F3Key;         /**< key-code for the F3 key */
 204     static const int F4Key;         /**< key-code for the F4 key */
 205     static const int F5Key;         /**< key-code for the F5 key */
 206     static const int F6Key;         /**< key-code for the F6 key */
 207     static const int F7Key;         /**< key-code for the F7 key */
 208     static const int F8Key;         /**< key-code for the F8 key */
 209     static const int F9Key;         /**< key-code for the F9 key */
 210     static const int F10Key;        /**< key-code for the F10 key */
 211     static const int F11Key;        /**< key-code for the F11 key */
 212     static const int F12Key;        /**< key-code for the F12 key */
 213     static const int F13Key;        /**< key-code for the F13 key */
 214     static const int F14Key;        /**< key-code for the F14 key */
 215     static const int F15Key;        /**< key-code for the F15 key */
 216     static const int F16Key;        /**< key-code for the F16 key */
 217
 218     static const int numberPad0;     /**< key-code for the 0 on the numeric keypad. */
 219     static const int numberPad1;     /**< key-code for the 1 on the numeric keypad. */
 220     static const int numberPad2;     /**< key-code for the 2 on the numeric keypad. */
 221     static const int numberPad3;     /**< key-code for the 3 on the numeric keypad. */
 222     static const int numberPad4;     /**< key-code for the 4 on the numeric keypad. */
 223     static const int numberPad5;     /**< key-code for the 5 on the numeric keypad. */
 224     static const int numberPad6;     /**< key-code for the 6 on the numeric keypad. */
 225     static const int numberPad7;     /**< key-code for the 7 on the numeric keypad. */
 226     static const int numberPad8;     /**< key-code for the 8 on the numeric keypad. */
 227     static const int numberPad9;     /**< key-code for the 9 on the numeric keypad. */
 228
 229     static const int numberPadAdd;            /**< key-code for the add sign on the numeric keypad. */
 230     static const int numberPadSubtract;       /**< key-code for the subtract sign on the numeric keypad. */
 231     static const int numberPadMultiply;       /**< key-code for the multiply sign on the numeric keypad. */
 232     static const int numberPadDivide;         /**< key-code for the divide sign on the numeric keypad. */
 233     static const int numberPadSeparator;      /**< key-code for the comma on the numeric keypad. */
 234     static const int numberPadDecimalPoint;   /**< key-code for the decimal point sign on the numeric keypad. */
 235     static const int numberPadEquals;         /**< key-code for the equals key on the numeric keypad. */
 236     static const int numberPadDelete;         /**< key-code for the delete key on the numeric keypad. */
 237
 238     static const int playKey;        /**< key-code for a multimedia 'play' key, (not all keyboards will have one) */
 239     static const int stopKey;        /**< key-code for a multimedia 'stop' key, (not all keyboards will have one) */
 240     static const int fastForwardKey; /**< key-code for a multimedia 'fast-forward' key, (not all keyboards will have one) */
 241     static const int rewindKey;      /**< key-code for a multimedia 'rewind' key, (not all keyboards will have one) */
 242
 243 private:
 244     //==============================================================================
 245     int keyCode;
 246     ModifierKeys mods;
 247     juce_wchar textCharacter;
 248
 249     JUCE_LEAK_DETECTOR (KeyPress);
 250 };
 251
 252
 253 #endif   // __JUCE_KEYPRESS_JUCEHEADER__