1wxKeyEvent(3) Erlang Module Definition wxKeyEvent(3)
2
6 wxKeyEvent - Functions for wxKeyEvent class
7
9 This event class contains information about key press and release
10 events.
11 The main information carried by this event is the key being pressed or
13 released. It can be accessed using either getKeyCode/1 function or
14 getUnicodeKey/1. For the printable characters, the latter should be
15 used as it works for any keys, including non-Latin-1 characters that
16 can be entered when using national keyboard layouts. getKeyCode/1
17 should be used to handle special characters (such as cursor arrows keys
18 or HOME or INS and so on) which correspond to ?wxKeyCode enum elements
19 above the WXK_START constant. While getKeyCode/1 also returns the char‐
20 acter code for Latin-1 keys for compatibility, it doesn't work for Uni‐
21 code characters in general and will return WXK_NONE for any non-Latin-1
22 ones. For this reason, it's recommended to always use getUnicodeKey/1
23 and only fall back to getKeyCode/1 if getUnicodeKey/1 returned WXK_NONE
24 meaning that the event corresponds to a non-printable special keys.
25 While both of these functions can be used with the events of wx‐
27 EVT_KEY_DOWN, wxEVT_KEY_UP and wxEVT_CHAR types, the values returned by
28 them are different for the first two events and the last one. For the
29 latter, the key returned corresponds to the character that would appear
30 in e.g. a text zone if the user pressed the key in it. As such, its
31 value depends on the current state of the Shift key and, for the let‐
32 ters, on the state of Caps Lock modifier. For example, if A key is
33 pressed without Shift being held down, wxKeyEvent of type wxEVT_CHAR
34 generated for this key press will return (from either getKeyCode/1 or
35 getUnicodeKey/1 as their meanings coincide for ASCII characters) key
36 code of 97 corresponding the ASCII value of a. And if the same key is
37 pressed but with Shift being held (or Caps Lock being active), then the
38 key could would be 65, i.e. ASCII value of capital A.
39 However for the key down and up events the returned key code will in‐
41 stead be A independently of the state of the modifier keys i.e. it de‐
42 pends only on physical key being pressed and is not translated to its
43 logical representation using the current keyboard state. Such untrans‐
44 lated key codes are defined as follows:
45 Notice that the first rule applies to all Unicode letters, not just the
47 usual Latin-1 ones. However for non-Latin-1 letters only getUni‐
48 codeKey/1 can be used to retrieve the key code as getKeyCode/1 just re‐
49 turns WXK_NONE in this case.
50 To summarize: you should handle wxEVT_CHAR if you need the translated
52 key and wxEVT_KEY_DOWN if you only need the value of the key itself,
53 independent of the current keyboard state.
54 Note: Not all key down events may be generated by the user. As an exam‐
56 ple, wxEVT_KEY_DOWN with = key code can be generated using the standard
57 US keyboard layout but not using the German one because the = key cor‐
58 responds to Shift-0 key combination in this layout and the key code for
59 it is 0, not =. Because of this you should avoid requiring your users
60 to type key events that might be impossible to enter on their keyboard.
61 Another difference between key and char events is that another kind of
63 translation is done for the latter ones when the Control key is
64 pressed: char events for ASCII letters in this case carry codes corre‐
65 sponding to the ASCII value of Ctrl-Latter, i.e. 1 for Ctrl-A, 2 for
66 Ctrl-B and so on until 26 for Ctrl-Z. This is convenient for terminal-
67 like applications and can be completely ignored by all the other ones
68 (if you need to handle Ctrl-A it is probably a better idea to use the
69 key event rather than the char one). Notice that currently no transla‐
70 tion is done for the presses of [, \, ], ^ and _ keys which might be
71 mapped to ASCII values from 27 to 31. Since version 2.9.2, the enum
72 values WXK_CONTROL_A - WXK_CONTROL_Z can be used instead of the non-de‐
73 scriptive constant values 1-26.
74 Finally, modifier keys only generate key events but no char events at
76 all. The modifiers keys are WXK_SHIFT, WXK_CONTROL, WXK_ALT and various
77 WXK_WINDOWS_XXX from ?wxKeyCode enum.
78 Modifier keys events are special in one additional aspect: usually the
80 keyboard state associated with a key press is well defined, e.g. shift‐
81 Down/1 returns true only if the Shift key was held pressed when the key
82 that generated this event itself was pressed. There is an ambiguity for
83 the key press events for Shift key itself however. By convention, it is
84 considered to be already pressed when it is pressed and already re‐
85 leased when it is released. In other words, wxEVT_KEY_DOWN event for
86 the Shift key itself will have wxMOD_SHIFT in getModifiers/1 and shift‐
87 Down/1 will return true while the wxEVT_KEY_UP event for Shift itself
88 will not have wxMOD_SHIFT in its modifiers and shiftDown/1 will return
89 false.
90 Tip: You may discover the key codes and modifiers generated by all the
92 keys on your system interactively by running the page_samples_keyboard
93 wxWidgets sample and pressing some keys in it.
94 Note: If a key down (EVT_KEY_DOWN) event is caught and the event han‐
96 dler does not call event.Skip() then the corresponding char event
97 (EVT_CHAR) will not happen. This is by design and enables the programs
98 that handle both types of events to avoid processing the same key
99 twice. As a consequence, if you do not want to suppress the wxEVT_CHAR
100 events for the keys you handle, always call event.Skip() in your wx‐
101 EVT_KEY_DOWN handler. Not doing may also prevent accelerators defined
102 using this key from working.
103 Note: If a key is maintained in a pressed state, you will typically get
105 a lot of (automatically generated) key down events but only one key up
106 one at the end when the key is released so it is wrong to assume that
107 there is one up event corresponding to each down one.
108 Note: For Windows programmers: The key and char events in wxWidgets are
110 similar to but slightly different from Windows WM_KEYDOWN and WM_CHAR
111 events. In particular, Alt-x combination will generate a char event in
112 wxWidgets (unless it is used as an accelerator) and almost all keys,
113 including ones without ASCII equivalents, generate char events too.
114 See: wxKeyboardState (not implemented in wx)
116 This class is derived (and can use functions) from: wxEvent
118 wxWidgets docs: wxKeyEvent
120
122 Use wxEvtHandler:connect/3 with wxKeyEventType to subscribe to events
123 of this type.
124
126 wxKeyEvent() = wx:wx_object()
127 wxKey() =
129 #wxKey{type = wxKeyEvent:wxKeyEventType(),
130 x = integer(),
131 y = integer(),
132 keyCode = integer(),
133 controlDown = boolean(),
134 shiftDown = boolean(),
135 altDown = boolean(),
136 metaDown = boolean(),
137 uniChar = integer(),
138 rawCode = integer(),
139 rawFlags = integer()}
140 wxKeyEventType() = char | char_hook | key_down | key_up
142
144 altDown(This) -> boolean()
145 Types:
147 This = wxKeyEvent()
149 Returns true if the Alt key is pressed.
151 Notice that getModifiers/1 should usually be used instead of
153 this one.
154 cmdDown(This) -> boolean()
156 Types:
158 This = wxKeyEvent()
160 Returns true if the key used for command accelerators is
162 pressed.
163 Same as controlDown/1. Deprecated.
165 Notice that getModifiers/1 should usually be used instead of
167 this one.
168 controlDown(This) -> boolean()
170 Types:
172 This = wxKeyEvent()
174 Returns true if the Control key or Apple/Command key under macOS
176 is pressed.
177 This function doesn't distinguish between right and left control
179 keys.
180 Notice that getModifiers/1 should usually be used instead of
182 this one.
183 getKeyCode(This) -> integer()
185 Types:
187 This = wxKeyEvent()
189 Returns the key code of the key that generated this event.
191 ASCII symbols return normal ASCII values, while events from spe‐
193 cial keys such as "left cursor arrow" (WXK_LEFT) return values
194 outside of the ASCII range. See ?wxKeyCode for a full list of
195 the virtual key codes.
196 Note that this method returns a meaningful value only for spe‐
198 cial non-alphanumeric keys or if the user entered a Latin-1
199 character (this includes ASCII and the accented letters found in
200 Western European languages but not letters of other alphabets
201 such as e.g. Cyrillic). Otherwise it simply method returns
202 WXK_NONE and getUnicodeKey/1 should be used to obtain the corre‐
203 sponding Unicode character.
204 Using getUnicodeKey/1 is in general the right thing to do if you
206 are interested in the characters typed by the user, getKeyCode/1
207 should be only used for special keys (for which getUnicodeKey/1
208 returns WXK_NONE). To handle both kinds of keys you might write:
209 getModifiers(This) -> integer()
211 Types:
213 This = wxKeyEvent()
215 Return the bit mask of all pressed modifier keys.
217 The return value is a combination of wxMOD_ALT, wxMOD_CONTROL,
219 wxMOD_SHIFT and wxMOD_META bit masks. Additionally, wxMOD_NONE
220 is defined as 0, i.e. corresponds to no modifiers (see HasAny‐
221 Modifiers() (not implemented in wx)) and wxMOD_CMD is either wx‐
222 MOD_CONTROL (MSW and Unix) or wxMOD_META (Mac), see cmdDown/1.
223 See ?wxKeyModifier for the full list of modifiers.
224 Notice that this function is easier to use correctly than, for
226 example, controlDown/1 because when using the latter you also
227 have to remember to test that none of the other modifiers is
228 pressed:
229 and forgetting to do it can result in serious program bugs (e.g.
231 program not working with European keyboard layout where AltGr
232 key which is seen by the program as combination of CTRL and ALT
233 is used). On the other hand, you can simply write:
234 with this function.
236 getPosition(This) -> {X :: integer(), Y :: integer()}
238 Types:
240 This = wxKeyEvent()
242 Obtains the position (in client coordinates) at which the key
244 was pressed.
245 Notice that under most platforms this position is simply the
247 current mouse pointer position and has no special relationship
248 to the key event itself.
249 x and y may be NULL if the corresponding coordinate is not
251 needed.
252 getRawKeyCode(This) -> integer()
254 Types:
256 This = wxKeyEvent()
258 Returns the raw key code for this event.
260 The flags are platform-dependent and should only be used if the
262 functionality provided by other wxKeyEvent methods is insuffi‐
263 cient.
264 Under MSW, the raw key code is the value of wParam parameter of
266 the corresponding message.
267 Under GTK, the raw key code is the keyval field of the corre‐
269 sponding GDK event.
270 Under macOS, the raw key code is the keyCode field of the corre‐
272 sponding NSEvent.
273 Note: Currently the raw key codes are not supported by all
275 ports, use #ifdef wxHAS_RAW_KEY_CODES to determine if this fea‐
276 ture is available.
277 getRawKeyFlags(This) -> integer()
279 Types:
281 This = wxKeyEvent()
283 Returns the low level key flags for this event.
285 The flags are platform-dependent and should only be used if the
287 functionality provided by other wxKeyEvent methods is insuffi‐
288 cient.
289 Under MSW, the raw flags are just the value of lParam parameter
291 of the corresponding message.
292 Under GTK, the raw flags contain the hardware_keycode field of
294 the corresponding GDK event.
295 Under macOS, the raw flags contain the modifiers state.
297 Note: Currently the raw key flags are not supported by all
299 ports, use #ifdef wxHAS_RAW_KEY_CODES to determine if this fea‐
300 ture is available.
301 getUnicodeKey(This) -> integer()
303 Types:
305 This = wxKeyEvent()
307 Returns the Unicode character corresponding to this key event.
309 If the key pressed doesn't have any character value (e.g. a cur‐
311 sor key) this method will return WXK_NONE. In this case you
312 should use getKeyCode/1 to retrieve the value of the key.
313 This function is only available in Unicode build, i.e. when
315 wxUSE_UNICODE is 1.
316 getX(This) -> integer()
318 Types:
320 This = wxKeyEvent()
322 Returns the X position (in client coordinates) of the event.
324 See: getPosition/1
326 getY(This) -> integer()
328 Types:
330 This = wxKeyEvent()
332 Returns the Y position (in client coordinates) of the event.
334 See: getPosition/1
336 hasModifiers(This) -> boolean()
338 Types:
340 This = wxKeyEvent()
342 Returns true if Control or Alt are pressed.
344 Checks if Control, Alt or, under macOS only, Command key are
346 pressed (notice that the real Control key is still taken into
347 account under OS X too).
348 This method returns false if only Shift is pressed for compati‐
350 bility reasons and also because pressing Shift usually doesn't
351 change the interpretation of key events, see HasAnyModifiers()
352 (not implemented in wx) if you want to take Shift into account
353 as well.
354 metaDown(This) -> boolean()
356 Types:
358 This = wxKeyEvent()
360 Returns true if the Meta/Windows/Apple key is pressed.
362 This function tests the state of the key traditionally called
364 Meta under Unix systems, Windows keys under MSW Notice that get‐
365 Modifiers/1 should usually be used instead of this one.
366 See: cmdDown/1
368 shiftDown(This) -> boolean()
370 Types:
372 This = wxKeyEvent()
374 Returns true if the Shift key is pressed.
376 This function doesn't distinguish between right and left shift
378 keys.
379 Notice that getModifiers/1 should usually be used instead of
381 this one.
382wxWidgets team. wx 2.1 wxKeyEvent(3)