git.saurik.com Git - wxWidgets.git/blame_incremental

... / ...

Commit	Line	Data
	1	\section{\class{wxKeyEvent}}\label{wxkeyevent}
	2
	3	This event class contains information about keypress (character) events.
	4
	5	Notice that there are three different kinds of keyboard events in wxWindows:
	6	key down and up events and char events. The difference between the first two
	7	is clear - the first corresponds to a key press and the second to a key
	8	release - otherwise they are identical. Just note that if the key is
	9	maintained in a pressed state you will typically get a lot of (automatically
	10	generated) down events but only up one so it is wrong to assume that there is
	11	one up event corresponding to each down one.
	12
	13	Both key events provide untranslated key codes while the char event carries
	14	the translated one. The untranslated code for alphanumeric keys is always
	15	an upper case value. For the other keys it is one of {\tt WXK\_XXX} values
	16	from the \helpref{keycodes table}{keycodes}. The translated key is, in
	17	general, the character the user expects to appear as the result of the key
	18	combination when typing the text into a text entry zone, for example.
	19
	20	A few examples to clarify this (all assume that {\sc Caps Lock} is unpressed
	21	and the standard US keyboard): when the {\tt 'A'} key is pressed, the key down
	22	event key code is equal to {\tt ASCII A} $== 65$. But the char event key code
	23	is {\tt ASCII a} $== 97$. On the other hand, if you press both {\sc Shift} and
	24	{\tt 'A'} keys simultaneously , the key code in key down event will still be
	25	just {\tt 'A'} while the char event key code parameter will now be {\tt 'A'}
	26	as well.
	27
	28	Although in this simple case it is clear that the correct key code could be
	29	found in the key down event handler by checking the value returned by
	30	\helpref{ShiftDown()}{wxkeyeventshiftdown}, in general you should use
	31	{\tt EVT\_CHAR} for this as for non alphanumeric keys the translation is
	32	keyboard-layout dependent and can only be done properly by the system itself.
	33
	34	Another kind of translation is done when the control key is pressed: for
	35	example, for {\sc Ctrl-A} key press the key down event still carries the
	36	same key code {\tt 'a'} as usual but the char event will have key code of
	37	$1$, the ASCII value of this key combination.
	38
	39	You may discover how the other keys on your system behave interactively by
	40	running the \helpref{text}{sampletext} wxWindows sample and pressing some keys
	41	in any of the text controls shown in it.
	42
	43	{\bf Note for Windows programmers:} The key and char events in wxWindows are
	44	similar to but slightly different from Windows {\tt WM\_KEYDOWN} and
	45	{\tt WM\_CHAR} events. In particular, Alt-x combination will generate a char
	46	event in wxWindows (unless it is used as an acclerator).
	47
	48	\wxheading{Derived from}
	49
	50	\helpref{wxEvent}{wxevent}
	51
	52	\wxheading{Include files}
	53
	54	<wx/event.h>
	55
	56	\wxheading{Event table macros}
	57
	58	To process a key event, use these event handler macros to direct input to member
	59	functions that take a wxKeyEvent argument.
	60
	61	\twocolwidtha{7cm}
	62	\begin{twocollist}\itemsep=0pt
	63	\twocolitem{{\bf EVT\_KEY\_DOWN(func)}}{Process a wxEVT\_KEY\_DOWN event (any key has been pressed).}
	64	\twocolitem{{\bf EVT\_KEY\_UP(func)}}{Process a wxEVT\_KEY\_UP event (any key has been released).}
	65	\twocolitem{{\bf EVT\_CHAR(func)}}{Process a wxEVT\_CHAR event.}
	66	%\twocolitem{{\bf EVT\_CHAR\_HOOK(func)}}{Process a wxEVT\_CHAR\_HOOK event.}
	67	\end{twocollist}%
	68
	69	\wxheading{See also}
	70
	71	\helpref{wxWindow::OnChar}{wxwindowonchar},
	72	\helpref{wxWindow::OnCharHook}{wxwindowoncharhook},
	73	\helpref{wxWindow::OnKeyDown}{wxwindowonkeydown},
	74	\helpref{wxWindow::OnKeyUp}{wxwindowonkeyup}
	75
	76	\latexignore{\rtfignore{\wxheading{Members}}}
	77
	78	\membersection{wxKeyEvent::m\_altDown}
	79
	80	\member{bool}{m\_altDown}
	81
	82	TRUE if the Alt key is pressed down.
	83
	84	\membersection{wxKeyEvent::m\_controlDown}
	85
	86	\member{bool}{m\_controlDown}
	87
	88	TRUE if control is pressed down.
	89
	90	\membersection{wxKeyEvent::m\_keyCode}
	91
	92	\member{long}{m\_keyCode}
	93
	94	Virtual keycode. See \helpref{Keycodes}{keycodes} for a list of identifiers.
	95
	96	\membersection{wxKeyEvent::m\_metaDown}
	97
	98	\member{bool}{m\_metaDown}
	99
	100	TRUE if the Meta key is pressed down.
	101
	102	\membersection{wxKeyEvent::m\_shiftDown}
	103
	104	\member{bool}{m\_shiftDown}
	105
	106	TRUE if shift is pressed down.
	107
	108	\membersection{wxKeyEvent::m\_x}
	109
	110	\member{int}{m\_x}
	111
	112	X position of the event.
	113
	114	\membersection{wxKeyEvent::m\_y}
	115
	116	\member{int}{m\_y}
	117
	118	Y position of the event.
	119
	120	\membersection{wxKeyEvent::wxKeyEvent}
	121
	122	\func{}{wxKeyEvent}{\param{WXTYPE}{ keyEventType}}
	123
	124	Constructor. Currently, the only valid event types are wxEVT\_CHAR and wxEVT\_CHAR\_HOOK.
	125
	126	\membersection{wxKeyEvent::AltDown}
	127
	128	\constfunc{bool}{AltDown}{\void}
	129
	130	Returns TRUE if the Alt key was down at the time of the key event.
	131
	132	\membersection{wxKeyEvent::ControlDown}
	133
	134	\constfunc{bool}{ControlDown}{\void}
	135
	136	Returns TRUE if the control key was down at the time of the key event.
	137
	138	\membersection{wxKeyEvent::GetKeyCode}
	139
	140	\constfunc{int}{GetKeyCode}{\void}
	141
	142	Returns the virtual key code. ASCII events return normal ASCII values,
	143	while non-ASCII events return values such as {\bf WXK\_LEFT} for the
	144	left cursor key. See \helpref{Keycodes}{keycodes} for a full list of the virtual key codes.
	145
	146	\membersection{wxKeyEvent::GetX}
	147
	148	\constfunc{long}{GetX}{\void}
	149
	150	Returns the X position of the event.
	151
	152	\membersection{wxKeyEvent::GetY}
	153
	154	\constfunc{long}{GetY}{\void}
	155
	156	Returns the Y position of the event.
	157
	158	\membersection{wxKeyEvent::MetaDown}
	159
	160	\constfunc{bool}{MetaDown}{\void}
	161
	162	Returns TRUE if the Meta key was down at the time of the key event.
	163
	164	\membersection{wxKeyEvent::GetPosition}
	165
	166	\constfunc{wxPoint}{GetPosition}{\void}
	167
	168	\constfunc{void}{GetPosition}{\param{long }{x}, \param{long }{y}}
	169
	170	Obtains the position at which the key was pressed.
	171
	172	\membersection{wxKeyEvent::HasModifiers}
	173
	174	\constfunc{bool}{HasModifiers}{\void}
	175
	176	Returns TRUE if either {\sc Ctrl} or {\sc Alt} keys was down
	177	at the time of the key event. Note that this function does not take into
	178	account neither {\sc Shift} nor {\sc Meta} key states (the reason for ignoring
	179	the latter is that it is common for {\sc NumLock} key to be configured as
	180	{\sc Meta} under X but the key presses even while {\sc NumLock} is on should
	181	be still processed normally).
	182
	183	\membersection{wxKeyEvent::ShiftDown}\label{wxkeyeventshiftdown}
	184
	185	\constfunc{bool}{ShiftDown}{\void}
	186
	187	Returns TRUE if the shift key was down at the time of the key event.
	188
	189