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

\section{\class{wxCommandEvent}}\label{wxcommandevent}

This event class contains information about command events, which originate from a variety of
simple controls. More complex controls, such as \helpref{wxTreeCtrl}{wxtreectrl}, have separate command event classes.

\wxheading{Derived from}

\helpref{wxEvent}{wxevent}

\wxheading{Include files}

<wx/event.h>

\wxheading{Event table macros}

To process a menu command event, use these event handler macros to direct input to member
functions that take a wxCommandEvent argument.

\twocolwidtha{7cm}
\begin{twocollist}\itemsep=0pt
\twocolitem{{\bf EVT\_COMMAND(id, event, func)}}{Process a command, supplying the window identifier,
command event identifier, and member function.}
\twocolitem{{\bf EVT\_COMMAND\_RANGE(id1, id2, event, func)}}{Process a command for a range
of window identifiers, supplying the minimum and maximum window identifiers,
command event identifier, and member function.}
\twocolitem{{\bf EVT\_BUTTON(id, func)}}{Process a wxEVT\_COMMAND\_BUTTON\_CLICKED command,
which is generated by a wxButton control.}
\twocolitem{{\bf EVT\_CHECKBOX(id, func)}}{Process a wxEVT\_COMMAND\_CHECKBOX\_CLICKED command,
which is generated by a wxCheckBox control.}
\twocolitem{{\bf EVT\_CHOICE(id, func)}}{Process a wxEVT\_COMMAND\_CHOICE\_SELECTED command,
which is generated by a wxChoice control.}
\twocolitem{{\bf EVT\_LISTBOX(id, func)}}{Process a wxEVT\_COMMAND\_LISTBOX\_SELECTED command,
which is generated by a wxListBox control.}
\twocolitem{{\bf EVT\_LISTBOX\_DCLICK(id, func)}}{Process a wxEVT\_COMMAND\_LISTBOX\_DOUBLECLICKED command,
which is generated by a wxListBox control.}
\twocolitem{{\bf EVT\_TEXT(id, func)}}{Process a wxEVT\_COMMAND\_TEXT\_UPDATED command,
which is generated by a wxTextCtrl control.}
\twocolitem{{\bf EVT\_TEXT\_ENTER(id, func)}}{Process a wxEVT\_COMMAND\_TEXT\_ENTER command,
which is generated by a wxTextCtrl control. Note that you must use
wxTE\_PROCESS\_ENTER flag when creating the control if you want it to generate
such events.}
\twocolitem{{\bf EVT\_TEXT\_MAXLEN(id, func)}}{Process a wxEVT\_COMMAND\_TEXT\_MAXLEN command,
which is generated by a wxTextCtrl control when the user tries to enter more
characters into it than the limit previosuly set with 
\helpref{SetMaxLength}{wxtextctrlsetmaxlength}.}
\twocolitem{{\bf EVT\_MENU(id, func)}}{Process a wxEVT\_COMMAND\_MENU\_SELECTED command,
which is generated by a menu item.}
\twocolitem{{\bf EVT\_MENU\_RANGE(id1, id2, func)}}{Process a wxEVT\_COMMAND\_MENU\_RANGE command,
which is generated by a range of menu items.}
\twocolitem{{\bf EVT\_SLIDER(id, func)}}{Process a wxEVT\_COMMAND\_SLIDER\_UPDATED command,
which is generated by a wxSlider control.}
\twocolitem{{\bf EVT\_RADIOBOX(id, func)}}{Process a wxEVT\_COMMAND\_RADIOBOX\_SELECTED command,
which is generated by a wxRadioBox control.}
\twocolitem{{\bf EVT\_RADIOBUTTON(id, func)}}{Process a wxEVT\_COMMAND\_RADIOBUTTON\_SELECTED command,
which is generated by a wxRadioButton control.}
\twocolitem{{\bf EVT\_SCROLLBAR(id, func)}}{Process a wxEVT\_COMMAND\_SCROLLBAR\_UPDATED command,
which is generated by a wxScrollBar control. This is provided for compatibility only;
more specific scrollbar event macros should be used instead (see \helpref{wxScrollEvent}{wxscrollevent}).}
\twocolitem{{\bf EVT\_COMBOBOX(id, func)}}{Process a wxEVT\_COMMAND\_COMBOBOX\_SELECTED command,
which is generated by a wxComboBox control.}
\twocolitem{{\bf EVT\_TOOL(id, func)}}{Process a wxEVT\_COMMAND\_TOOL\_CLICKED event
(a synonym for wxEVT\_COMMAND\_MENU\_SELECTED). Pass the id of the tool.}
\twocolitem{{\bf EVT\_TOOL\_RANGE(id1, id2, func)}}{Process a wxEVT\_COMMAND\_TOOL\_CLICKED event
for a range id identifiers. Pass the ids of the tools.}
\twocolitem{{\bf EVT\_TOOL\_RCLICKED(id, func)}}{Process a wxEVT\_COMMAND\_TOOL\_RCLICKED event.
Pass the id of the tool.}
\twocolitem{{\bf EVT\_TOOL\_RCLICKED\_RANGE(id1, id2, func)}}{Process a wxEVT\_COMMAND\_TOOL\_RCLICKED event
for a range of ids. Pass the ids of the tools.}
\twocolitem{{\bf EVT\_TOOL\_ENTER(id, func)}}{Process a wxEVT\_COMMAND\_TOOL\_ENTER event.
Pass the id of the toolbar itself. The value of wxCommandEvent::GetSelection is the tool id, or -1 if the mouse cursor has moved off a tool.}
\twocolitem{{\bf EVT\_COMMAND\_LEFT\_CLICK(id, func)}}{Process a wxEVT\_COMMAND\_LEFT\_CLICK command,
which is generated by a control (Windows 95 and NT only).}
\twocolitem{{\bf EVT\_COMMAND\_LEFT\_DCLICK(id, func)}}{Process a wxEVT\_COMMAND\_LEFT\_DCLICK command,
which is generated by a control (Windows 95 and NT only).}
\twocolitem{{\bf EVT\_COMMAND\_RIGHT\_CLICK(id, func)}}{Process a wxEVT\_COMMAND\_RIGHT\_CLICK command,
which is generated by a control (Windows 95 and NT only).}
\twocolitem{{\bf EVT\_COMMAND\_SET\_FOCUS(id, func)}}{Process a wxEVT\_COMMAND\_SET\_FOCUS command,
which is generated by a control (Windows 95 and NT only).}
\twocolitem{{\bf EVT\_COMMAND\_KILL\_FOCUS(id, func)}}{Process a wxEVT\_COMMAND\_KILL\_FOCUS command,
which is generated by a control (Windows 95 and NT only).}
\twocolitem{{\bf EVT\_COMMAND\_ENTER(id, func)}}{Process a wxEVT\_COMMAND\_ENTER command,
which is generated by a control.}
\end{twocollist}%

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxCommandEvent::m\_clientData}

