[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\_COMBOBOX(id, func)}}{Process a wxEVT\_COMMAND\_COMBOBOX\_SELECTED command,
which is generated by a wxComboBox 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\_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\_CONTEXT\_MENU(func)}}{Process the event generated
when the user has requested a popup menu to appear by pressing a special
keyboard key (under Windows) or by right clicking the mouse.}
\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\_SLIDER(id, func)}}{Process a wxEVT\_COMMAND\_SLIDER\_UPDATED command,
which is generated by a wxSlider 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 previously set with 
\helpref{SetMaxLength}{wxtextctrlsetmaxlength}.}
\twocolitem{{\bf EVT\_TOGGLEBUTTON(id, func)}}{Process a wxEVT\_COMMAND\_TOGGLEBUTTON\_CLICKED event.}
\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 of 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::wxCommandEvent}\label{wxcommandeventctor}

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

Constructor.

\membersection{wxCommandEvent::Checked}\label{wxcommandeventchecked}

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

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

\membersection{wxCommandEvent::GetClientData}\label{wxcommandeventgetclientdata}

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

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

\membersection{wxCommandEvent::GetClientObject}\label{wxcommandeventgetclientobject}

\func{wxClientData *}{GetClientObject}{\void}

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

\membersection{wxCommandEvent::GetExtraLong}\label{wxcommandeventgetextralong}

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

Returns extra information dependant on the event objects type.
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::GetInt}\label{wxcommandeventgetint}

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

Returns the 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::GetSelection}\label{wxcommandeventgetselection}

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

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

\membersection{wxCommandEvent::GetString}\label{wxcommandeventgetstring}

\func{wxString}{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}\label{wxcommandeventisselection}

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

For a listbox or similar event, returns true if it is a selection, false if it
is a deselection.

\membersection{wxCommandEvent::SetClientData}\label{wxcommandeventsetclientdata}

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

Sets the client data for this event.

\membersection{wxCommandEvent::SetClientObject}\label{wxcommandeventsetclientobject}

\func{void}{SetClientObject}{\param{wxClientData*}{ clientObject}}

Sets the client object for this event. The client object is \emph{not} owned by the event
object and the event object will not delete the client object in its destructor.
The client object must be owned and deleted by another object (e.g. a control)
that has longer life time than the event object.

\membersection{wxCommandEvent::SetExtraLong}\label{wxcommandeventsetextralong}

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

Sets the {\bf m\_extraLong} member.

\membersection{wxCommandEvent::SetInt}\label{wxcommandeventsetint}

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

Sets the {\bf m\_commandInt} member.

\membersection{wxCommandEvent::SetString}\label{wxcommandeventsetstring}

