- This event class contains information about keypress (character) events.
-
- Notice that there are three different kinds of keyboard events in wxWidgets:
- key down and up events and char events. The difference between the first two
- is clear - the first corresponds to a key press and the second to a key
- release - otherwise they are identical. Just note that if the key is
- maintained in a pressed state you will typically get a lot of (automatically
- generated) down events but only one up so it is wrong to assume that there is
- one up event corresponding to each down one.
-
- Both key events provide untranslated key codes while the char event carries
- the translated one. The untranslated code for alphanumeric keys is always
- an upper case value. For the other keys it is one of @c WXK_XXX values
- from the @ref page_keycodes.
- The translated key is, in general, the character the user expects to appear
- as the result of the key combination when typing the text into a text entry
- zone, for example.
-
- A few examples to clarify this (all assume that CAPS LOCK is unpressed
- and the standard US keyboard): when the @c 'A' key is pressed, the key down
- event key code is equal to @c ASCII A == 65. But the char event key code
- is @c ASCII a == 97. On the other hand, if you press both SHIFT and
- @c 'A' keys simultaneously , the key code in key down event will still be
- just @c 'A' while the char event key code parameter will now be @c 'A'
- as well.
-
- Although in this simple case it is clear that the correct key code could be
- found in the key down event handler by checking the value returned by
- wxKeyEvent::ShiftDown(), in general you should use @c EVT_CHAR for this as
- for non-alphanumeric keys the translation is keyboard-layout dependent and
- can only be done properly by the system itself.
-
- Another kind of translation is done when the control key is pressed: for
- example, for CTRL-A key press the key down event still carries the
- same key code @c 'a' as usual but the char event will have key code of 1,
- the ASCII value of this key combination.
-
- You may discover how the other keys on your system behave interactively by
- running the @ref page_samples_text wxWidgets sample and pressing some keys
- in any of the text controls shown in it.
-
- @b Tip: be sure to call @c event.Skip() for events that you don't process in
- key event function, otherwise menu shortcuts may cease to work under Windows.
+ This event class contains information about key press and release events.
+
+ The main information carried by this event is the key being pressed or
+ released. It can be accessed using either GetKeyCode() function or
+ GetUnicodeKey(). For the printable characters, the latter should be used as
+ it works for any keys, including non-Latin-1 characters that can be entered
+ when using national keyboard layouts. GetKeyCode() should be used to handle
+ special characters (such as cursor arrows keys or @c HOME or @c INS and so
+ on) which correspond to ::wxKeyCode enum elements above the @c WXK_START
+ constant. While GetKeyCode() also returns the character code for Latin-1
+ keys for compatibility, it doesn't work for Unicode characters in general
+ and will return @c WXK_NONE for any non-Latin-1 ones. For this reason, it's
+ recommended to always use GetUnicodeKey() and only fall back to GetKeyCode()
+ if GetUnicodeKey() returned @c WXK_NONE meaning that the event corresponds
+ to a non-printable special keys.
+
+ While both of these functions can be used with the events of @c
+ wxEVT_KEY_DOWN, @c wxEVT_KEY_UP and @c wxEVT_CHAR types, the values
+ returned by them are different for the first two events and the last one.
+ For the latter, the key returned corresponds to the character that would
+ appear in e.g. a text zone if the user pressed the key in it. As such, its
+ value depends on the current state of the Shift key and, for the letters,
+ on the state of Caps Lock modifier. For example, if @c A key is pressed
+ without Shift being held down, wxKeyEvent of type @c wxEVT_CHAR generated
+ for this key press will return (from either GetKeyCode() or GetUnicodeKey()
+ as their meanings coincide for ASCII characters) key code of 97
+ corresponding the ASCII value of @c a. And if the same key is pressed but
+ with Shift being held (or Caps Lock being active), then the key could would
+ be 65, i.e. ASCII value of capital @c A.
+
+ However for the key down and up events the returned key code will instead
+ be @c A independently of the state of the modifier keys i.e. it depends
+ only on physical key being pressed and is not translated to its logical
+ representation using the current keyboard state. Such untranslated key
+ codes are defined as follows:
+ - For the letters they correspond to the @e upper case value of the
+ letter.
+ - For the other alphanumeric keys (e.g. @c 7 or @c +), the untranslated
+ key code corresponds to the character produced by the key when it is
+ pressed without Shift. E.g. in standard US keyboard layout the
+ untranslated key code for the key @c =/+ in the upper right corner of
+ the keyboard is 61 which is the ASCII value of @c =.
+ - For the rest of the keys (i.e. special non-printable keys) it is the
+ same as the normal key code as no translation is used anyhow.
+
+ Notice that the first rule applies to all Unicode letters, not just the
+ usual Latin-1 ones. However for non-Latin-1 letters only GetUnicodeKey()
+ can be used to retrieve the key code as GetKeyCode() just returns @c
+ WXK_NONE in this case.
+
+ To summarize: you should handle @c wxEVT_CHAR if you need the translated
+ key and @c wxEVT_KEY_DOWN if you only need the value of the key itself,
+ independent of the current keyboard state.
+
+ @note Not all key down events may be generated by the user. As an example,
+ @c wxEVT_KEY_DOWN with @c = key code can be generated using the
+ standard US keyboard layout but not using the German one because the @c
+ = key corresponds to Shift-0 key combination in this layout and the key
+ code for it is @c 0, not @c =. Because of this you should avoid
+ requiring your users to type key events that might be impossible to
+ enter on their keyboard.
+
+
+ Another difference between key and char events is that another kind of
+ translation is done for the latter ones when the Control key is pressed:
+ char events for ASCII letters in this case carry codes corresponding to the
+ ASCII value of Ctrl-Latter, i.e. 1 for Ctrl-A, 2 for Ctrl-B and so on until
+ 26 for Ctrl-Z. This is convenient for terminal-like applications and can be
+ completely ignored by all the other ones (if you need to handle Ctrl-A it
+ is probably a better idea to use the key event rather than the char one).
+ Notice that currently no translation is done for the presses of @c [, @c
+ \\, @c ], @c ^ and @c _ keys which might be mapped to ASCII values from 27
+ to 31.
+
+ Finally, modifier keys only generate key events but no char events at all.
+ The modifiers keys are @c WXK_SHIFT, @c WXK_CONTROL, @c WXK_ALT and various
+ @c WXK_WINDOWS_XXX from ::wxKeyCode enum.
+
+ Modifier keys events are special in one additional aspect: usually the
+ keyboard state associated with a key press is well defined, e.g.
+ wxKeyboardState::ShiftDown() returns @c true only if the Shift key was held
+ pressed when the key that generated this event itself was pressed. There is
+ an ambiguity for the key press events for Shift key itself however. By
+ convention, it is considered to be already pressed when it is pressed and
+ already released when it is released. In other words, @c wxEVT_KEY_DOWN
+ event for the Shift key itself will have @c wxMOD_SHIFT in GetModifiers()
+ and ShiftDown() will return true while the @c wxEVT_KEY_UP event for Shift
+ itself will not have @c wxMOD_SHIFT in its modifiers and ShiftDown() will
+ return false.
+
+
+ @b Tip: You may discover the key codes and modifiers generated by all the
+ keys on your system interactively by running the @ref
+ page_samples_keyboard wxWidgets sample and pressing some keys in it.
projects / wxWidgets.git / blobdiff