\member{void*}{m\_clientData}

Contains a pointer to client data for listboxes and choices, if the event
was a selection. Beware, this is not implemented anyway...

\membersection{wxCommandEvent::m\_commandInt}

\member{int}{m\_commandInt}

Contains an integer identifier corresponding to a listbox, choice or
radiobox selection (only if the event was a selection, not a
deselection), or a boolean value representing the value of a checkbox.

\membersection{wxCommandEvent::m\_commandString}

\member{char*}{m\_commandString}

Contains a string corresponding to a listbox or choice selection.

\membersection{wxCommandEvent::m\_extraLong}

\member{long}{m\_extraLong}

Extra information. If the event comes from a listbox selection, it is
a boolean determining whether the event was a selection (TRUE) or a
deselection (FALSE). A listbox deselection only occurs for
multiple-selection boxes, and in this case the index and string values
are indeterminate and the listbox must be examined by the application.

\membersection{wxCommandEvent::wxCommandEvent}

\func{}{wxCommandEvent}{\param{WXTYPE}{ commandEventType = 0}, \param{int}{ id = 0}}

Constructor.

\membersection{wxCommandEvent::Checked}

\constfunc{bool}{Checked}{\void}

Deprecated, use \helpref{IsChecked}{wxcommandeventischecked} instead.

\membersection{wxCommandEvent::GetClientData}

\func{void*}{GetClientData}{\void}

Returns client data pointer for a listbox or choice selection event
(not valid for a deselection).

\membersection{wxCommandEvent::GetExtraLong}

\func{long}{GetExtraLong}{\void}

Returns the {\bf m\_extraLong} member.

\membersection{wxCommandEvent::GetInt}

\func{int}{GetInt}{\void}

Returns the {\bf m\_commandInt} member.

\membersection{wxCommandEvent::GetSelection}

\func{int}{GetSelection}{\void}

Returns item index for a listbox or choice selection event (not valid for
a deselection).

\membersection{wxCommandEvent::GetString}

\func{char*}{GetString}{\void}

Returns item string for a listbox or choice selection event (not valid for
a deselection).

\membersection{wxCommandEvent::IsChecked}\label{wxcommandeventischecked}

