X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a660d684eda27638bca0384b2058911a31c8e845..772c017b2c30f5cb8072d7b22f39da175e101e9a:/docs/latex/wx/keyevent.tex?ds=sidebyside diff --git a/docs/latex/wx/keyevent.tex b/docs/latex/wx/keyevent.tex index 0f86725e3c..0abdc667d4 100644 --- a/docs/latex/wx/keyevent.tex +++ b/docs/latex/wx/keyevent.tex @@ -1,11 +1,58 @@ \section{\class{wxKeyEvent}}\label{wxkeyevent} -This event class contains information about keypress (character) events. See \helpref{wxWindow::OnChar}{wxwindowonchar}. +This event class contains information about keypress (character) events. + +Notice that there are three different kinds of keyboard events in wxWindows: +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 up one 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 {\tt WXK\_XXX} values +from the \helpref{keycodes table}{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 {\sc Caps Lock} is unpressed +and the standard US keyboard): when the {\tt 'A'} key is pressed, the key down +event key code is equal to {\tt ASCII A} $== 65$. But the char event key code +is {\tt ASCII a} $== 97$. On the other hand, if you press both {\sc Shift} and +{\tt 'A'} keys simultaneously , the key code in key down event will still be +just {\tt 'A'} while the char event key code parameter will now be {\tt '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 +\helpref{ShiftDown()}{wxkeyeventshiftdown}, in general you should use +{\tt 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 {\sc Ctrl-A} key press the key down event still carries the +same key code {\tt '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 \helpref{text}{sampletext} wxWindows sample and pressing some keys +in any of the text controls shown in it. + +{\bf Note for Windows programmers:} The key and char events in wxWindows are +similar to but slightly different from Windows {\tt WM\_KEYDOWN} and +{\tt WM\_CHAR} events. In particular, Alt-x combination will generate a char +event in wxWindows (unless it is used as an acclerator). \wxheading{Derived from} \helpref{wxEvent}{wxevent} +\wxheading{Include files} + + + \wxheading{Event table macros} To process a key event, use these event handler macros to direct input to member @@ -13,10 +60,19 @@ functions that take a wxKeyEvent argument. \twocolwidtha{7cm} \begin{twocollist}\itemsep=0pt +\twocolitem{{\bf EVT\_KEY\_DOWN(func)}}{Process a wxEVT\_KEY\_DOWN event (any key has been pressed).} +\twocolitem{{\bf EVT\_KEY\_UP(func)}}{Process a wxEVT\_KEY\_UP event (any key has been released).} \twocolitem{{\bf EVT\_CHAR(func)}}{Process a wxEVT\_CHAR event.} -\twocolitem{{\bf EVT\_CHAR\_HOOK(func)}}{Process a wxEVT\_CHAR\_HOOK event.} +%\twocolitem{{\bf EVT\_CHAR\_HOOK(func)}}{Process a wxEVT\_CHAR\_HOOK event.} \end{twocollist}% +\wxheading{See also} + +\helpref{wxWindow::OnChar}{wxwindowonchar}, +\helpref{wxWindow::OnCharHook}{wxwindowoncharhook}, +\helpref{wxWindow::OnKeyDown}{wxwindowonkeydown}, +\helpref{wxWindow::OnKeyUp}{wxwindowonkeyup} + \latexignore{\rtfignore{\wxheading{Members}}} \membersection{wxKeyEvent::m\_altDown} @@ -35,84 +91,7 @@ TRUE if control is pressed down. \member{long}{m\_keyCode} -Virtual keycode. An enumerated type, one of: - -\begin{verbatim} - WXK_BACK = 8 - WXK_TAB = 9 - WXK_RETURN = 13 - WXK_ESCAPE = 27 - WXK_SPACE = 32 - WXK_DELETE = 127 - - WXK_START = 300 - WXK_LBUTTON - WXK_RBUTTON - WXK_CANCEL - WXK_MBUTTON - WXK_CLEAR - WXK_SHIFT - WXK_CONTROL - WXK_MENU - WXK_PAUSE - WXK_CAPITAL - WXK_PRIOR - WXK_NEXT - WXK_END - WXK_HOME - WXK_LEFT - WXK_UP - WXK_RIGHT - WXK_DOWN - WXK_SELECT - WXK_PRINT - WXK_EXECUTE - WXK_SNAPSHOT - WXK_INSERT - WXK_HELP - WXK_NUMPAD0 - WXK_NUMPAD1 - WXK_NUMPAD2 - WXK_NUMPAD3 - WXK_NUMPAD4 - WXK_NUMPAD5 - WXK_NUMPAD6 - WXK_NUMPAD7 - WXK_NUMPAD8 - WXK_NUMPAD9 - WXK_MULTIPLY - WXK_ADD - WXK_SEPARATOR - WXK_SUBTRACT - WXK_DECIMAL - WXK_DIVIDE - WXK_F1 - WXK_F2 - WXK_F3 - WXK_F4 - WXK_F5 - WXK_F6 - WXK_F7 - WXK_F8 - WXK_F9 - WXK_F10 - WXK_F11 - WXK_F12 - WXK_F13 - WXK_F14 - WXK_F15 - WXK_F16 - WXK_F17 - WXK_F18 - WXK_F19 - WXK_F20 - WXK_F21 - WXK_F22 - WXK_F23 - WXK_F24 - WXK_NUMLOCK - WXK_SCROLL -\end{verbatim} +Virtual keycode. See \helpref{Keycodes}{keycodes} for a list of identifiers. \membersection{wxKeyEvent::m\_metaDown} @@ -146,51 +125,64 @@ Constructor. Currently, the only valid event types are wxEVT\_CHAR and wxEVT\_CH \membersection{wxKeyEvent::AltDown} -\func{bool}{AltDown}{\void} +\constfunc{bool}{AltDown}{\void} Returns TRUE if the Alt key was down at the time of the key event. \membersection{wxKeyEvent::ControlDown} -\func{bool}{ControlDown}{\void} +\constfunc{bool}{ControlDown}{\void} Returns TRUE if the control key was down at the time of the key event. +\membersection{wxKeyEvent::GetKeyCode} + +\constfunc{int}{GetKeyCode}{\void} + +Returns the virtual key code. ASCII events return normal ASCII values, +while non-ASCII events return values such as {\bf WXK\_LEFT} for the +left cursor key. See \helpref{Keycodes}{keycodes} for a full list of the virtual key codes. + \membersection{wxKeyEvent::GetX} -\func{float}{GetX}{\void} +\constfunc{long}{GetX}{\void} Returns the X position of the event. \membersection{wxKeyEvent::GetY} -\func{float}{GetY}{\void} +\constfunc{long}{GetY}{\void} Returns the Y position of the event. -\membersection{wxKeyEvent::KeyCode} - -\func{long}{KeyCode}{\void} - -Returns the virtual key code. ASCII events return normal ASCII values, -while non-ASCII events return values such as {\bf WXK\_LEFT} for the -left cursor key. See {\tt wx\_defs.h} for a full list of the virtual key codes. - \membersection{wxKeyEvent::MetaDown} -\func{bool}{MetaDown}{\void} +\constfunc{bool}{MetaDown}{\void} Returns TRUE if the Meta key was down at the time of the key event. -\membersection{wxKeyEvent::Position} +\membersection{wxKeyEvent::GetPosition} -\func{void}{Position}{\param{float *}{x}, \param{float *}{y}} +\constfunc{wxPoint}{GetPosition}{\void} + +\constfunc{void}{GetPosition}{\param{long *}{x}, \param{long *}{y}} Obtains the position at which the key was pressed. -\membersection{wxKeyEvent::ShiftDown} +\membersection{wxKeyEvent::HasModifiers} + +\constfunc{bool}{HasModifiers}{\void} + +Returns TRUE if either {\sc Ctrl} or {\sc Alt} keys was down +at the time of the key event. Note that this function does not take into +account neither {\sc Shift} nor {\sc Meta} key states (the reason for ignoring +the latter is that it is common for {\sc NumLock} key to be configured as +{\sc Meta} under X but the key presses even while {\sc NumLock} is on should +be still processed normally). + +\membersection{wxKeyEvent::ShiftDown}\label{wxkeyeventshiftdown} -\func{bool}{ShiftDown}{\void} +\constfunc{bool}{ShiftDown}{\void} Returns TRUE if the shift key was down at the time of the key event.