]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/keyevent.tex
changed wxCondition API to take a reference, not pointer, to wxMutex
[wxWidgets.git] / docs / latex / wx / keyevent.tex
CommitLineData
a660d684
KB
1\section{\class{wxKeyEvent}}\label{wxkeyevent}
2
4ce81a75 3This event class contains information about keypress (character) events.
a660d684 4
f17393f1
VZ
5Notice that there are three different kinds of keyboard events in wxWindows:
6key down and up events and char events. The difference between the first two
7is clear - the first corresponds to a key press and the second to a key
8release - otherwise they are identical. Just note that if the key is
9maintained in a pressed state you will typically get a lot of (automatically
68304caf 10generated) down events but only one up so it is wrong to assume that there is
f17393f1
VZ
11one up event corresponding to each down one.
12
13Both key events provide untranslated key codes while the char event carries
14the translated one. The untranslated code for alphanumeric keys is always
15an upper case value. For the other keys it is one of {\tt WXK\_XXX} values
16from the \helpref{keycodes table}{keycodes}. The translated key is, in
17general, the character the user expects to appear as the result of the key
18combination when typing the text into a text entry zone, for example.
19
68304caf
RD
20If the key up event is caught and the event handler does not call
21event.Skip() then the coresponding char event will not happen. This
22is by design and enables the programs that handle both types of events
23to be a bit simpler.
24
f17393f1
VZ
25A few examples to clarify this (all assume that {\sc Caps Lock} is unpressed
26and the standard US keyboard): when the {\tt 'A'} key is pressed, the key down
27event key code is equal to {\tt ASCII A} $== 65$. But the char event key code
28is {\tt ASCII a} $== 97$. On the other hand, if you press both {\sc Shift} and
29{\tt 'A'} keys simultaneously , the key code in key down event will still be
68304caf 30just {\tt 'A'} while the char event key code parameter will now be {\tt 'A'}
f17393f1
VZ
31as well.
32
33Although in this simple case it is clear that the correct key code could be
68304caf
RD
34found in the key down event handler by checking the value returned by
35\helpref{ShiftDown()}{wxkeyeventshiftdown}, in general you should use
f17393f1
VZ
36{\tt EVT\_CHAR} for this as for non alphanumeric keys the translation is
37keyboard-layout dependent and can only be done properly by the system itself.
38
39Another kind of translation is done when the control key is pressed: for
40example, for {\sc Ctrl-A} key press the key down event still carries the
41same key code {\tt 'a'} as usual but the char event will have key code of
42$1$, the ASCII value of this key combination.
43
44You may discover how the other keys on your system behave interactively by
45running the \helpref{text}{sampletext} wxWindows sample and pressing some keys
46in any of the text controls shown in it.
47
48{\bf Note for Windows programmers:} The key and char events in wxWindows are
68304caf 49similar to but slightly different from Windows {\tt WM\_KEYDOWN} and
f17393f1
VZ
50{\tt WM\_CHAR} events. In particular, Alt-x combination will generate a char
51event in wxWindows (unless it is used as an acclerator).
52
a660d684
KB
53\wxheading{Derived from}
54
55\helpref{wxEvent}{wxevent}
56
954b8ae6
JS
57\wxheading{Include files}
58
59<wx/event.h>
60
a660d684
KB
61\wxheading{Event table macros}
62
63To process a key event, use these event handler macros to direct input to member
64functions that take a wxKeyEvent argument.
65
66\twocolwidtha{7cm}
67\begin{twocollist}\itemsep=0pt
4ce81a75
JS
68\twocolitem{{\bf EVT\_KEY\_DOWN(func)}}{Process a wxEVT\_KEY\_DOWN event (any key has been pressed).}
69\twocolitem{{\bf EVT\_KEY\_UP(func)}}{Process a wxEVT\_KEY\_UP event (any key has been released).}
a660d684 70\twocolitem{{\bf EVT\_CHAR(func)}}{Process a wxEVT\_CHAR event.}
f17393f1 71%\twocolitem{{\bf EVT\_CHAR\_HOOK(func)}}{Process a wxEVT\_CHAR\_HOOK event.}
a660d684
KB
72\end{twocollist}%
73
4ce81a75 74
a660d684
KB
75\latexignore{\rtfignore{\wxheading{Members}}}
76
77\membersection{wxKeyEvent::m\_altDown}
78
79\member{bool}{m\_altDown}
80
81TRUE if the Alt key is pressed down.
82
83\membersection{wxKeyEvent::m\_controlDown}
84
85\member{bool}{m\_controlDown}
86
87TRUE if control is pressed down.
88
89\membersection{wxKeyEvent::m\_keyCode}
90
91\member{long}{m\_keyCode}
92
3972fb49 93Virtual keycode. See \helpref{Keycodes}{keycodes} for a list of identifiers.
a660d684
KB
94
95\membersection{wxKeyEvent::m\_metaDown}
96
97\member{bool}{m\_metaDown}
98
99TRUE if the Meta key is pressed down.
100
101\membersection{wxKeyEvent::m\_shiftDown}
102
103\member{bool}{m\_shiftDown}
104
105TRUE if shift is pressed down.
106
107\membersection{wxKeyEvent::m\_x}
108
109\member{int}{m\_x}
110
111X position of the event.
112
113\membersection{wxKeyEvent::m\_y}
114
115\member{int}{m\_y}
116
117Y position of the event.
118
119\membersection{wxKeyEvent::wxKeyEvent}
120
121\func{}{wxKeyEvent}{\param{WXTYPE}{ keyEventType}}
122
123Constructor. Currently, the only valid event types are wxEVT\_CHAR and wxEVT\_CHAR\_HOOK.
124
125\membersection{wxKeyEvent::AltDown}
126
803ef874 127\constfunc{bool}{AltDown}{\void}
a660d684
KB
128
129Returns TRUE if the Alt key was down at the time of the key event.
130
131\membersection{wxKeyEvent::ControlDown}
132
803ef874 133\constfunc{bool}{ControlDown}{\void}
a660d684
KB
134
135Returns TRUE if the control key was down at the time of the key event.
136
f6bcfd97
BP
137\membersection{wxKeyEvent::GetKeyCode}
138
139\constfunc{int}{GetKeyCode}{\void}
140
141Returns the virtual key code. ASCII events return normal ASCII values,
142while non-ASCII events return values such as {\bf WXK\_LEFT} for the
143left cursor key. See \helpref{Keycodes}{keycodes} for a full list of the virtual key codes.
144
a660d684
KB
145\membersection{wxKeyEvent::GetX}
146
803ef874 147\constfunc{long}{GetX}{\void}
a660d684
KB
148
149Returns the X position of the event.
150
151\membersection{wxKeyEvent::GetY}
152
803ef874 153\constfunc{long}{GetY}{\void}
a660d684
KB
154
155Returns the Y position of the event.
156
a660d684
KB
157\membersection{wxKeyEvent::MetaDown}
158
803ef874 159\constfunc{bool}{MetaDown}{\void}
a660d684
KB
160
161Returns TRUE if the Meta key was down at the time of the key event.
162
803ef874 163\membersection{wxKeyEvent::GetPosition}
a660d684 164
803ef874
JS
165\constfunc{wxPoint}{GetPosition}{\void}
166
167\constfunc{void}{GetPosition}{\param{long *}{x}, \param{long *}{y}}
a660d684
KB
168
169Obtains the position at which the key was pressed.
170
f6bcfd97
BP
171\membersection{wxKeyEvent::HasModifiers}
172
173\constfunc{bool}{HasModifiers}{\void}
174
d11710cb 175Returns TRUE if either {\sc Ctrl} or {\sc Alt} keys was down
f6bcfd97 176at the time of the key event. Note that this function does not take into
d11710cb 177account neither {\sc Shift} nor {\sc Meta} key states (the reason for ignoring
68304caf 178the latter is that it is common for {\sc NumLock} key to be configured as
d11710cb
VZ
179{\sc Meta} under X but the key presses even while {\sc NumLock} is on should
180be still processed normally).
f6bcfd97 181
f17393f1 182\membersection{wxKeyEvent::ShiftDown}\label{wxkeyeventshiftdown}
a660d684 183
803ef874 184\constfunc{bool}{ShiftDown}{\void}
a660d684
KB
185
186Returns TRUE if the shift key was down at the time of the key event.
187
188