X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a2bd1520897a55da922e60e5d6ebdc68ee6e068a..db67d86dd1de506a5bb14dd59e9c45230120758a:/docs/latex/wx/keyevent.tex diff --git a/docs/latex/wx/keyevent.tex b/docs/latex/wx/keyevent.tex index a76d181b19..eff2b8c547 100644 --- a/docs/latex/wx/keyevent.tex +++ b/docs/latex/wx/keyevent.tex @@ -28,7 +28,7 @@ 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 +{\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 @@ -41,7 +41,7 @@ running the \helpref{text}{sampletext} wxWidgets 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 +the event handler does not call {\tt event.Skip()} then the corresponding 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. @@ -79,80 +79,102 @@ functions that take a wxKeyEvent argument. \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxKeyEvent::m\_altDown} +\membersection{wxKeyEvent::m\_altDown}\label{wxkeyeventmaltdown} \member{bool}{m\_altDown} +\textbf{Deprecated: } Please use \helpref{GetModifiers}{wxkeyeventgetmodifiers} +instead! + true if the Alt key is pressed down. -\membersection{wxKeyEvent::m\_controlDown} +\membersection{wxKeyEvent::m\_controlDown}\label{wxkeyeventmcontroldown} \member{bool}{m\_controlDown} +\textbf{Deprecated: } Please use \helpref{GetModifiers}{wxkeyeventgetmodifiers} +instead! + true if control is pressed down. -\membersection{wxKeyEvent::m\_keyCode} +\membersection{wxKeyEvent::m\_keyCode}\label{wxkeyeventmkeycode} \member{long}{m\_keyCode} +\textbf{Deprecated: } Please use \helpref{GetKeyCode}{wxkeyeventgetkeycode} +instead! + 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} +\textbf{Deprecated: } Please use \helpref{GetModifiers}{wxkeyeventgetmodifiers} +instead! + true if the Meta key is pressed down. -\membersection{wxKeyEvent::m\_shiftDown} +\membersection{wxKeyEvent::m\_shiftDown}\label{wxkeyeventmshiftdown} \member{bool}{m\_shiftDown} +\textbf{Deprecated: } Please use \helpref{GetModifiers}{wxkeyeventgetmodifiers} +instead! + true if shift is pressed down. -\membersection{wxKeyEvent::m\_x} +\membersection{wxKeyEvent::m\_x}\label{wxkeyeventmx} \member{int}{m\_x} +\textbf{Deprecated: } Please use \helpref{GetX}{wxkeyeventgetx} instead! + X position of the event. -\membersection{wxKeyEvent::m\_y} +\membersection{wxKeyEvent::m\_y}\label{wxkeyeventmy} \member{int}{m\_y} +\textbf{Deprecated: } Please use \helpref{GetY}{wxkeyeventgety} instead! + 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. +Notice that \helpref{GetModifiers}{wxkeyeventgetmodifiers} is easier to use +correctly than this function so you should consider using it in new code. + \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}. +\textsc{Cmd} is a pseudo key which is the same as Control for PC and Unix +platforms but the special \textsc{Apple} (a.k.a as \textsc{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} @@ -161,17 +183,56 @@ as \helpref{MetaDown()}{wxkeyeventmetadown}. Returns true if the control key was down at the time of the key event. +Notice that \helpref{GetModifiers}{wxkeyeventgetmodifiers} is easier to use +correctly than this function so you should consider using it in new code. + -\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::GetModifiers}\label{wxkeyeventgetmodifiers} -\membersection{wxKeyEvent::GetPosition} +\constfunc{int}{GetModifiers}{\void} + +Return the bitmask of modifier keys which were pressed when this event +happened. See \helpref{key modifier constants}{keymodifiers} for the full list +of modifiers. + +Notice that this function is easier to use correctly than, for example, +\helpref{ControlDown}{wxkeyeventcontroldown} because when using the latter you +also have to remember to test that none of the other modifiers is pressed: + +\begin{verbatim} + if ( ControlDown() && !AltDown() && !ShiftDown() && !MetaDown() ) + ... handle Ctrl-XXX ... +\end{verbatim} + +and forgetting to do it can result in serious program bugs (e.g. program not +working with European keyboard layout where \textsc{AltGr} key which is seen by +the program as combination of \textsc{Ctrl} and \textsc{Alt} is used). On the +other hand, you can simply write + +\begin{verbatim} + if ( GetModifiers() == wxMOD_CONTROL ) + ... handle Ctrl-XXX ... +\end{verbatim} + +with this function. + + +\membersection{wxKeyEvent::GetPosition}\label{wxkeyeventgetposition} \constfunc{wxPoint}{GetPosition}{\void} @@ -180,7 +241,7 @@ left cursor key. See \helpref{Keycodes}{keycodes} for a full list of the virtual Obtains the position (in client coordinates) at which the key was pressed. -\membersection{wxKeyEvent::GetRawKeyCode} +\membersection{wxKeyEvent::GetRawKeyCode}\label{wxkeyeventgetrawkeycode} \constfunc{wxUint32}{GetRawKeyCode}{\void} @@ -191,7 +252,7 @@ which should only be used in advanced applications. {\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} @@ -202,7 +263,7 @@ platform-dependent and should only be used in advanced applications. {\tt \#ifdef wxHAS\_RAW\_KEY\_CODES} to determine if this feature is available. -\membersection{wxKeyEvent::GetUnicodeKey} +\membersection{wxKeyEvent::GetUnicodeKey}\label{wxkeyeventgetunicodekey} \constfunc{wxChar}{GetUnicodeKey}{\void} @@ -212,21 +273,21 @@ This function is only available in Unicode build, i.e. when \texttt{wxUSE\_UNICODE} is $1$. -\membersection{wxKeyEvent::GetX} +\membersection{wxKeyEvent::GetX}\label{wxkeyeventgetx} \constfunc{long}{GetX}{\void} Returns the X position (in client coordinates) of the event. -\membersection{wxKeyEvent::GetY} +\membersection{wxKeyEvent::GetY}\label{wxkeyeventgety} \constfunc{long}{GetY}{\void} Returns the Y (in client coordinates) position of the event. -\membersection{wxKeyEvent::HasModifiers} +\membersection{wxKeyEvent::HasModifiers}\label{wxkeyeventhasmodifiers} \constfunc{bool}{HasModifiers}{\void} @@ -244,6 +305,9 @@ be still processed normally). Returns true if the Meta key was down at the time of the key event. +Notice that \helpref{GetModifiers}{wxkeyeventgetmodifiers} is easier to use +correctly than this function so you should consider using it in new code. + \membersection{wxKeyEvent::ShiftDown}\label{wxkeyeventshiftdown} @@ -251,3 +315,6 @@ Returns true if the Meta 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. +Notice that \helpref{GetModifiers}{wxkeyeventgetmodifiers} is easier to use +correctly than this function so you should consider using it in new code. +