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
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.
\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}
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}
Obtains the position (in client coordinates) at which the key was pressed.
-\membersection{wxKeyEvent::GetRawKeyCode}
+\membersection{wxKeyEvent::GetRawKeyCode}\label{wxkeyeventgetrawkeycode}
\constfunc{wxUint32}{GetRawKeyCode}{\void}
{\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}
{\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}
\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}
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}
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.
+
projects / wxWidgets.git / blobdiff