1wxKeyEvent(3)              Erlang Module Definition              wxKeyEvent(3)
2
3
4

NAME

6       wxKeyEvent - Functions for wxKeyEvent class
7

DESCRIPTION

9       This  event  class  contains  information  about  key press and release
10       events.
11
12       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
26       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
40       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
46       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
51       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
55       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
62       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
75       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
79       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
91       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
95       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
104       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
109       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
115       See: wxKeyboardState (not implemented in wx)
116
117       This class is derived (and can use functions) from: wxEvent
118
119       wxWidgets docs: wxKeyEvent
120

EVENTS

122       Use  wxEvtHandler:connect/3  with wxKeyEventType to subscribe to events
123       of this type.
124

DATA TYPES

126       wxKeyEvent() = wx:wx_object()
127
128       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
141       wxKeyEventType() = char | char_hook | key_down | key_up
142

EXPORTS

144       altDown(This) -> boolean()
145
146              Types:
147
148                 This = wxKeyEvent()
149
150              Returns true if the Alt key is pressed.
151
152              Notice that getModifiers/1 should usually  be  used  instead  of
153              this one.
154
155       cmdDown(This) -> boolean()
156
157              Types:
158
159                 This = wxKeyEvent()
160
161              Returns  true  if  the  key  used  for  command  accelerators is
162              pressed.
163
164              Same as controlDown/1. Deprecated.
165
166              Notice that getModifiers/1 should usually  be  used  instead  of
167              this one.
168
169       controlDown(This) -> boolean()
170
171              Types:
172
173                 This = wxKeyEvent()
174
175              Returns true if the Control key or Apple/Command key under macOS
176              is pressed.
177
178              This function doesn't distinguish between right and left control
179              keys.
180
181              Notice  that  getModifiers/1  should  usually be used instead of
182              this one.
183
184       getKeyCode(This) -> integer()
185
186              Types:
187
188                 This = wxKeyEvent()
189
190              Returns the key code of the key that generated this event.
191
192              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
197              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
205              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
210       getModifiers(This) -> integer()
211
212              Types:
213
214                 This = wxKeyEvent()
215
216              Return the bit mask of all pressed modifier keys.
217
218              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
225              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
230              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
235              with this function.
236
237       getPosition(This) -> {X :: integer(), Y :: integer()}
238
239              Types:
240
241                 This = wxKeyEvent()
242
243              Obtains  the  position  (in client coordinates) at which the key
244              was pressed.
245
246              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
250              x and y may be NULL  if  the  corresponding  coordinate  is  not
251              needed.
252
253       getRawKeyCode(This) -> integer()
254
255              Types:
256
257                 This = wxKeyEvent()
258
259              Returns the raw key code for this event.
260
261              The  flags are platform-dependent and should only be used if the
262              functionality provided by other wxKeyEvent methods  is  insuffi‐
263              cient.
264
265              Under  MSW, the raw key code is the value of wParam parameter of
266              the corresponding message.
267
268              Under GTK, the raw key code is the keyval field  of  the  corre‐
269              sponding GDK event.
270
271              Under macOS, the raw key code is the keyCode field of the corre‐
272              sponding NSEvent.
273
274              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
278       getRawKeyFlags(This) -> integer()
279
280              Types:
281
282                 This = wxKeyEvent()
283
284              Returns the low level key flags for this event.
285
286              The flags are platform-dependent and should only be used if  the
287              functionality  provided  by other wxKeyEvent methods is insuffi‐
288              cient.
289
290              Under MSW, the raw flags are just the value of lParam  parameter
291              of the corresponding message.
292
293              Under  GTK,  the raw flags contain the hardware_keycode field of
294              the corresponding GDK event.
295
296              Under macOS, the raw flags contain the modifiers state.
297
298              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
302       getUnicodeKey(This) -> integer()
303
304              Types:
305
306                 This = wxKeyEvent()
307
308              Returns the Unicode character corresponding to this key event.
309
310              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
314              This function is only available  in  Unicode  build,  i.e.  when
315              wxUSE_UNICODE is 1.
316
317       getX(This) -> integer()
318
319              Types:
320
321                 This = wxKeyEvent()
322
323              Returns the X position (in client coordinates) of the event.
324
325              See: getPosition/1
326
327       getY(This) -> integer()
328
329              Types:
330
331                 This = wxKeyEvent()
332
333              Returns the Y position (in client coordinates) of the event.
334
335              See: getPosition/1
336
337       hasModifiers(This) -> boolean()
338
339              Types:
340
341                 This = wxKeyEvent()
342
343              Returns true if Control or Alt are pressed.
344
345              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
349              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
355       metaDown(This) -> boolean()
356
357              Types:
358
359                 This = wxKeyEvent()
360
361              Returns true if the Meta/Windows/Apple key is pressed.
362
363              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
367              See: cmdDown/1
368
369       shiftDown(This) -> boolean()
370
371              Types:
372
373                 This = wxKeyEvent()
374
375              Returns true if the Shift key is pressed.
376
377              This  function  doesn't distinguish between right and left shift
378              keys.
379
380              Notice that getModifiers/1 should usually  be  used  instead  of
381              this one.
382
383
384
385wxWidgets team.                     wx 2.1                       wxKeyEvent(3)
Impressum