enable verbose messages by default in debug builds

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

\section{\class{wxEvtHandler}}\label{wxevthandler}

A class that can handle events from the windowing system.
wxWindow (and therefore all window classes) are derived from
this class.

\wxheading{Derived from}

\helpref{wxObject}{wxobject}

\wxheading{See also}

\overview{Event handling overview}{eventhandlingoverview}

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

\membersection{wxEvtHandler::wxEvtHandler}

\func{}{wxEvtHandler}{\void}

Constructor.

\membersection{wxEvtHandler::\destruct{wxEvtHandler}}

\func{}{\destruct{wxEvtHandler}}{\void}

Destructor. If the handler is part of a chain, the destructor will
unlink itself and restore the previous and next handlers so that they point to
each other.

\membersection{wxEvtHandler::Connect}\label{wxevthandlerconnect}

\func{void}{Connect}{\param{int}{ id},
 \param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function},
 \param{wxObject*}{ userData = NULL}}

\func{void}{Connect}{\param{int}{ id}, \param{int}{ lastId},
 \param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function},
 \param{wxObject*}{ userData = NULL}}

Connects the given function dynamically with the event handler, id and event type. This
is an alternative to the use of static event tables. See the 'dynamic' sample for usage.

\wxheading{Parameters}

\docparam{id}{The identifier (or first of the identifier range) to be associated with the event handler function.}

\docparam{lastId}{The second part of the identifier range to be associated with the event handler function.}

\docparam{eventType}{The event type to be associated with this event handler.}

\docparam{function}{The event handler function.}

\docparam{userData}{Data to be associated with the event table entry.}

\wxheading{Example}

\begin{verbatim}
  frame->Connect( wxID_EXIT,
    wxEVT_COMMAND_MENU_SELECTED,
    (wxObjectEventFunction) (wxEventFunction) (wxCommandEventFunction) MyFrame::OnQuit );
\end{verbatim}

\membersection{wxEvtHandler::Default}\label{wxevthandlerdefault}

\func{virtual long}{Default}{\void}

Invokes default processing if this event handler is a window.

\wxheading{Return value}

System dependent.

\wxheading{Remarks}

A generic way of delegating processing to the default system behaviour. It calls a platform-dependent
default function, with parameters dependent on the event or message parameters
originally sent from the windowing system.

Normally the application should call a base member, such as \helpref{wxWindow::OnChar}{wxwindowonchar}, which itself
may call {\bf Default}.

\membersection{wxEvtHandler::GetClientData}\label{wxevthandlergetclientdata}

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

Gets user-supplied client data.

\wxheading{Remarks}

Normally, any extra data the programmer wishes to associate with the object
should be made available by deriving a new class
with new data members.

\wxheading{See also}

\helpref{wxEvtHandler::SetClientData}{wxevthandlersetclientdata}

\membersection{wxEvtHandler::GetEvtHandlerEnabled}\label{wxevthandlergetevthandlerenabled}

\func{bool}{GetEvtHandlerEnabled}{\void}

Returns TRUE if the event handler is enabled, FALSE otherwise.

\wxheading{See also}

\helpref{wxEvtHandler::SetEvtHandlerEnabled}{wxevthandlersetevthandlerenabled}

\membersection{wxEvtHandler::GetNextHandler}\label{wxevthandlergetnexthandler}

\func{wxEvtHandler*}{GetNextHandler}{\void}

Gets the pointer to the next handler in the chain.

\wxheading{See also}

\helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp
\helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp
\helpref{wxEvtHandler::SetNextHandler}{wxevthandlersetnexthandler},\rtfsp
\helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
\helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler}

\membersection{wxEvtHandler::GetPreviousHandler}\label{wxevthandlergetprevioushandler}

\func{wxEvtHandler*}{GetPreviousHandler}{\void}

Gets the pointer to the previous handler in the chain.

\wxheading{See also}

\helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp
\helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp
\helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp
\helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
\helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler}

\membersection{wxEvtHandler::ProcessEvent}\label{wxevthandlerprocessevent}

\func{virtual bool}{ProcessEvent}{\param{wxEvent\& }{event}}

Processes an event, searching event tables and calling zero or more suitable event handler function(s).

\wxheading{Parameters}

\docparam{event}{Event to process.}

\wxheading{Return value}

TRUE if a suitable event handler function was found and executed, and the function did not
call \helpref{wxEvent::Skip}{wxeventskip}.

\wxheading{Remarks}

Normally, your application would not call this function: it is called in the wxWindows
implementation to dispatch incoming user interface events to the framework (and application).

However, you might need to call it if implementing new functionality (such as a new control) where
you define new event types, as opposed to allowing the user to override virtual functions.

