mentioned that the handlers should be allocated on the heap also in ClearHandlers...

[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.