[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\_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.}
a660d684 KB	42	\twocolitem{{\bf EVT\_MENU(id, func)}}{Process a wxEVT\_COMMAND\_MENU\_SELECTED command,
	43	which is generated by a menu item.}
	44	\twocolitem{{\bf EVT\_MENU\_RANGE(id1, id2, func)}}{Process a wxEVT\_COMMAND\_MENU\_RANGE command,
	45	which is generated by a range of menu items.}
	46	\twocolitem{{\bf EVT\_SLIDER(id, func)}}{Process a wxEVT\_COMMAND\_SLIDER\_UPDATED command,
	47	which is generated by a wxSlider control.}
	48	\twocolitem{{\bf EVT\_RADIOBOX(id, func)}}{Process a wxEVT\_COMMAND\_RADIOBOX\_SELECTED command,
	49	which is generated by a wxRadioBox control.}
	50	\twocolitem{{\bf EVT\_RADIOBUTTON(id, func)}}{Process a wxEVT\_COMMAND\_RADIOBUTTON\_SELECTED command,
	51	which is generated by a wxRadioButton control.}
	52	\twocolitem{{\bf EVT\_SCROLLBAR(id, func)}}{Process a wxEVT\_COMMAND\_SCROLLBAR\_UPDATED command,
	53	which is generated by a wxScrollBar control. This is provided for compatibility only;
	54	more specific scrollbar event macros should be used instead (see \helpref{wxScrollEvent}{wxscrollevent}).}
	55	\twocolitem{{\bf EVT\_COMBOBOX(id, func)}}{Process a wxEVT\_COMMAND\_COMBOBOX\_SELECTED command,
	56	which is generated by a wxComboBox control.}