\constfunc{bool}{IsChecked}{\void}

This method can be used with checkbox and menu events: for the checkboxes, the
method returns {\tt TRUE} for a selection event and {\tt FALSE} for a
deselection one. For the menu events, this method indicates if the menu item
just has become checked or unchecked (and thus only makes sense for checkable
menu items).

\membersection{wxCommandEvent::IsSelection}

\func{bool}{IsSelection}{\void}

For a listbox or choice event, returns TRUE if it is a selection, FALSE if it
is a deselection.

\membersection{wxCommandEvent::SetClientData}

\func{void}{SetClientData}{\param{void*}{ clientData}}

Sets the client data for this event.

\membersection{wxCommandEvent::SetExtraLong}

\func{void}{SetExtraLong}{\param{int}{ extraLong}}

Sets the {\bf m\_extraLong} member.

\membersection{wxCommandEvent::SetInt}

\func{void}{SetInt}{\param{int}{ intCommand}}

Sets the {\bf m\_commandInt} member.

\membersection{wxCommandEvent::SetString}

\func{void}{SetString}{\param{char*}{ string}}

Sets the {\bf m\_commandString} member.
Commit	Line	Data
a660d684 KB	1	\section{\class{wxCommandEvent}}\label{wxcommandevent}
	2
	3	This event class contains information about command events, which originate from a variety of
	4	simple controls. More complex controls, such as \helpref{wxTreeCtrl}{wxtreectrl}, have separate command event classes.
	5
	6	\wxheading{Derived from}
	7
	8	\helpref{wxEvent}{wxevent}
	9
954b8ae6 JS	10	\wxheading{Include files}
	11
	12	<wx/event.h>
	13
a660d684 KB	14	\wxheading{Event table macros}
	15
	16	To process a menu command event, use these event handler macros to direct input to member
	17	functions that take a wxCommandEvent argument.
	18
	19	\twocolwidtha{7cm}
	20	\begin{twocollist}\itemsep=0pt
1f112209	21	\twocolitem{{\bf EVT\_COMMAND(id, event, func)}}{Process a command, supplying the window identifier,
a660d684	22	command event identifier, and member function.}
1f112209	23	\twocolitem{{\bf EVT\_COMMAND\_RANGE(id1, id2, event, func)}}{Process a command for a range
a660d684 KB	24	of window identifiers, supplying the minimum and maximum window identifiers,
	25	command event identifier, and member function.}
	26	\twocolitem{{\bf EVT\_BUTTON(id, func)}}{Process a wxEVT\_COMMAND\_BUTTON\_CLICKED command,
	27	which is generated by a wxButton control.}
	28	\twocolitem{{\bf EVT\_CHECKBOX(id, func)}}{Process a wxEVT\_COMMAND\_CHECKBOX\_CLICKED command,
	29	which is generated by a wxCheckBox control.}
	30	\twocolitem{{\bf EVT\_CHOICE(id, func)}}{Process a wxEVT\_COMMAND\_CHOICE\_SELECTED command,
	31	which is generated by a wxChoice control.}
	32	\twocolitem{{\bf EVT\_LISTBOX(id, func)}}{Process a wxEVT\_COMMAND\_LISTBOX\_SELECTED command,
	33	which is generated by a wxListBox control.}
e14dccff	34	\twocolitem{{\bf EVT\_LISTBOX\_DCLICK(id, func)}}{Process a wxEVT\_COMMAND\_LISTBOX\_DOUBLECLICKED command,
debe6624	35	which is generated by a wxListBox control.}
a660d684 KB	36	\twocolitem{{\bf EVT\_TEXT(id, func)}}{Process a wxEVT\_COMMAND\_TEXT\_UPDATED command,
	37	which is generated by a wxTextCtrl control.}
	38	\twocolitem{{\bf EVT\_TEXT\_ENTER(id, func)}}{Process a wxEVT\_COMMAND\_TEXT\_ENTER command,
3ca6a5f0 BP	39	which is generated by a wxTextCtrl control. Note that you must use
	40	wxTE\_PROCESS\_ENTER flag when creating the control if you want it to generate
	41	such events.}
d7eee191 VZ	42	\twocolitem{{\bf EVT\_TEXT\_MAXLEN(id, func)}}{Process a wxEVT\_COMMAND\_TEXT\_MAXLEN command,
	43	which is generated by a wxTextCtrl control when the user tries to enter more
	44	characters into it than the limit previosuly set with
	45	\helpref{SetMaxLength}{wxtextctrlsetmaxlength}.}