\func{void}{SetString}{\param{const wxString\&}{ 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.}
052d2fc5 KH	32	\twocolitem{{\bf EVT\_COMBOBOX(id, func)}}{Process a wxEVT\_COMMAND\_COMBOBOX\_SELECTED command,
052d2fc5 KH	33	which is generated by a wxComboBox control.}
a660d684 KB	34	\twocolitem{{\bf EVT\_LISTBOX(id, func)}}{Process a wxEVT\_COMMAND\_LISTBOX\_SELECTED command,
a660d684 KB	35	which is generated by a wxListBox control.}
e14dccff	36	\twocolitem{{\bf EVT\_LISTBOX\_DCLICK(id, func)}}{Process a wxEVT\_COMMAND\_LISTBOX\_DOUBLECLICKED command,
debe6624	37	which is generated by a wxListBox control.}
a660d684 KB	38	\twocolitem{{\bf EVT\_MENU(id, func)}}{Process a wxEVT\_COMMAND\_MENU\_SELECTED command,
	39	which is generated by a menu item.}
	40	\twocolitem{{\bf EVT\_MENU\_RANGE(id1, id2, func)}}{Process a wxEVT\_COMMAND\_MENU\_RANGE command,
	41	which is generated by a range of menu items.}
ccef86c7 VZ	42	\twocolitem{{\bf EVT\_CONTEXT\_MENU(func)}}{Process the event generated
	43	when the user has requested a popup menu to appear by pressing a special
	44	keyboard key (under Windows) or by right clicking the mouse.}
a660d684 KB	45	\twocolitem{{\bf EVT\_RADIOBOX(id, func)}}{Process a wxEVT\_COMMAND\_RADIOBOX\_SELECTED command,
	46	which is generated by a wxRadioBox control.}
	47	\twocolitem{{\bf EVT\_RADIOBUTTON(id, func)}}{Process a wxEVT\_COMMAND\_RADIOBUTTON\_SELECTED command,
	48	which is generated by a wxRadioButton control.}
	49	\twocolitem{{\bf EVT\_SCROLLBAR(id, func)}}{Process a wxEVT\_COMMAND\_SCROLLBAR\_UPDATED command,
	50	which is generated by a wxScrollBar control. This is provided for compatibility only;
	51	more specific scrollbar event macros should be used instead (see \helpref{wxScrollEvent}{wxscrollevent}).}
052d2fc5 KH	52	\twocolitem{{\bf EVT\_SLIDER(id, func)}}{Process a wxEVT\_COMMAND\_SLIDER\_UPDATED command,
	53	which is generated by a wxSlider control.}
	54	\twocolitem{{\bf EVT\_TEXT(id, func)}}{Process a wxEVT\_COMMAND\_TEXT\_UPDATED command,
	55	which is generated by a wxTextCtrl control.}
	56	\twocolitem{{\bf EVT\_TEXT\_ENTER(id, func)}}{Process a wxEVT\_COMMAND\_TEXT\_ENTER command,
	57	which is generated by a wxTextCtrl control. Note that you must use
	58	wxTE\_PROCESS\_ENTER flag when creating the control if you want it to generate
	59	such events.}
	60	\twocolitem{{\bf EVT\_TEXT\_MAXLEN(id, func)}}{Process a wxEVT\_COMMAND\_TEXT\_MAXLEN command,
	61	which is generated by a wxTextCtrl control when the user tries to enter more
	62	characters into it than the limit previously set with
	63	\helpref{SetMaxLength}{wxtextctrlsetmaxlength}.}
20f82e13	64	\twocolitem{{\bf EVT\_TOGGLEBUTTON(id, func)}}{Process a wxEVT\_COMMAND\_TOGGLEBUTTON\_CLICKED event.}
81d66cf3 JS	65	\twocolitem{{\bf EVT\_TOOL(id, func)}}{Process a wxEVT\_COMMAND\_TOOL\_CLICKED event
	66	(a synonym for wxEVT\_COMMAND\_MENU\_SELECTED). Pass the id of the tool.}
	67	\twocolitem{{\bf EVT\_TOOL\_RANGE(id1, id2, func)}}{Process a wxEVT\_COMMAND\_TOOL\_CLICKED event
156194e1	68	for a range of identifiers. Pass the ids of the tools.}
81d66cf3 JS	69	\twocolitem{{\bf EVT\_TOOL\_RCLICKED(id, func)}}{Process a wxEVT\_COMMAND\_TOOL\_RCLICKED event.
	70	Pass the id of the tool.}
	71	\twocolitem{{\bf EVT\_TOOL\_RCLICKED\_RANGE(id1, id2, func)}}{Process a wxEVT\_COMMAND\_TOOL\_RCLICKED event
	72	for a range of ids. Pass the ids of the tools.}
	73	\twocolitem{{\bf EVT\_TOOL\_ENTER(id, func)}}{Process a wxEVT\_COMMAND\_TOOL\_ENTER event.
	74	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	75	\twocolitem{{\bf EVT\_COMMAND\_LEFT\_CLICK(id, func)}}{Process a wxEVT\_COMMAND\_LEFT\_CLICK command,
	76	which is generated by a control (Windows 95 and NT only).}
	77	\twocolitem{{\bf EVT\_COMMAND\_LEFT\_DCLICK(id, func)}}{Process a wxEVT\_COMMAND\_LEFT\_DCLICK command,
	78	which is generated by a control (Windows 95 and NT only).}
	79	\twocolitem{{\bf EVT\_COMMAND\_RIGHT\_CLICK(id, func)}}{Process a wxEVT\_COMMAND\_RIGHT\_CLICK command,
	80	which is generated by a control (Windows 95 and NT only).}
	81	\twocolitem{{\bf EVT\_COMMAND\_SET\_FOCUS(id, func)}}{Process a wxEVT\_COMMAND\_SET\_FOCUS command,
	82	which is generated by a control (Windows 95 and NT only).}
	83	\twocolitem{{\bf EVT\_COMMAND\_KILL\_FOCUS(id, func)}}{Process a wxEVT\_COMMAND\_KILL\_FOCUS command,
	84	which is generated by a control (Windows 95 and NT only).}
	85	\twocolitem{{\bf EVT\_COMMAND\_ENTER(id, func)}}{Process a wxEVT\_COMMAND\_ENTER command,
	86	which is generated by a control.}
	87	\end{twocollist}%
	88
	89	\latexignore{\rtfignore{\wxheading{Members}}}
	90
f510b7b2	91	\membersection{wxCommandEvent::wxCommandEvent}\label{wxcommandeventctor}
a660d684 KB	92
	93	\func{}{wxCommandEvent}{\param{WXTYPE}{ commandEventType = 0}, \param{int}{ id = 0}}
	94
	95	Constructor.
	96
f510b7b2	97	\membersection{wxCommandEvent::Checked}\label{wxcommandeventchecked}
a660d684	98
3ca6a5f0	99	\constfunc{bool}{Checked}{\void}
a660d684	100
3ca6a5f0	101	Deprecated, use \helpref{IsChecked}{wxcommandeventischecked} instead.
a660d684	102
f510b7b2	103	\membersection{wxCommandEvent::GetClientData}\label{wxcommandeventgetclientdata}
a660d684	104
9c884972	105	\func{void*}{GetClientData}{\void}
a660d684 KB	106
a660d684 KB	107	Returns client data pointer for a listbox or choice selection event
3ca6a5f0	108	(not valid for a deselection).
a660d684	109
f510b7b2	110	\membersection{wxCommandEvent::GetClientObject}\label{wxcommandeventgetclientobject}
88eadcf2 VZ	111
	112	\func{wxClientData *}{GetClientObject}{\void}
	113
	114	Returns client object pointer for a listbox or choice selection event
	115	(not valid for a deselection).
	116
f510b7b2	117	\membersection{wxCommandEvent::GetExtraLong}\label{wxcommandeventgetextralong}
a660d684 KB	118
	119	\func{long}{GetExtraLong}{\void}
	120
1e75cc48 KH	121	Returns extra information dependant on the event objects type.
	122	If the event comes from a listbox selection, it is a boolean
	123	determining whether the event was a selection (true) or a
	124	deselection (false). A listbox deselection only occurs for
	125	multiple-selection boxes, and in this case the index and string values
	126	are indeterminate and the listbox must be examined by the application.
a660d684	127
f510b7b2	128	\membersection{wxCommandEvent::GetInt}\label{wxcommandeventgetint}
a660d684 KB	129
	130	\func{int}{GetInt}{\void}
	131
1e75cc48 KH	132	Returns the integer identifier corresponding to a listbox, choice or
	133	radiobox selection (only if the event was a selection, not a
	134	deselection), or a boolean value representing the value of a checkbox.
a660d684	135
f510b7b2	136	\membersection{wxCommandEvent::GetSelection}\label{wxcommandeventgetselection}
a660d684 KB	137
	138	\func{int}{GetSelection}{\void}
	139
	140	Returns item index for a listbox or choice selection event (not valid for
	141	a deselection).
	142
f510b7b2	143	\membersection{wxCommandEvent::GetString}\label{wxcommandeventgetstring}
a660d684	144
ce788ad9	145	\func{wxString}{GetString}{\void}
a660d684 KB	146
	147	Returns item string for a listbox or choice selection event (not valid for
	148	a deselection).
	149
3ca6a5f0 BP	150	\membersection{wxCommandEvent::IsChecked}\label{wxcommandeventischecked}
	151
	152	\constfunc{bool}{IsChecked}{\void}
	153
	154	This method can be used with checkbox and menu events: for the checkboxes, the
cc81d32f	155	method returns {\tt true} for a selection event and {\tt false} for a
3ca6a5f0 BP	156	deselection one. For the menu events, this method indicates if the menu item
	157	just has become checked or unchecked (and thus only makes sense for checkable
	158	menu items).
	159
f510b7b2	160	\membersection{wxCommandEvent::IsSelection}\label{wxcommandeventisselection}
a660d684 KB	161
	162	\func{bool}{IsSelection}{\void}
	163
9fa1a107	164	For a listbox or similar event, returns true if it is a selection, false if it
a660d684 KB	165	is a deselection.
a660d684 KB	166
f510b7b2	167	\membersection{wxCommandEvent::SetClientData}\label{wxcommandeventsetclientdata}
a660d684	168
9c884972	169	\func{void}{SetClientData}{\param{void*}{ clientData}}
a660d684 KB	170
	171	Sets the client data for this event.
	172
f510b7b2	173	\membersection{wxCommandEvent::SetClientObject}\label{wxcommandeventsetclientobject}
88eadcf2 VZ	174
	175	\func{void}{SetClientObject}{\param{wxClientData*}{ clientObject}}
	176
	177	Sets the client object for this event. The client object is \emph{not} owned by the event
	178	object and the event object will not delete the client object in its destructor.
	179	The client object must be owned and deleted by another object (e.g. a control)
	180	that has longer life time than the event object.
	181
f510b7b2	182	\membersection{wxCommandEvent::SetExtraLong}\label{wxcommandeventsetextralong}
a660d684 KB	183
	184	\func{void}{SetExtraLong}{\param{int}{ extraLong}}
	185
	186	Sets the {\bf m\_extraLong} member.
	187
f510b7b2	188	\membersection{wxCommandEvent::SetInt}\label{wxcommandeventsetint}
a660d684 KB	189
	190	\func{void}{SetInt}{\param{int}{ intCommand}}
	191
	192	Sets the {\bf m\_commandInt} member.
	193
f510b7b2	194	\membersection{wxCommandEvent::SetString}\label{wxcommandeventsetstring}
a660d684	195
ce788ad9	196	\func{void}{SetString}{\param{const wxString\&}{ string}}
a660d684 KB	197
	198	Sets the {\bf m\_commandString} member.
	199