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         Constructor initializes the modifier key settings.
  30
  31         By default, no modifiers are active.
  32      */
  33     wxKeyboardState(bool controlDown,
  34                     bool shiftDown,
  35                     bool altDown,
  36                     bool metaDown);
  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 HasModifiers())
  44         and @c wxMOD_CMD is either @c wxMOD_CONTROL (MSW and Unix) or @c
  45         wxMOD_META (Mac), see CmdDown(). See @ref page_keymodifiers for the
  46         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     bool HasModifiers() const;
  77
  78     /**
  79         Returns true if the Control key is pressed.
  80
  81         This function doesn't distinguish between right and left control keys.
  82
  83         In portable code you usually want to use CmdDown() to automatically
  84         test for the more frequently used Command key (and not the rarely used
  85         Control one) under Mac.
  86
  87         Notice that GetModifiers() should usually be used instead of this one.
  88      */
  89     bool ControlDown() const;
  90
  91     /**
  92         Returns true if the Shift key is pressed.
  93
  94         This function doesn't distinguish between right and left shift keys.
  95
  96         Notice that GetModifiers() should usually be used instead of this one.
  97      */
  98     bool ShiftDown() const;
  99
 100     /**
 101         Returns true if the Meta/Windows/Apple key is pressed.
 102
 103         This function tests the state of the key traditionally called Meta
 104         under Unix systems, Windows keys under MSW and Apple, or Command, key
 105         under Mac.
 106
 107         Notice that GetModifiers() should usually be used instead of this one.
 108
 109         @see CmdDown()
 110      */
 111     bool MetaDown() const;
 112
 113     /**
 114         Returns true if the Alt key is pressed.
 115
 116         Notice that GetModifiers() should usually be used instead of this one.
 117      */
 118     bool AltDown() const;
 119
 120     /**
 121         Returns true if the key used for command accelerators is pressed.
 122
 123         @c Cmd is a pseudo key which is Control for PC and Unix platforms but
 124         Apple (or Command) key under Macs: it makes often sense to use it
 125         instead of ControlDown() because @c Command key is used for the same
 126         thing under Mac as @c Control elsewhere (even though @c Control still
 127         exists, it is usually not used for the same purpose under Mac).
 128
 129         Notice that GetModifiers() should usually be used instead of this one.
 130      */
 131     bool CmdDown() const;
 132 };
 133