a660d684 KB	46	\twocolitem{{\bf EVT\_MENU(id, func)}}{Process a wxEVT\_COMMAND\_MENU\_SELECTED command,
	47	which is generated by a menu item.}
	48	\twocolitem{{\bf EVT\_MENU\_RANGE(id1, id2, func)}}{Process a wxEVT\_COMMAND\_MENU\_RANGE command,
	49	which is generated by a range of menu items.}
	50	\twocolitem{{\bf EVT\_SLIDER(id, func)}}{Process a wxEVT\_COMMAND\_SLIDER\_UPDATED command,
	51	which is generated by a wxSlider control.}
	52	\twocolitem{{\bf EVT\_RADIOBOX(id, func)}}{Process a wxEVT\_COMMAND\_RADIOBOX\_SELECTED command,
	53	which is generated by a wxRadioBox control.}
	54	\twocolitem{{\bf EVT\_RADIOBUTTON(id, func)}}{Process a wxEVT\_COMMAND\_RADIOBUTTON\_SELECTED command,
	55	which is generated by a wxRadioButton control.}
	56	\twocolitem{{\bf EVT\_SCROLLBAR(id, func)}}{Process a wxEVT\_COMMAND\_SCROLLBAR\_UPDATED command,
	57	which is generated by a wxScrollBar control. This is provided for compatibility only;
	58	more specific scrollbar event macros should be used instead (see \helpref{wxScrollEvent}{wxscrollevent}).}
	59	\twocolitem{{\bf EVT\_COMBOBOX(id, func)}}{Process a wxEVT\_COMMAND\_COMBOBOX\_SELECTED command,
	60	which is generated by a wxComboBox control.}
81d66cf3 JS	61	\twocolitem{{\bf EVT\_TOOL(id, func)}}{Process a wxEVT\_COMMAND\_TOOL\_CLICKED event
	62	(a synonym for wxEVT\_COMMAND\_MENU\_SELECTED). Pass the id of the tool.}
	63	\twocolitem{{\bf EVT\_TOOL\_RANGE(id1, id2, func)}}{Process a wxEVT\_COMMAND\_TOOL\_CLICKED event
	64	for a range id identifiers. Pass the ids of the tools.}
	65	\twocolitem{{\bf EVT\_TOOL\_RCLICKED(id, func)}}{Process a wxEVT\_COMMAND\_TOOL\_RCLICKED event.
	66	Pass the id of the tool.}
	67	\twocolitem{{\bf EVT\_TOOL\_RCLICKED\_RANGE(id1, id2, func)}}{Process a wxEVT\_COMMAND\_TOOL\_RCLICKED event
	68	for a range of ids. Pass the ids of the tools.}
	69	\twocolitem{{\bf EVT\_TOOL\_ENTER(id, func)}}{Process a wxEVT\_COMMAND\_TOOL\_ENTER event.
	70	Pass the id of the toolbar itself. The value of wxCommandEvent::GetSelection is the tool id, or -1 if the mouse cursor has moved off a tool.}
a660d684 KB	71	\twocolitem{{\bf EVT\_COMMAND\_LEFT\_CLICK(id, func)}}{Process a wxEVT\_COMMAND\_LEFT\_CLICK command,
	72	which is generated by a control (Windows 95 and NT only).}
	73	\twocolitem{{\bf EVT\_COMMAND\_LEFT\_DCLICK(id, func)}}{Process a wxEVT\_COMMAND\_LEFT\_DCLICK command,
	74	which is generated by a control (Windows 95 and NT only).}
	75	\twocolitem{{\bf EVT\_COMMAND\_RIGHT\_CLICK(id, func)}}{Process a wxEVT\_COMMAND\_RIGHT\_CLICK command,
	76	which is generated by a control (Windows 95 and NT only).}
	77	\twocolitem{{\bf EVT\_COMMAND\_SET\_FOCUS(id, func)}}{Process a wxEVT\_COMMAND\_SET\_FOCUS command,
	78	which is generated by a control (Windows 95 and NT only).}
	79	\twocolitem{{\bf EVT\_COMMAND\_KILL\_FOCUS(id, func)}}{Process a wxEVT\_COMMAND\_KILL\_FOCUS command,
	80	which is generated by a control (Windows 95 and NT only).}
	81	\twocolitem{{\bf EVT\_COMMAND\_ENTER(id, func)}}{Process a wxEVT\_COMMAND\_ENTER command,
	82	which is generated by a control.}
	83	\end{twocollist}%
	84
	85	\latexignore{\rtfignore{\wxheading{Members}}}
	86
	87	\membersection{wxCommandEvent::m\_clientData}
	88
