one more fix for tree selection

[wxWidgets.git] / docs / latex / wx / keyevent.tex

diff --git a/docs/latex/wx/keyevent.tex b/docs/latex/wx/keyevent.tex
index ef8543a623fc8e1b2591495245bbab355818f1d6..584d5aec4547a6e0a3d3cc5bb489df532e3b1360 100644 (file)
--- 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.
 
 
 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
 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.
 
 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
 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,22 @@ 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
 $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.
 
 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 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.
+
+{\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
 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.

 
 \wxheading{Derived from}
 
 
 \wxheading{Derived from}
 


@@ -74,75 +78,115 @@ functions that take a wxKeyEvent argument.
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

-\membersection{wxKeyEvent::m\_altDown}
+
+\membersection{wxKeyEvent::m\_altDown}\label{wxkeyeventmaltdown}

 
 \member{bool}{m\_altDown}
 
 
 \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}
 
 
 \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.
 
 
 \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}
 
 
 \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}
 
 
 \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.
 
 
 \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.
 
 
 \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.
 
 
 \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}
 
 
 \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::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}
+\membersection{wxKeyEvent::ControlDown}\label{wxkeyeventcontroldown}

 
 \constfunc{bool}{ControlDown}{\void}
 
 
 \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
 
 \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}
 
 
 \constfunc{wxUint32}{GetRawKeyCode}{\void}
 


@@ -150,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
 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}
 
 
 \constfunc{wxUint32}{GetRawKeyFlags}{\void}
 


@@ -160,49 +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
 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}
+
+Returns the Y (in client coordinates) position of the event.

 
 

-Obtains the position at which the key was pressed.

 
 

-\membersection{wxKeyEvent::HasModifiers}
+\membersection{wxKeyEvent::HasModifiers}\label{wxkeyeventhasmodifiers}

 
 \constfunc{bool}{HasModifiers}{\void}
 
 
 \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).
 
 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}
 
 \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.