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 license
   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/keystate.h@> and thus has
  19     no linking requirements.
  20
  21     @category{misc}
  22
  23     @see wxKeyEvent, wxMouseState
  24  */
  25 class wxKeyboardState
  26 {
  27 public:
  28     /**
  29         Default constructor.
  30
  31         By default, no modifiers are active.
  32      */
  33     wxKeyboardState();
  34
  35     /**
  36         Return the bit mask of all pressed modifier keys.
  37
  38         The return value is a combination of @c wxMOD_ALT, @c wxMOD_CONTROL,
  39         @c wxMOD_SHIFT and @c wxMOD_META bit masks. Additionally, @c wxMOD_NONE
  40         is defined as 0, i.e. corresponds to no modifiers (see HasModifiers())
  41         and @c wxMOD_CMD is either @c wxMOD_CONTROL (MSW and Unix) or @c
  42         wxMOD_META (Mac), see CmdDown(). See @ref page_keymodifiers for the
  43         full list of modifiers.
  44
  45         Notice that this function is easier to use correctly than, for example,
  46         ControlDown() because when using the latter you also have to remember to
  47         test that none of the other modifiers is pressed:
  48
  49         @code
  50         if ( ControlDown() && !AltDown() && !ShiftDown() && !MetaDown() )
  51             ... handle Ctrl-XXX ...
  52         @endcode
  53
  54         and forgetting to do it can result in serious program bugs (e.g. program
  55         not working with European keyboard layout where @c AltGr key which is
  56         seen by the program as combination of CTRL and ALT is used). On the
  57         other hand, you can simply write:
  58
  59         @code
  60         if ( GetModifiers() == wxMOD_CONTROL )
  61             ... handle Ctrl-XXX ...
  62         @endcode
  63
  64         with this function.
  65     */
  66     int GetModifiers() const;
  67
  68     /**
  69         Returns true if any modifiers at all are pressed.
  70
  71         This is equivalent to @c GetModifiers() @c != @c wxMOD_NONE.
  72      */
  73     bool HasModifiers() const;
  74
  75     /**
  76         Returns true if the Control key is pressed.
  77
  78         This function doesn't distinguish between right and left control keys.
  79
  80         In portable code you usually want to use CmdDown() to automatically
  81         test for the more frequently used Command key (and not the rarely used
  82         Control one) under Mac.
  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 Shift key is pressed.
  90
  91         This function doesn't distinguish between right and left shift keys.
  92
  93         Notice that GetModifiers() should usually be used instead of this one.
  94      */
  95     bool ShiftDown() const;
  96
  97     /**
  98         Returns true if the Meta/Windows/Apple key is pressed.
  99
 100         This function tests the state of the key traditionally called Meta
 101         under Unix systems, Windows keys under MSW and Apple, or Command, key
 102         under Mac.
 103
 104         Notice that GetModifiers() should usually be used instead of this one.
 105
 106         @see CmdDown()
 107      */
 108     bool MetaDown() const;
 109
 110     /**
 111         Returns true if the Alt key is pressed.
 112
 113         Notice that GetModifiers() should usually be used instead of this one.
 114      */
 115     bool AltDown() const;
 116
 117     /**
 118         Returns true if the key used for command accelerators is pressed.
 119
 120         @c Cmd is a pseudo key which is Control for PC and Unix platforms but
 121         Apple (or Command) key under Macs: it makes often sense to use it
 122         instead of ControlDown() because @c Command key is used for the same
 123         thing under Mac as @c Control elsewhere (even though @c Control still
 124         exists, it is usually not used for the same purpose under Mac).
 125
 126         Notice that GetModifiers() should usually be used instead of this one.
 127      */
 128     bool CmdDown() const;
 129 };
 130