An instance where you might actually override the {\bf ProcessEvent} function is where you want
to direct event processing to event handlers not normally noticed by wxWindows. For example,
in the document/view architecture, documents and views are potential event handlers.
When an event reaches a frame, {\bf ProcessEvent} will need to be called on the associated
document and view in case event handler functions are associated with these objects.
The property classes library (wxProperty) also overrides {\bf ProcessEvent} for similar reasons.

The normal order of event table searching is as follows:

\begin{enumerate}\itemsep=0pt
\item If the object is disabled (via a call to \helpref{wxEvtHandler::SetEvtHandlerEnabled}{wxevthandlersetevthandlerenabled})
the function skips to step (6).
\item If the object is a wxWindow, {\bf ProcessEvent} is recursively called on the window's\rtfsp
\helpref{wxValidator}{wxvalidator}. If this returns TRUE, the function exits.
\item {\bf SearchEventTable} is called for this event handler. If this fails, the base
class table is tried, and so on until no more tables exist or an appropriate function was found,
in which case the function exits.
\item The search is applied down the entire chain of event handlers (usually the chain has a length
of one). If this succeeds, the function exits.
\item If the object is a wxWindow and the event is a wxCommandEvent, {\bf ProcessEvent} is
recursively applied to the parent window's event handler. If this returns TRUE, the function exits.
\item Finally, {\bf ProcessEvent} is called on the wxApp object.
\end{enumerate}

\wxheading{See also}

\helpref{wxEvtHandler::SearchEventTable}{wxevthandlersearcheventtable}

\membersection{wxEvtHandler::SearchEventTable}\label{wxevthandlersearcheventtable}

\func{bool}{SearchEventTable}{\param{wxEventTable\& }{table}, \param{wxEvent\& }{event}}

Searches the event table, executing an event handler function if an appropriate one
is found.

\wxheading{Parameters}

\docparam{table}{Event table to be searched.}

\docparam{event}{Event to be matched against an event table entry.}

\wxheading{Return value}

TRUE if a suitable event handler function was found and executed, and the function did not
call \helpref{wxEvent::Skip}{wxeventskip}.

\wxheading{Remarks}

This function looks through the object's event table and tries to find an entry
that will match the event.

An entry will match if:

\begin{enumerate}\itemsep=0pt
\item The event type matches, and
\item the identifier or identifier range matches, or the event table entry's identifier is zero.
\end{enumerate}

If a suitable function is called but calls \helpref{wxEvent::Skip}{wxeventskip}, this function will
fail, and searching will continue.

\wxheading{See also}

\helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent}

\membersection{wxEvtHandler::SetClientData}\label{wxevthandlersetclientdata}

\func{void}{SetClientData}{\param{char* }{data}}

Sets user-supplied client data.

\wxheading{Parameters}

\docparam{data}{Data to be associated with the event handler.}

\wxheading{Remarks}

Normally, any extra data the programmer wishes
to associate with the object should be made available by deriving a new class
with new data members.
%TODO: make this void*, char* only in compatibility mode.

\wxheading{See also}

\helpref{wxEvtHandler::GetClientData}{wxevthandlergetclientdata}

\membersection{wxEvtHandler::SetEvtHandlerEnabled}\label{wxevthandlersetevthandlerenabled}

\func{void}{SetEvtHandlerEnabled}{\param{bool }{enabled}}

Enables or disables the event handler.

\wxheading{Parameters}

\docparam{enabled}{TRUE if the event handler is to be enabled, FALSE if it is to be disabled.}

\wxheading{Remarks}

You can use this function to avoid having to remove the event handler from the chain, for example
when implementing a dialog editor and changing from edit to test mode.

\wxheading{See also}

\helpref{wxEvtHandler::GetEvtHandlerEnabled}{wxevthandlergetevthandlerenabled}

\membersection{wxEvtHandler::SetNextHandler}\label{wxevthandlersetnexthandler}

\func{void}{SetNextHandler}{\param{wxEvtHandler* }{handler}}

Sets the pointer to the next handler.

\wxheading{Parameters}

\docparam{handler}{Event handler to be set as the next handler.}

\wxheading{See also}

\helpref{wxEvtHandler::GetNextHandler}{wxevthandlergetnexthandler},\rtfsp
\helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp
\helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp
\helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
\helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler}

\membersection{wxEvtHandler::SetPreviousHandler}\label{wxevthandlersetprevioushandler}

\func{void}{SetPreviousHandler}{\param{wxEvtHandler* }{handler}}

Sets the pointer to the previous handler.

\wxheading{Parameters}

\docparam{handler}{Event handler to be set as the previous handler.}

\wxheading{See also}

\helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp
\helpref{wxEvtHandler::SetNextHandler}{wxevthandlersetnexthandler},\rtfsp
\helpref{wxEvtHandler::GetNextHandler}{wxevthandlergetnexthandler},\rtfsp
\helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
\helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler}