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 HasModifiers())
  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     bool HasModifiers() const;
  78
  79     /**
  80         Returns true if the Control key or Apple/Command key under OS X is pressed.
  81
  82         This function doesn't distinguish between right and left control keys.
  83
  84         Notice that GetModifiers() should usually be used instead of this one.
  85      */
  86     bool ControlDown() const;
  87
  88     /**
  89         Returns true if the Control key (also under OS X).
  90
  91         This function doesn't distinguish between right and left control keys.
  92
  93         Notice that GetModifiers() should usually be used instead of this one.
  94      */
  95     bool RawControlDown() const;
  96
  97     /**
  98         Returns true if the Shift key is pressed.
  99
 100         This function doesn't distinguish between right and left shift keys.
 101
 102         Notice that GetModifiers() should usually be used instead of this one.
 103      */
 104     bool ShiftDown() const;
 105
 106     /**
 107         Returns true if the Meta/Windows/Apple key is pressed.
 108
 109         This function tests the state of the key traditionally called Meta
 110         under Unix systems, Windows keys under MSW
 111         Notice that GetModifiers() should usually be used instead of this one.
 112
 113         @see CmdDown()
 114      */
 115     bool MetaDown() const;
 116
 117     /**
 118         Returns true if the Alt key is pressed.
 119
 120         Notice that GetModifiers() should usually be used instead of this one.
 121      */
 122     bool AltDown() const;
 123
 124     /**
 125         Returns true if the key used for command accelerators is pressed. Same as
 126         ControlDown(). Deprecated.
 127
 128         Notice that GetModifiers() should usually be used instead of this one.
 129      */
 130     bool CmdDown() const;
 131
 132
 133     void SetControlDown(bool down);
 134     void SetRawControlDown(bool down);
 135     void SetShiftDown(bool down);
 136     void SetAltDown(bool down);
 137     void SetMetaDown(bool down);
 138
 139 };
 140