X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/d11710cbb5f661222faf347039b4cf18c0a8474c..07b87e8d9b49b46bbe71d414feb35db2be278586:/docs/latex/wx/keyevent.tex diff --git a/docs/latex/wx/keyevent.tex b/docs/latex/wx/keyevent.tex index 99d3386f3f..e2b47c7fb8 100644 --- a/docs/latex/wx/keyevent.tex +++ b/docs/latex/wx/keyevent.tex @@ -2,6 +2,58 @@ 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 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 {\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:} If a key down ({\tt EVT\_KEY\_DOWN}) event is caught and +the event handler does not call {\tt event.Skip()} then the coresponding +char event ({\tt EVT\_CHAR}) will not happen. This is by design and +enables the programs that handle both types of events to be a bit +simpler. + +{\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 accelerator). + +{\bf Tip:} be sure to call {\tt event.Skip()} for events that you don't process in +key event function, otherwise menu shortcuts may cease to work under Windows. + \wxheading{Derived from} \helpref{wxEvent}{wxevent} @@ -17,19 +69,12 @@ functions that take a wxKeyEvent argument. \twocolwidtha{7cm} \begin{twocollist}\itemsep=0pt -\twocolitem{{\bf EVT\_CHAR(func)}}{Process a wxEVT\_CHAR event (a non-modifier key has been pressed).} \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}}} @@ -37,13 +82,13 @@ functions that take a wxKeyEvent argument. \member{bool}{m\_altDown} -TRUE if the Alt key is pressed down. +true if the Alt key is pressed down. \membersection{wxKeyEvent::m\_controlDown} \member{bool}{m\_controlDown} -TRUE if control is pressed down. +true if control is pressed down. \membersection{wxKeyEvent::m\_keyCode} @@ -55,13 +100,13 @@ Virtual keycode. See \helpref{Keycodes}{keycodes} for a list of identifiers. \member{bool}{m\_metaDown} -TRUE if the Meta key is pressed down. +true if the Meta key is pressed down. \membersection{wxKeyEvent::m\_shiftDown} \member{bool}{m\_shiftDown} -TRUE if shift is pressed down. +true if shift is pressed down. \membersection{wxKeyEvent::m\_x} @@ -85,13 +130,13 @@ Constructor. Currently, the only valid event types are wxEVT\_CHAR and wxEVT\_CH \constfunc{bool}{AltDown}{\void} -Returns TRUE if the Alt key was down at the time of the key event. +Returns true if the Alt key was down at the time of the key event. \membersection{wxKeyEvent::ControlDown} \constfunc{bool}{ControlDown}{\void} -Returns TRUE if the control key was down at the time of the key event. +Returns true if the control key was down at the time of the key event. \membersection{wxKeyEvent::GetKeyCode} @@ -101,23 +146,43 @@ 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::GetRawKeyCode} + +\constfunc{wxUint32}{GetRawKeyCode}{\void} + +Returns the raw key code for this event. This is a platform-dependent scan code +which should only be used in advanced applications. + +{\bf NB:} Currently the raw key codes are not supported by all ports, use +{\tt\#ifdef wxHAS\_RAW\_KEY\_CODES} to determine if this feature is available. + +\membersection{wxKeyEvent::GetRawKeyFlags} + +\constfunc{wxUint32}{GetRawKeyFlags}{\void} + +Returns the low level key flags for this event. The flags are +platform-dependent and should only be used in advanced applications. + +{\bf NB:} Currently the raw key flags are not supported by all ports, use +{\tt \#ifdef wxHAS\_RAW\_KEY\_CODES} to determine if this feature is available. + \membersection{wxKeyEvent::GetX} \constfunc{long}{GetX}{\void} -Returns the X position of the event. +Returns the X position (in client coordinates) of the event. \membersection{wxKeyEvent::GetY} \constfunc{long}{GetY}{\void} -Returns the Y position of the event. +Returns the Y (in client coordinates) position of the event. \membersection{wxKeyEvent::MetaDown} \constfunc{bool}{MetaDown}{\void} -Returns TRUE if the Meta key was down at the time of the key event. +Returns true if the Meta key was down at the time of the key event. \membersection{wxKeyEvent::GetPosition} @@ -125,23 +190,22 @@ Returns TRUE if the Meta key was down at the time of the key event. \constfunc{void}{GetPosition}{\param{long *}{x}, \param{long *}{y}} -Obtains the position at which the key was pressed. +Obtains the position (in client coordinates) at which the key was pressed. \membersection{wxKeyEvent::HasModifiers} \constfunc{bool}{HasModifiers}{\void} -Returns TRUE if either {\sc Ctrl} or {\sc Alt} keys was down +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 +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} +\membersection{wxKeyEvent::ShiftDown}\label{wxkeyeventshiftdown} \constfunc{bool}{ShiftDown}{\void} -Returns TRUE if the shift key was down at the time of the key event. - +Returns true if the shift key was down at the time of the key event.