9c884972	89	\member{void*}{m\_clientData}
a660d684 KB	90
a660d684 KB	91	Contains a pointer to client data for listboxes and choices, if the event
9c884972	92	was a selection. Beware, this is not implemented anyway...
a660d684 KB	93
	94	\membersection{wxCommandEvent::m\_commandInt}
	95
	96	\member{int}{m\_commandInt}
	97
	98	Contains an integer identifier corresponding to a listbox, choice or
	99	radiobox selection (only if the event was a selection, not a
	100	deselection), or a boolean value representing the value of a checkbox.
	101
	102	\membersection{wxCommandEvent::m\_commandString}
	103
	104	\member{char*}{m\_commandString}
	105
	106	Contains a string corresponding to a listbox or choice selection.
	107
	108	\membersection{wxCommandEvent::m\_extraLong}
	109
	110	\member{long}{m\_extraLong}
	111
	112	Extra information. If the event comes from a listbox selection, it is
	113	a boolean determining whether the event was a selection (TRUE) or a
	114	deselection (FALSE). A listbox deselection only occurs for
	115	multiple-selection boxes, and in this case the index and string values
	116	are indeterminate and the listbox must be examined by the application.
	117
	118	\membersection{wxCommandEvent::wxCommandEvent}
	119
	120	\func{}{wxCommandEvent}{\param{WXTYPE}{ commandEventType = 0}, \param{int}{ id = 0}}
	121
	122	Constructor.
	123
	124	\membersection{wxCommandEvent::Checked}
	125
3ca6a5f0	126	\constfunc{bool}{Checked}{\void}
a660d684	127
3ca6a5f0	128	Deprecated, use \helpref{IsChecked}{wxcommandeventischecked} instead.
a660d684 KB	129
	130	\membersection{wxCommandEvent::GetClientData}
	131
9c884972	132	\func{void*}{GetClientData}{\void}
a660d684 KB	133
a660d684 KB	134	Returns client data pointer for a listbox or choice selection event
3ca6a5f0	135	(not valid for a deselection).
a660d684 KB	136
	137	\membersection{wxCommandEvent::GetExtraLong}
	138
	139	\func{long}{GetExtraLong}{\void}
	140
	141	Returns the {\bf m\_extraLong} member.
	142
	143	\membersection{wxCommandEvent::GetInt}
	144
	145	\func{int}{GetInt}{\void}
	146
	147	Returns the {\bf m\_commandInt} member.
	148
	149	\membersection{wxCommandEvent::GetSelection}
	150
	151	\func{int}{GetSelection}{\void}
	152
	153	Returns item index for a listbox or choice selection event (not valid for
	154	a deselection).
	155
	156	\membersection{wxCommandEvent::GetString}
	157
	158	\func{char*}{GetString}{\void}
	159
	160	Returns item string for a listbox or choice selection event (not valid for
	161	a deselection).
	162
3ca6a5f0 BP	163	\membersection{wxCommandEvent::IsChecked}\label{wxcommandeventischecked}
	164
	165	\constfunc{bool}{IsChecked}{\void}
	166
	167	This method can be used with checkbox and menu events: for the checkboxes, the
	168	method returns {\tt TRUE} for a selection event and {\tt FALSE} for a
	169	deselection one. For the menu events, this method indicates if the menu item
	170	just has become checked or unchecked (and thus only makes sense for checkable
	171	menu items).
	172
a660d684 KB	173	\membersection{wxCommandEvent::IsSelection}
	174
	175	\func{bool}{IsSelection}{\void}
	176
	177	For a listbox or choice event, returns TRUE if it is a selection, FALSE if it
	178	is a deselection.
	179
	180	\membersection{wxCommandEvent::SetClientData}
	181
9c884972	182	\func{void}{SetClientData}{\param{void*}{ clientData}}
a660d684 KB	183
	184	Sets the client data for this event.
	185
	186	\membersection{wxCommandEvent::SetExtraLong}
	187
	188	\func{void}{SetExtraLong}{\param{int}{ extraLong}}
	189
	190	Sets the {\bf m\_extraLong} member.
	191
	192	\membersection{wxCommandEvent::SetInt}
	193
	194	\func{void}{SetInt}{\param{int}{ intCommand}}
	195
	196	Sets the {\bf m\_commandInt} member.
	197
	198	\membersection{wxCommandEvent::SetString}
	199
	200	\func{void}{SetString}{\param{char*}{ string}}
	201
	202	Sets the {\bf m\_commandString} member.
	203