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