763b330106
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@34748 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
399 lines
15 KiB
TeX
399 lines
15 KiB
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.
|
|
|
|
When events are received, wxEvtHandler invokes the method listed in the
|
|
event table using itself as the object. When using multiple inheritance
|
|
it is imperative that the wxEvtHandler(-derived) class be the first
|
|
class inherited such that the "this" pointer for the overall object
|
|
will be identical to the "this" pointer for the wxEvtHandler portion.
|
|
|
|
\wxheading{Derived from}
|
|
|
|
\helpref{wxObject}{wxobject}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/event.h>
|
|
|
|
\wxheading{See also}
|
|
|
|
\overview{Event handling overview}{eventhandlingoverview}
|
|
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
\membersection{wxEvtHandler::wxEvtHandler}\label{wxevthandlerctor}
|
|
|
|
\func{}{wxEvtHandler}{\void}
|
|
|
|
Constructor.
|
|
|
|
\membersection{wxEvtHandler::\destruct{wxEvtHandler}}\label{wxevthandlerdtor}
|
|
|
|
\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::AddPendingEvent}\label{wxevthandleraddpendingevent}
|
|
|
|
\func{void}{AddPendingEvent}{\param{wxEvent\& }{event}}
|
|
|
|
This function posts an event to be processed later.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{event}{Event to add to process queue.}
|
|
|
|
\wxheading{Remarks}
|
|
|
|
The difference between sending an event (using the
|
|
\helpref{ProcessEvent}{wxevthandlerprocessevent} method) and posting it is
|
|
that in the first case the event is processed before the function returns,
|
|
while in the second case, the function returns immediately and the event will
|
|
be processed sometime later (usually during the next event loop iteration).
|
|
|
|
A copy of {\it event} is made by the function, so the original can be deleted
|
|
as soon as function returns (it is common that the original is created on the
|
|
stack). This requires that the \helpref{wxEvent::Clone}{wxeventclone} method
|
|
be implemented by {\it event} so that it can be duplicated and stored until
|
|
it gets processed.
|
|
|
|
This is also the method to call for inter-thread communication---it will
|
|
post events safely between different threads which means that this method is
|
|
thread-safe by using critical sections where needed. In a multi-threaded
|
|
program, you often need to inform the main GUI thread about the status of
|
|
other working threads and such notification should be done using this method.
|
|
|
|
This method automatically wakes up idle handling if the underlying window
|
|
system is currently idle and thus would not send any idle events. (Waking
|
|
up idle handling is done calling \helpref{::wxWakeUpIdle}{wxwakeupidle}.)
|
|
|
|
\membersection{wxEvtHandler::Connect}\label{wxevthandlerconnect}
|
|
|
|
\func{void}{Connect}{\param{int}{ id}, \param{int}{ lastId},
|
|
\param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function},
|
|
\param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}}
|
|
|
|
\func{void}{Connect}{\param{int}{ id},
|
|
\param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function},
|
|
\param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}}
|
|
|
|
\func{void}{Connect}{\param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function},
|
|
\param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = 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 'event' or the old 'dynamic' sample for usage.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{id}{The identifier (or first of the identifier range) to be
|
|
associated with the event handler function. For the version not taking this
|
|
argument, it defaults to \texttt{wxID\_ANY}.}
|
|
|
|
\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. Note that this function should
|
|
be explicitly converted to the correct type which can be done using a macro
|
|
called \texttt{wxFooHandler} for the handler for any \texttt{wxFooEvent}.}
|
|
|
|
\docparam{userData}{Data to be associated with the event table entry.}
|
|
|
|
\docparam{eventSink}{Object whose member function should be called. If this is NULL,
|
|
\textit{this} will be used.}
|
|
|
|
\wxheading{Example}
|
|
|
|
\begin{verbatim}
|
|
frame->Connect( wxID_EXIT,
|
|
wxEVT_COMMAND_MENU_SELECTED,
|
|
wxCommandEventHandler(MyFrame::OnQuit) );
|
|
\end{verbatim}
|
|
|
|
\perlnote{In wxPerl this function takes 4 arguments: \texttt{id,
|
|
lastid, type, method}; if \texttt{method} is \texttt{undef}, the
|
|
handler is disconnected.}
|
|
|
|
\membersection{wxEvtHandler::Disconnect}\label{wxevthandlerdisconnect}
|
|
|
|
\func{bool}{Disconnect}{\param{wxEventType }{eventType = wxEVT\_NULL}, \param{wxObjectEventFunction}{ function = NULL},
|
|
\param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}}
|
|
|
|
\func{bool}{Disconnect}{\param{int}{ id = \texttt{wxID\_ANY}},
|
|
\param{wxEventType }{eventType = wxEVT\_NULL}, \param{wxObjectEventFunction}{ function = NULL},
|
|
\param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}}
|
|
|
|
\func{bool}{Disconnect}{\param{int}{ id}, \param{int}{ lastId = \texttt{wxID\_ANY}},
|
|
\param{wxEventType }{eventType = wxEVT\_NULL}, \param{wxObjectEventFunction}{ function = NULL},
|
|
\param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}}
|
|
|
|
Disconnects the given function dynamically from the event handler, using the specified
|
|
parameters as search criteria and returning true if a matching function has been
|
|
found and removed. This method can only disconnect functions which have been added
|
|
using the \helpref{wxEvtHandler::Connect}{wxevthandlerconnect} method. There is no way
|
|
to disconnect functions connected using the (static) event tables.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{id}{The identifier (or first of the identifier range) associated with the event handler function.}
|
|
|
|
\docparam{lastId}{The second part of the identifier range associated with the event handler function.}
|
|
|
|
\docparam{eventType}{The event type associated with this event handler.}
|
|
|
|
\docparam{function}{The event handler function.}
|
|
|
|
\docparam{userData}{Data associated with the event table entry.}
|
|
|
|
\docparam{eventSink}{Object whose member function should be called.}
|
|
|
|
\perlnote{In wxPerl this function takes 3 arguments: \texttt{id,
|
|
lastid, type}.}
|
|
|
|
\membersection{wxEvtHandler::GetClientData}\label{wxevthandlergetclientdata}
|
|
|
|
\func{void* }{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::GetClientObject}\label{wxevthandlergetclientobject}
|
|
|
|
\constfunc{wxClientData*}{GetClientObject}{\void}
|
|
|
|
Get a pointer to the user-supplied client data object.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxEvtHandler::SetClientObject}{wxevthandlersetclientobject},
|
|
\helpref{wxClientData}{wxclientdata}
|
|
|
|
\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::SetNextHandler}{wxevthandlersetnexthandler},\rtfsp
|
|
\helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp
|
|
\helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\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::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp
|
|
\helpref{wxEvtHandler::GetNextHandler}{wxevthandlergetnexthandler},\rtfsp
|
|
\helpref{wxEvtHandler::SetNextHandler}{wxevthandlersetnexthandler},\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 wxWidgets
|
|
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 wxWidgets. 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{virtual 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{void* }{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. You must not call this method and
|
|
\helpref{SetClientObject}{wxevthandlersetclientobject} on the
|
|
same class - only one of them.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxEvtHandler::GetClientData}{wxevthandlergetclientdata}
|
|
|
|
\membersection{wxEvtHandler::SetClientObject}\label{wxevthandlersetclientobject}
|
|
|
|
\func{void}{SetClientObject}{\param{wxClientData* }{data}}
|
|
|
|
Set the client data object. Any previous object will be deleted.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxEvtHandler::GetClientObject}{wxevthandlergetclientobject},
|
|
\helpref{wxClientData}{wxclientdata}
|
|
|
|
\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}
|
|
|
|
|