Commit | Line | Data |
---|---|---|
0e097789 VZ |
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 | ||
d4624460 | 18 | This class is implemented entirely inline in @<wx/kbdstate.h@> and thus has |
0e097789 VZ |
19 | no linking requirements. |
20 | ||
d4624460 | 21 | @nolibrary |
9e0ed083 | 22 | @category{events} |
0e097789 VZ |
23 | |
24 | @see wxKeyEvent, wxMouseState | |
25 | */ | |
26 | class wxKeyboardState | |
27 | { | |
28 | public: | |
29 | /** | |
ba4d737a | 30 | Constructor initializes the modifier key settings. |
0e097789 VZ |
31 | |
32 | By default, no modifiers are active. | |
33 | */ | |
0a98423e FM |
34 | wxKeyboardState(bool controlDown = false, |
35 | bool shiftDown = false, | |
36 | bool altDown = false, | |
37 | bool metaDown = false); | |
0e097789 VZ |
38 | |
39 | /** | |
40 | Return the bit mask of all pressed modifier keys. | |
0a98423e | 41 | |
0e097789 VZ |
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()) | |
d4624460 FM |
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. | |
0e097789 VZ |
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 is pressed. | |
81 | ||
82 | This function doesn't distinguish between right and left control keys. | |
83 | ||
84 | In portable code you usually want to use CmdDown() to automatically | |
85 | test for the more frequently used Command key (and not the rarely used | |
86 | Control one) under Mac. | |
87 | ||
88 | Notice that GetModifiers() should usually be used instead of this one. | |
89 | */ | |
90 | bool ControlDown() const; | |
91 | ||
92 | /** | |
93 | Returns true if the Shift key is pressed. | |
94 | ||
95 | This function doesn't distinguish between right and left shift keys. | |
96 | ||
97 | Notice that GetModifiers() should usually be used instead of this one. | |
98 | */ | |
99 | bool ShiftDown() const; | |
100 | ||
101 | /** | |
102 | Returns true if the Meta/Windows/Apple key is pressed. | |
103 | ||
104 | This function tests the state of the key traditionally called Meta | |
105 | under Unix systems, Windows keys under MSW and Apple, or Command, key | |
106 | under Mac. | |
107 | ||
108 | Notice that GetModifiers() should usually be used instead of this one. | |
109 | ||
110 | @see CmdDown() | |
111 | */ | |
112 | bool MetaDown() const; | |
113 | ||
114 | /** | |
115 | Returns true if the Alt key is pressed. | |
116 | ||
117 | Notice that GetModifiers() should usually be used instead of this one. | |
118 | */ | |
119 | bool AltDown() const; | |
120 | ||
121 | /** | |
122 | Returns true if the key used for command accelerators is pressed. | |
123 | ||
124 | @c Cmd is a pseudo key which is Control for PC and Unix platforms but | |
125 | Apple (or Command) key under Macs: it makes often sense to use it | |
126 | instead of ControlDown() because @c Command key is used for the same | |
127 | thing under Mac as @c Control elsewhere (even though @c Control still | |
128 | exists, it is usually not used for the same purpose under Mac). | |
129 | ||
130 | Notice that GetModifiers() should usually be used instead of this one. | |
131 | */ | |
132 | bool CmdDown() const; | |
133 | }; | |
134 |