]> git.saurik.com Git - wxWidgets.git/blame_incremental - interface/wx/kbdstate.h
don't place NULL pointers in the GDK window array in GTKGetWindow()
[wxWidgets.git] / interface / wx / kbdstate.h
... / ...
CommitLineData
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/kbdstate.h@> and thus has
19 no linking requirements.
20
21 @category{misc}
22 @nolibrary
23
24 @see wxKeyEvent, wxMouseState
25 */
26class wxKeyboardState
27{
28public:
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 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