added wxEVT_COMMAND_LIST_ITEM_FOCUSED event and implemented it for the generic version

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

diff --git a/docs/latex/wx/keyevent.tex b/docs/latex/wx/keyevent.tex
index 1248ec89cf26183abe2ac34d1087fb076e4698dd..0abdc667d4cd0915ff2f79e5a5b30fb8344b694b 100644 (file)
--- a/docs/latex/wx/keyevent.tex
+++ b/docs/latex/wx/keyevent.tex
@@ -2,6 +2,49 @@
 
 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:
+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 up one 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 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 acclerator).
+

 \wxheading{Derived from}
 
 \helpref{wxEvent}{wxevent}
 \wxheading{Derived from}
 
 \helpref{wxEvent}{wxevent}


@@ -17,11 +60,10 @@ functions that take a wxKeyEvent argument.
 
 \twocolwidtha{7cm}
 \begin{twocollist}\itemsep=0pt
 
 \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\_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}
 \end{twocollist}%
 
 \wxheading{See also}


@@ -83,51 +125,64 @@ Constructor. Currently, the only valid event types are wxEVT\_CHAR and wxEVT\_CH
 
 \membersection{wxKeyEvent::AltDown}
 
 
 \membersection{wxKeyEvent::AltDown}
 

-\func{bool}{AltDown}{\void}
+\constfunc{bool}{AltDown}{\void}

 
 Returns TRUE if the Alt key was down at the time of the key event.
 
 \membersection{wxKeyEvent::ControlDown}
 
 
 Returns TRUE if the Alt key was down at the time of the key event.
 
 \membersection{wxKeyEvent::ControlDown}
 

-\func{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}
+
+\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.
+

 \membersection{wxKeyEvent::GetX}
 
 \membersection{wxKeyEvent::GetX}
 

-\func{float}{GetX}{\void}
+\constfunc{long}{GetX}{\void}

 
 Returns the X position of the event.
 
 \membersection{wxKeyEvent::GetY}
 
 
 Returns the X position of the event.
 
 \membersection{wxKeyEvent::GetY}
 

-\func{float}{GetY}{\void}
+\constfunc{long}{GetY}{\void}

 
 Returns the Y position of the event.
 
 
 Returns the Y position of the event.
 

-\membersection{wxKeyEvent::KeyCode}
-
-\func{long}{KeyCode}{\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.
-

 \membersection{wxKeyEvent::MetaDown}
 
 \membersection{wxKeyEvent::MetaDown}
 

-\func{bool}{MetaDown}{\void}
+\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::Position}
+\membersection{wxKeyEvent::GetPosition}

 
 

-\func{void}{Position}{\param{float *}{x}, \param{float *}{y}}
+\constfunc{wxPoint}{GetPosition}{\void}
+
+\constfunc{void}{GetPosition}{\param{long *}{x}, \param{long *}{y}}

 
 Obtains the position at which the key was pressed.
 
 
 Obtains the position at which the key was pressed.
 

-\membersection{wxKeyEvent::ShiftDown}
+\membersection{wxKeyEvent::HasModifiers}
+
+\constfunc{bool}{HasModifiers}{\void}
+
+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::ShiftDown}\label{wxkeyeventshiftdown}

 
 

-\func{bool}{ShiftDown}{\void}
+\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.