X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/f4fcc2919776cffa5e3b2f0d44dd24c41e652ff4..027aa6fa77e5b4643d2296f63d6911beb496c5bc:/docs/latex/wx/keyevent.tex diff --git a/docs/latex/wx/keyevent.tex b/docs/latex/wx/keyevent.tex index bd8174736c..7fbfa91e51 100644 --- a/docs/latex/wx/keyevent.tex +++ b/docs/latex/wx/keyevent.tex @@ -2,7 +2,7 @@ This event class contains information about keypress (character) events. -Notice that there are three different kinds of keyboard events in wxWindows: +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 @@ -17,11 +17,6 @@ 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. -If the key up event is caught and the event handler does not call -event.Skip() then the coresponding char event will not happen. This -is by design and enables the programs that handle both types of events -to be a bit simpler. - 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 @@ -42,13 +37,19 @@ 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 +running the \helpref{text}{sampletext} wxWidgets 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 +{\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 wxWidgets 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). +event in wxWidgets (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. @@ -77,75 +78,115 @@ functions that take a wxKeyEvent argument. \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxKeyEvent::m\_altDown} + +\membersection{wxKeyEvent::m\_altDown}\label{wxkeyeventmaltdown} \member{bool}{m\_altDown} -TRUE if the Alt key is pressed down. +true if the Alt key is pressed down. -\membersection{wxKeyEvent::m\_controlDown} + +\membersection{wxKeyEvent::m\_controlDown}\label{wxkeyeventmcontroldown} \member{bool}{m\_controlDown} -TRUE if control is pressed down. +true if control is pressed down. + -\membersection{wxKeyEvent::m\_keyCode} +\membersection{wxKeyEvent::m\_keyCode}\label{wxkeyeventmkeycode} \member{long}{m\_keyCode} Virtual keycode. See \helpref{Keycodes}{keycodes} for a list of identifiers. -\membersection{wxKeyEvent::m\_metaDown} + +\membersection{wxKeyEvent::m\_metaDown}\label{wxkeyeventmmetadown} \member{bool}{m\_metaDown} -TRUE if the Meta key is pressed down. +true if the Meta key is pressed down. -\membersection{wxKeyEvent::m\_shiftDown} + +\membersection{wxKeyEvent::m\_shiftDown}\label{wxkeyeventmshiftdown} \member{bool}{m\_shiftDown} -TRUE if shift is pressed down. +true if shift is pressed down. + -\membersection{wxKeyEvent::m\_x} +\membersection{wxKeyEvent::m\_x}\label{wxkeyeventmx} \member{int}{m\_x} X position of the event. -\membersection{wxKeyEvent::m\_y} + +\membersection{wxKeyEvent::m\_y}\label{wxkeyeventmy} \member{int}{m\_y} Y position of the event. -\membersection{wxKeyEvent::wxKeyEvent} + +\membersection{wxKeyEvent::wxKeyEvent}\label{wxkeyeventctor} \func{}{wxKeyEvent}{\param{WXTYPE}{ keyEventType}} Constructor. Currently, the only valid event types are wxEVT\_CHAR and wxEVT\_CHAR\_HOOK. -\membersection{wxKeyEvent::AltDown} + +\membersection{wxKeyEvent::AltDown}\label{wxkeyeventaltdown} \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} + +\membersection{wxKeyEvent::CmdDown}\label{wxkeyeventcmddown} + +\constfunc{bool}{CmdDown}{\void} + +"Cmd" is a pseudo key which is the same as Control for PC and Unix platforms +but the special "Apple" (a.k.a as "Command") key under Macs: it makes often +sense to use it instead of, say, ControlDown() because Cmd key is used for the +same thing under Mac as Ctrl elsewhere (but Ctrl still exists, just not used +for this purpose under Mac). So for non-Mac platforms this is the same as +\helpref{ControlDown()}{wxkeyeventcontroldown} and under Mac this is the same +as \helpref{MetaDown()}{wxkeyeventmetadown}. + + +\membersection{wxKeyEvent::ControlDown}\label{wxkeyeventcontroldown} \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} + +\membersection{wxKeyEvent::GetKeyCode}\label{wxkeyeventgetkeycode} \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. +left cursor key. See \helpref{Keycodes}{keycodes} for a full list of +the virtual key codes. + +Note that in Unicode build, the returned value is meaningful only if the +user entered a character that can be represented in current locale's default +charset. You can obtain the corresponding Unicode character using +\helpref{GetUnicodeKey}{wxkeyeventgetunicodekey}. + -\membersection{wxKeyEvent::GetRawKeyCode} +\membersection{wxKeyEvent::GetPosition}\label{wxkeyeventgetposition} + +\constfunc{wxPoint}{GetPosition}{\void} + +\constfunc{void}{GetPosition}{\param{long *}{x}, \param{long *}{y}} + +Obtains the position (in client coordinates) at which the key was pressed. + + +\membersection{wxKeyEvent::GetRawKeyCode}\label{wxkeyeventgetrawkeycode} \constfunc{wxUint32}{GetRawKeyCode}{\void} @@ -153,9 +194,10 @@ 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. +{\tt\#ifdef wxHAS\_RAW\_KEY\_CODES} to determine if this feature is available. -\membersection{wxKeyEvent::GetRawKeyFlags} + +\membersection{wxKeyEvent::GetRawKeyFlags}\label{wxkeyeventgetrawkeyflags} \constfunc{wxUint32}{GetRawKeyFlags}{\void} @@ -163,48 +205,55 @@ 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. +{\tt \#ifdef wxHAS\_RAW\_KEY\_CODES} to determine if this feature is available. -\membersection{wxKeyEvent::GetX} -\constfunc{long}{GetX}{\void} +\membersection{wxKeyEvent::GetUnicodeKey}\label{wxkeyeventgetunicodekey} -Returns the X position of the event. +\constfunc{wxChar}{GetUnicodeKey}{\void} -\membersection{wxKeyEvent::GetY} +Returns the Unicode character corresponding to this key event. -\constfunc{long}{GetY}{\void} +This function is only available in Unicode build, i.e. when +\texttt{wxUSE\_UNICODE} is $1$. -Returns the Y position of the event. -\membersection{wxKeyEvent::MetaDown} +\membersection{wxKeyEvent::GetX}\label{wxkeyeventgetx} -\constfunc{bool}{MetaDown}{\void} +\constfunc{long}{GetX}{\void} -Returns TRUE if the Meta key was down at the time of the key event. +Returns the X position (in client coordinates) of the event. -\membersection{wxKeyEvent::GetPosition} -\constfunc{wxPoint}{GetPosition}{\void} +\membersection{wxKeyEvent::GetY}\label{wxkeyeventgety} -\constfunc{void}{GetPosition}{\param{long *}{x}, \param{long *}{y}} +\constfunc{long}{GetY}{\void} -Obtains the position at which the key was pressed. +Returns the Y (in client coordinates) position of the event. -\membersection{wxKeyEvent::HasModifiers} + +\membersection{wxKeyEvent::HasModifiers}\label{wxkeyeventhasmodifiers} \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 {\sc Meta} under X but the key presses even while {\sc NumLock} is on should be still processed normally). + +\membersection{wxKeyEvent::MetaDown}\label{wxkeyeventmetadown} + +\constfunc{bool}{MetaDown}{\void} + +Returns true if the Meta key was down at the time of the key event. + + \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.