docs/latex/wx/keyevent.tex

   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 wxWindows:
   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 up one 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} wxWindows sample and pressing some keys
  41 in any of the text controls shown in it.
  42
  43 {\bf Note for Windows programmers:} The key and char events in wxWindows are
  44 similar to but slightly different from Windows {\tt WM\_KEYDOWN} and
  45 {\tt WM\_CHAR} events. In particular, Alt-x combination will generate a char
  46 event in wxWindows (unless it is used as an acclerator).
  47
  48 \wxheading{Derived from}
  49
  50 \helpref{wxEvent}{wxevent}
  51
  52 \wxheading{Include files}
  53
  54 <wx/event.h>
  55
  56 \wxheading{Event table macros}
  57
  58 To process a key event, use these event handler macros to direct input to member
  59 functions that take a wxKeyEvent argument.
  60
  61 \twocolwidtha{7cm}
  62 \begin{twocollist}\itemsep=0pt
  63 \twocolitem{{\bf EVT\_KEY\_DOWN(func)}}{Process a wxEVT\_KEY\_DOWN event (any key has been pressed).}
  64 \twocolitem{{\bf EVT\_KEY\_UP(func)}}{Process a wxEVT\_KEY\_UP event (any key has been released).}
  65 \twocolitem{{\bf EVT\_CHAR(func)}}{Process a wxEVT\_CHAR event.}
  66 %\twocolitem{{\bf EVT\_CHAR\_HOOK(func)}}{Process a wxEVT\_CHAR\_HOOK event.}
  67 \end{twocollist}%
  68
  69 \wxheading{See also}
  70
  71 \helpref{wxWindow::OnChar}{wxwindowonchar},
  72 \helpref{wxWindow::OnCharHook}{wxwindowoncharhook},
  73 \helpref{wxWindow::OnKeyDown}{wxwindowonkeydown},
  74 \helpref{wxWindow::OnKeyUp}{wxwindowonkeyup}
  75
  76 \latexignore{\rtfignore{\wxheading{Members}}}
  77
  78 \membersection{wxKeyEvent::m\_altDown}
  79
  80 \member{bool}{m\_altDown}
  81
  82 TRUE if the Alt key is pressed down.
  83
  84 \membersection{wxKeyEvent::m\_controlDown}
  85
  86 \member{bool}{m\_controlDown}
  87
  88 TRUE if control is pressed down.
  89
  90 \membersection{wxKeyEvent::m\_keyCode}
  91
  92 \member{long}{m\_keyCode}
  93
  94 Virtual keycode. See \helpref{Keycodes}{keycodes} for a list of identifiers.
  95
  96 \membersection{wxKeyEvent::m\_metaDown}
  97
  98 \member{bool}{m\_metaDown}
  99
 100 TRUE if the Meta key is pressed down.
 101
 102 \membersection{wxKeyEvent::m\_shiftDown}
 103
 104 \member{bool}{m\_shiftDown}
 105
 106 TRUE if shift is pressed down.
 107
 108 \membersection{wxKeyEvent::m\_x}
 109
 110 \member{int}{m\_x}
 111
 112 X position of the event.
 113
 114 \membersection{wxKeyEvent::m\_y}
 115
 116 \member{int}{m\_y}
 117
 118 Y position of the event.
 119
 120 \membersection{wxKeyEvent::wxKeyEvent}
 121
 122 \func{}{wxKeyEvent}{\param{WXTYPE}{ keyEventType}}
 123
 124 Constructor. Currently, the only valid event types are wxEVT\_CHAR and wxEVT\_CHAR\_HOOK.
 125
 126 \membersection{wxKeyEvent::AltDown}
 127
 128 \constfunc{bool}{AltDown}{\void}
 129
 130 Returns TRUE if the Alt key was down at the time of the key event.
 131
 132 \membersection{wxKeyEvent::ControlDown}
 133
 134 \constfunc{bool}{ControlDown}{\void}
 135
 136 Returns TRUE if the control key was down at the time of the key event.
 137
 138 \membersection{wxKeyEvent::GetKeyCode}
 139
 140 \constfunc{int}{GetKeyCode}{\void}
 141
 142 Returns the virtual key code. ASCII events return normal ASCII values,
 143 while non-ASCII events return values such as {\bf WXK\_LEFT} for the
 144 left cursor key. See \helpref{Keycodes}{keycodes} for a full list of the virtual key codes.
 145
 146 \membersection{wxKeyEvent::GetX}
 147
 148 \constfunc{long}{GetX}{\void}
 149
 150 Returns the X position of the event.
 151
 152 \membersection{wxKeyEvent::GetY}
 153
 154 \constfunc{long}{GetY}{\void}
 155
 156 Returns the Y position of the event.
 157
 158 \membersection{wxKeyEvent::MetaDown}
 159
 160 \constfunc{bool}{MetaDown}{\void}
 161
 162 Returns TRUE if the Meta key was down at the time of the key event.
 163
 164 \membersection{wxKeyEvent::GetPosition}
 165
 166 \constfunc{wxPoint}{GetPosition}{\void}
 167
 168 \constfunc{void}{GetPosition}{\param{long *}{x}, \param{long *}{y}}
 169
 170 Obtains the position at which the key was pressed.
 171
 172 \membersection{wxKeyEvent::HasModifiers}
 173
 174 \constfunc{bool}{HasModifiers}{\void}
 175
 176 Returns TRUE if either {\sc Ctrl} or {\sc Alt} keys was down
 177 at the time of the key event. Note that this function does not take into
 178 account neither {\sc Shift} nor {\sc Meta} key states (the reason for ignoring
 179 the latter is that it is common for {\sc NumLock} key to be configured as
 180 {\sc Meta} under X but the key presses even while {\sc NumLock} is on should
 181 be still processed normally).
 182
 183 \membersection{wxKeyEvent::ShiftDown}\label{wxkeyeventshiftdown}
 184
 185 \constfunc{bool}{ShiftDown}{\void}
 186
 187 Returns TRUE if the shift key was down at the time of the key event.
 188
 189