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