interface/wx/kbdstate.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/kbdstate.h
   3 // Purpose:     documentation of wxKeyboardState
   4 // Author:      wxWidgets team
   5 // Created:     2008-09-19
   6 // RCS-ID:      $Id$
   7 // Licence:     wxWindows licence
   8 /////////////////////////////////////////////////////////////////////////////
   9
  10 /**
  11     Provides methods for testing the state of the keyboard modifier keys.
  12
  13     This class is used as a base class of wxKeyEvent and wxMouseState and,
  14     hence, indirectly, of wxMouseEvent, so its methods may be used to get
  15     information about the modifier keys which were pressed when the event
  16     occurred.
  17
  18     This class is implemented entirely inline in @<wx/kbdstate.h@> and thus has
  19     no linking requirements.
  20
  21     @nolibrary
  22     @category{events}
  23
  24     @see wxKeyEvent, wxMouseState
  25  */
  26 class wxKeyboardState
  27 {
  28 public:
  29     /**
  30         Constructor initializes the modifier key settings.
  31
  32         By default, no modifiers are active.
  33      */
  34     wxKeyboardState(bool controlDown = false,
  35                     bool shiftDown = false,
  36                     bool altDown = false,
  37                     bool metaDown = false);
  38
  39     /**
  40         Return the bit mask of all pressed modifier keys.
  41
  42         The return value is a combination of @c wxMOD_ALT, @c wxMOD_CONTROL,
  43         @c wxMOD_SHIFT and @c wxMOD_META bit masks. Additionally, @c wxMOD_NONE
  44         is defined as 0, i.e. corresponds to no modifiers (see HasAnyModifiers())
  45         and @c wxMOD_CMD is either @c wxMOD_CONTROL (MSW and Unix) or
  46         @c wxMOD_META (Mac), see CmdDown().
  47         See ::wxKeyModifier for the full list of modifiers.
  48
  49         Notice that this function is easier to use correctly than, for example,
  50         ControlDown() because when using the latter you also have to remember to
  51         test that none of the other modifiers is pressed:
  52
  53         @code
  54         if ( ControlDown() && !AltDown() && !ShiftDown() && !MetaDown() )
  55             ... handle Ctrl-XXX ...
  56         @endcode
  57
  58         and forgetting to do it can result in serious program bugs (e.g. program
  59         not working with European keyboard layout where @c AltGr key which is
  60         seen by the program as combination of CTRL and ALT is used). On the
  61         other hand, you can simply write:
  62
  63         @code
  64         if ( GetModifiers() == wxMOD_CONTROL )
  65             ... handle Ctrl-XXX ...
  66         @endcode
  67
  68         with this function.
  69     */
  70     int GetModifiers() const;
  71
  72     /**
  73         Returns true if any modifiers at all are pressed.
  74
  75         This is equivalent to @c GetModifiers() @c != @c wxMOD_NONE.
  76
  77         Notice that this is different from HasModifiers() method which doesn't
  78         take e.g. Shift modifier into account. This method is most suitable for
  79         mouse events when any modifier, including Shift, can change the
  80         interpretation of the event.
  81
  82         @since 2.9.5
  83      */
  84     bool HasAnyModifiers() const;
  85
  86     /**
  87         Returns true if Control or Alt are pressed.
  88
  89         Checks if Control, Alt or, under OS X only, Command key are pressed
  90         (notice that the real Control key is still taken into account under OS
  91         X too).
  92
  93         This method returns @false if only Shift is pressed for compatibility
  94         reasons and also because pressing Shift usually doesn't change the
  95         interpretation of key events, see HasAnyModifiers() if you want to
  96         take Shift into account as well.
  97      */
  98     bool HasModifiers() const;
  99
 100     /**
 101         Returns true if the Control key or Apple/Command key under OS X is pressed.
 102
 103         This function doesn't distinguish between right and left control keys.
 104
 105         Notice that GetModifiers() should usually be used instead of this one.
 106      */
 107     bool ControlDown() const;
 108
 109     /**
 110         Returns true if the Control key (also under OS X).
 111
 112         This function doesn't distinguish between right and left control keys.
 113
 114         Notice that GetModifiers() should usually be used instead of this one.
 115      */
 116     bool RawControlDown() const;
 117
 118     /**
 119         Returns true if the Shift key is pressed.
 120
 121         This function doesn't distinguish between right and left shift keys.
 122
 123         Notice that GetModifiers() should usually be used instead of this one.
 124      */
 125     bool ShiftDown() const;
 126
 127     /**
 128         Returns true if the Meta/Windows/Apple key is pressed.
 129
 130         This function tests the state of the key traditionally called Meta
 131         under Unix systems, Windows keys under MSW
 132         Notice that GetModifiers() should usually be used instead of this one.
 133
 134         @see CmdDown()
 135      */
 136     bool MetaDown() const;
 137
 138     /**
 139         Returns true if the Alt key is pressed.
 140
 141         Notice that GetModifiers() should usually be used instead of this one.
 142      */
 143     bool AltDown() const;
 144
 145     /**
 146         Returns true if the key used for command accelerators is pressed. Same as
 147         ControlDown(). Deprecated.
 148
 149         Notice that GetModifiers() should usually be used instead of this one.
 150      */
 151     bool CmdDown() const;
 152
 153
 154     void SetControlDown(bool down);
 155     void SetRawControlDown(bool down);
 156     void SetShiftDown(bool down);
 157     void SetAltDown(bool down);
 158     void SetMetaDown(bool down);
 159
 160 };
 161