1\section{\class{wxKeyEvent}}\label{wxkeyevent} 2 3This event class contains information about keypress (character) events. 4 5Notice that there are three different kinds of keyboard events in wxWidgets: 6key down and up events and char events. The difference between the first two 7is clear - the first corresponds to a key press and the second to a key 8release - otherwise they are identical. Just note that if the key is 9maintained in a pressed state you will typically get a lot of (automatically 10generated) down events but only one up so it is wrong to assume that there is 11one up event corresponding to each down one. 12 13Both key events provide untranslated key codes while the char event carries 14the translated one. The untranslated code for alphanumeric keys is always 15an upper case value. For the other keys it is one of {\tt WXK\_XXX} values 16from the \helpref{keycodes table}{keycodes}. The translated key is, in 17general, the character the user expects to appear as the result of the key 18combination when typing the text into a text entry zone, for example. 19 20A few examples to clarify this (all assume that {\sc Caps Lock} is unpressed 21and the standard US keyboard): when the {\tt 'A'} key is pressed, the key down 22event key code is equal to {\tt ASCII A} $== 65$. But the char event key code 23is {\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 25just {\tt 'A'} while the char event key code parameter will now be {\tt 'A'} 26as well. 27 28Although in this simple case it is clear that the correct key code could be 29found 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 32keyboard-layout dependent and can only be done properly by the system itself. 33 34Another kind of translation is done when the control key is pressed: for 35example, for {\sc Ctrl-A} key press the key down event still carries the 36same 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 39You may discover how the other keys on your system behave interactively by 40running the \helpref{text}{sampletext} wxWidgets sample and pressing some keys 41in any of the text controls shown in it. 42 43{\bf Note:} If a key down ({\tt EVT\_KEY\_DOWN}) event is caught and 44the event handler does not call {\tt event.Skip()} then the corresponding 45char event ({\tt EVT\_CHAR}) will not happen. This is by design and 46enables the programs that handle both types of events to be a bit 47simpler. 48 49{\bf Note for Windows programmers:} The key and char events in wxWidgets are 50similar to but slightly different from Windows {\tt WM\_KEYDOWN} and 51{\tt WM\_CHAR} events. In particular, Alt-x combination will generate a char 52event 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 55key 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 67To process a key event, use these event handler macros to direct input to member 68functions 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 82\membersection{wxKeyEvent::m\_altDown}\label{wxkeyeventmaltdown} 83 84\member{bool}{m\_altDown} 85 86\textbf{Deprecated: } Please use \helpref{GetModifiers}{wxkeyeventgetmodifiers} 87instead! 88 89true if the Alt key is pressed down. 90 91 92\membersection{wxKeyEvent::m\_controlDown}\label{wxkeyeventmcontroldown} 93 94\member{bool}{m\_controlDown} 95 96\textbf{Deprecated: } Please use \helpref{GetModifiers}{wxkeyeventgetmodifiers} 97instead! 98 99true if control is pressed down. 100 101 102\membersection{wxKeyEvent::m\_keyCode}\label{wxkeyeventmkeycode} 103 104\member{long}{m\_keyCode} 105 106\textbf{Deprecated: } Please use \helpref{GetKeyCode}{wxkeyeventgetkeycode} 107instead! 108 109Virtual keycode. See \helpref{Keycodes}{keycodes} for a list of identifiers. 110 111 112\membersection{wxKeyEvent::m\_metaDown}\label{wxkeyeventmmetadown} 113 114\member{bool}{m\_metaDown} 115 116\textbf{Deprecated: } Please use \helpref{GetModifiers}{wxkeyeventgetmodifiers} 117instead! 118 119true if the Meta key is pressed down. 120 121 122\membersection{wxKeyEvent::m\_shiftDown}\label{wxkeyeventmshiftdown} 123 124\member{bool}{m\_shiftDown} 125 126\textbf{Deprecated: } Please use \helpref{GetModifiers}{wxkeyeventgetmodifiers} 127instead! 128 129true if shift is pressed down. 130 131 132\membersection{wxKeyEvent::m\_x}\label{wxkeyeventmx} 133 134\member{int}{m\_x} 135 136\textbf{Deprecated: } Please use \helpref{GetX}{wxkeyeventgetx} instead! 137 138X position of the event. 139 140 141\membersection{wxKeyEvent::m\_y}\label{wxkeyeventmy} 142 143\member{int}{m\_y} 144 145\textbf{Deprecated: } Please use \helpref{GetY}{wxkeyeventgety} instead! 146 147Y position of the event. 148 149 150\membersection{wxKeyEvent::wxKeyEvent}\label{wxkeyeventctor} 151 152\func{}{wxKeyEvent}{\param{WXTYPE}{ keyEventType}} 153 154Constructor. Currently, the only valid event types are wxEVT\_CHAR and wxEVT\_CHAR\_HOOK. 155 156 157\membersection{wxKeyEvent::AltDown}\label{wxkeyeventaltdown} 158 159\constfunc{bool}{AltDown}{\void} 160 161Returns true if the Alt key was down at the time of the key event. 162 163Notice that \helpref{GetModifiers}{wxkeyeventgetmodifiers} is easier to use 164correctly than this function so you should consider using it in new code. 165 166 167\membersection{wxKeyEvent::CmdDown}\label{wxkeyeventcmddown} 168 169\constfunc{bool}{CmdDown}{\void} 170 171\textsc{Cmd} is a pseudo key which is the same as Control for PC and Unix 172platforms but the special \textsc{Apple} (a.k.a as \textsc{Command}) key under 173Macs: it makes often sense to use it instead of, say, ControlDown() because Cmd 174key is used for the same thing under Mac as Ctrl elsewhere (but Ctrl still 175exists, just not used for this purpose under Mac). So for non-Mac platforms 176this is the same as \helpref{ControlDown()}{wxkeyeventcontroldown} and under 177Mac this is the same as \helpref{MetaDown()}{wxkeyeventmetadown}. 178 179 180\membersection{wxKeyEvent::ControlDown}\label{wxkeyeventcontroldown} 181 182\constfunc{bool}{ControlDown}{\void} 183 184Returns true if the control key was down at the time of the key event. 185 186Notice that \helpref{GetModifiers}{wxkeyeventgetmodifiers} is easier to use 187correctly than this function so you should consider using it in new code. 188 189 190\membersection{wxKeyEvent::GetKeyCode}\label{wxkeyeventgetkeycode} 191 192\constfunc{int}{GetKeyCode}{\void} 193 194Returns the virtual key code. ASCII events return normal ASCII values, 195while non-ASCII events return values such as {\bf WXK\_LEFT} for the 196left cursor key. See \helpref{Keycodes}{keycodes} for a full list of 197the virtual key codes. 198 199Note that in Unicode build, the returned value is meaningful only if the 200user entered a character that can be represented in current locale's default 201charset. You can obtain the corresponding Unicode character using 202\helpref{GetUnicodeKey}{wxkeyeventgetunicodekey}. 203 204 205\membersection{wxKeyEvent::GetModifiers}\label{wxkeyeventgetmodifiers} 206 207\constfunc{int}{GetModifiers}{\void} 208 209Return the bitmask of modifier keys which were pressed when this event 210happened. See \helpref{key modifier constants}{keymodifiers} for the full list 211of modifiers. 212 213Notice that this function is easier to use correctly than, for example, 214\helpref{ControlDown}{wxkeyeventcontroldown} because when using the latter you 215also have to remember to test that none of the other modifiers is pressed: 216 217\begin{verbatim} 218 if ( ControlDown() && !AltDown() && !ShiftDown() && !MetaDown() ) 219 ... handle Ctrl-XXX ... 220\end{verbatim} 221 222and forgetting to do it can result in serious program bugs (e.g. program not 223working with European keyboard layout where \textsc{AltGr} key which is seen by 224the program as combination of \textsc{Ctrl} and \textsc{Alt} is used). On the 225other hand, you can simply write 226 227\begin{verbatim} 228 if ( GetModifiers() == wxMOD_CONTROL ) 229 ... handle Ctrl-XXX ... 230\end{verbatim} 231 232with this function. 233 234 235\membersection{wxKeyEvent::GetPosition}\label{wxkeyeventgetposition} 236 237\constfunc{wxPoint}{GetPosition}{\void} 238 239\constfunc{void}{GetPosition}{\param{long *}{x}, \param{long *}{y}} 240 241Obtains the position (in client coordinates) at which the key was pressed. 242 243 244\membersection{wxKeyEvent::GetRawKeyCode}\label{wxkeyeventgetrawkeycode} 245 246\constfunc{wxUint32}{GetRawKeyCode}{\void} 247 248Returns the raw key code for this event. This is a platform-dependent scan code 249which should only be used in advanced applications. 250 251{\bf NB:} Currently the raw key codes are not supported by all ports, use 252{\tt\#ifdef wxHAS\_RAW\_KEY\_CODES} to determine if this feature is available. 253 254 255\membersection{wxKeyEvent::GetRawKeyFlags}\label{wxkeyeventgetrawkeyflags} 256 257\constfunc{wxUint32}{GetRawKeyFlags}{\void} 258 259Returns the low level key flags for this event. The flags are 260platform-dependent and should only be used in advanced applications. 261 262{\bf NB:} Currently the raw key flags are not supported by all ports, use 263{\tt \#ifdef wxHAS\_RAW\_KEY\_CODES} to determine if this feature is available. 264 265 266\membersection{wxKeyEvent::GetUnicodeKey}\label{wxkeyeventgetunicodekey} 267 268\constfunc{wxChar}{GetUnicodeKey}{\void} 269 270Returns the Unicode character corresponding to this key event. 271 272This function is only available in Unicode build, i.e. when 273\texttt{wxUSE\_UNICODE} is $1$. 274 275 276\membersection{wxKeyEvent::GetX}\label{wxkeyeventgetx} 277 278\constfunc{long}{GetX}{\void} 279 280Returns the X position (in client coordinates) of the event. 281 282 283\membersection{wxKeyEvent::GetY}\label{wxkeyeventgety} 284 285\constfunc{long}{GetY}{\void} 286 287Returns the Y (in client coordinates) position of the event. 288 289 290\membersection{wxKeyEvent::HasModifiers}\label{wxkeyeventhasmodifiers} 291 292\constfunc{bool}{HasModifiers}{\void} 293 294Returns true if either {\sc Ctrl} or {\sc Alt} keys was down 295at the time of the key event. Note that this function does not take into 296account neither {\sc Shift} nor {\sc Meta} key states (the reason for ignoring 297the latter is that it is common for {\sc NumLock} key to be configured as 298{\sc Meta} under X but the key presses even while {\sc NumLock} is on should 299be still processed normally). 300 301 302\membersection{wxKeyEvent::MetaDown}\label{wxkeyeventmetadown} 303 304\constfunc{bool}{MetaDown}{\void} 305 306Returns true if the Meta key was down at the time of the key event. 307 308Notice that \helpref{GetModifiers}{wxkeyeventgetmodifiers} is easier to use 309correctly than this function so you should consider using it in new code. 310 311 312\membersection{wxKeyEvent::ShiftDown}\label{wxkeyeventshiftdown} 313 314\constfunc{bool}{ShiftDown}{\void} 315 316Returns true if the shift key was down at the time of the key event. 317 318Notice that \helpref{GetModifiers}{wxkeyeventgetmodifiers} is easier to use 319correctly than this function so you should consider using it in new code. 320 321