81d66cf3 JS	57	\twocolitem{{\bf EVT\_TOOL(id, func)}}{Process a wxEVT\_COMMAND\_TOOL\_CLICKED event
	58	(a synonym for wxEVT\_COMMAND\_MENU\_SELECTED). Pass the id of the tool.}
	59	\twocolitem{{\bf EVT\_TOOL\_RANGE(id1, id2, func)}}{Process a wxEVT\_COMMAND\_TOOL\_CLICKED event
	60	for a range id identifiers. Pass the ids of the tools.}
	61	\twocolitem{{\bf EVT\_TOOL\_RCLICKED(id, func)}}{Process a wxEVT\_COMMAND\_TOOL\_RCLICKED event.
	62	Pass the id of the tool.}
	63	\twocolitem{{\bf EVT\_TOOL\_RCLICKED\_RANGE(id1, id2, func)}}{Process a wxEVT\_COMMAND\_TOOL\_RCLICKED event
	64	for a range of ids. Pass the ids of the tools.}
	65	\twocolitem{{\bf EVT\_TOOL\_ENTER(id, func)}}{Process a wxEVT\_COMMAND\_TOOL\_ENTER event.
	66	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	67	\twocolitem{{\bf EVT\_COMMAND\_LEFT\_CLICK(id, func)}}{Process a wxEVT\_COMMAND\_LEFT\_CLICK command,
	68	which is generated by a control (Windows 95 and NT only).}
	69	\twocolitem{{\bf EVT\_COMMAND\_LEFT\_DCLICK(id, func)}}{Process a wxEVT\_COMMAND\_LEFT\_DCLICK command,
	70	which is generated by a control (Windows 95 and NT only).}
	71	\twocolitem{{\bf EVT\_COMMAND\_RIGHT\_CLICK(id, func)}}{Process a wxEVT\_COMMAND\_RIGHT\_CLICK command,
	72	which is generated by a control (Windows 95 and NT only).}
	73	\twocolitem{{\bf EVT\_COMMAND\_SET\_FOCUS(id, func)}}{Process a wxEVT\_COMMAND\_SET\_FOCUS command,
	74	which is generated by a control (Windows 95 and NT only).}
	75	\twocolitem{{\bf EVT\_COMMAND\_KILL\_FOCUS(id, func)}}{Process a wxEVT\_COMMAND\_KILL\_FOCUS command,
	76	which is generated by a control (Windows 95 and NT only).}
	77	\twocolitem{{\bf EVT\_COMMAND\_ENTER(id, func)}}{Process a wxEVT\_COMMAND\_ENTER command,
	78	which is generated by a control.}
	79	\end{twocollist}%
	80
	81	\latexignore{\rtfignore{\wxheading{Members}}}
	82
	83	\membersection{wxCommandEvent::m\_clientData}
	84
9c884972	85	\member{void*}{m\_clientData}
a660d684 KB	86
a660d684 KB	87	Contains a pointer to client data for listboxes and choices, if the event
9c884972	88	was a selection. Beware, this is not implemented anyway...
a660d684 KB	89
	90	\membersection{wxCommandEvent::m\_commandInt}
	91
	92	\member{int}{m\_commandInt}
	93
	94	Contains an integer identifier corresponding to a listbox, choice or
	95	radiobox selection (only if the event was a selection, not a
	96	deselection), or a boolean value representing the value of a checkbox.
	97
	98	\membersection{wxCommandEvent::m\_commandString}
	99
	100	\member{char*}{m\_commandString}
	101
	102	Contains a string corresponding to a listbox or choice selection.
	103
	104	\membersection{wxCommandEvent::m\_extraLong}
	105
	106	\member{long}{m\_extraLong}
	107
	108	Extra information. If the event comes from a listbox selection, it is
	109	a boolean determining whether the event was a selection (TRUE) or a
	110	deselection (FALSE). A listbox deselection only occurs for
	111	multiple-selection boxes, and in this case the index and string values
	112	are indeterminate and the listbox must be examined by the application.
	113
	114	\membersection{wxCommandEvent::wxCommandEvent}
	115
	116	\func{}{wxCommandEvent}{\param{WXTYPE}{ commandEventType = 0}, \param{int}{ id = 0}}
	117
	118	Constructor.
	119
	120	\membersection{wxCommandEvent::Checked}
	121
3ca6a5f0	122	\constfunc{bool}{Checked}{\void}
a660d684	123
3ca6a5f0	124	Deprecated, use \helpref{IsChecked}{wxcommandeventischecked} instead.
a660d684 KB	125
	126	\membersection{wxCommandEvent::GetClientData}
	127
9c884972	128	\func{void*}{GetClientData}{\void}
a660d684 KB	129
a660d684 KB	130	Returns client data pointer for a listbox or choice selection event
3ca6a5f0	131	(not valid for a deselection).
a660d684 KB	132
	133	\membersection{wxCommandEvent::GetExtraLong}
	134
	135	\func{long}{GetExtraLong}{\void}
	136
	137	Returns the {\bf m\_extraLong} member.
	138
	139	\membersection{wxCommandEvent::GetInt}
	140
	141	\func{int}{GetInt}{\void}
	142
	143	Returns the {\bf m\_commandInt} member.
	144
	145	\membersection{wxCommandEvent::GetSelection}
	146
	147	\func{int}{GetSelection}{\void}
	148
	149	Returns item index for a listbox or choice selection event (not valid for
	150	a deselection).
	151
	152	\membersection{wxCommandEvent::GetString}
	153
	154	\func{char*}{GetString}{\void}
	155
	156	Returns item string for a listbox or choice selection event (not valid for
	157	a deselection).
	158
3ca6a5f0 BP	159	\membersection{wxCommandEvent::IsChecked}\label{wxcommandeventischecked}
	160
	161	\constfunc{bool}{IsChecked}{\void}
	162
	163	This method can be used with checkbox and menu events: for the checkboxes, the
	164	method returns {\tt TRUE} for a selection event and {\tt FALSE} for a
	165	deselection one. For the menu events, this method indicates if the menu item
	166	just has become checked or unchecked (and thus only makes sense for checkable
	167	menu items).
	168
a660d684 KB	169	\membersection{wxCommandEvent::IsSelection}
	170
	171	\func{bool}{IsSelection}{\void}
	172
	173	For a listbox or choice event, returns TRUE if it is a selection, FALSE if it
	174	is a deselection.
	175
	176	\membersection{wxCommandEvent::SetClientData}
	177
9c884972	178	\func{void}{SetClientData}{\param{void*}{ clientData}}
a660d684 KB	179
	180	Sets the client data for this event.
	181
	182	\membersection{wxCommandEvent::SetExtraLong}
	183
	184	\func{void}{SetExtraLong}{\param{int}{ extraLong}}
	185
	186	Sets the {\bf m\_extraLong} member.
	187
	188	\membersection{wxCommandEvent::SetInt}
	189
	190	\func{void}{SetInt}{\param{int}{ intCommand}}
	191
	192	Sets the {\bf m\_commandInt} member.
	193
	194	\membersection{wxCommandEvent::SetString}
	195
	196	\func{void}{SetString}{\param{char*}{ string}}
	197
	198	Sets the {\bf m\_commandString} member.
	199