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}
unlink itself and restore the previous and next handlers so that they point to
each other.
+\membersection{wxEvtHandler::AddPendingEvent}\label{wxevthandleraddpendingevent}
+
+\func{virtual 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{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function},
- \param{wxObject*}{ userData = NULL}}
+ \param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}}
\func{void}{Connect}{\param{int}{ id}, \param{int}{ lastId},
\param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function},
- \param{wxObject*}{ userData = NULL}}
+ \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 'dynamic' sample for usage.
\docparam{userData}{Data to be associated with the event table entry.}
+\docparam{eventSink}{Object whose member function should be called. If this is NULL,
+'this' will be used.}
+
\wxheading{Example}
\begin{verbatim}
(wxObjectEventFunction) (wxEventFunction) (wxCommandEventFunction) MyFrame::OnQuit );
\end{verbatim}
-\membersection{wxEvtHandler::Default}\label{wxevthandlerdefault}
+\perlnote{In wxPerl this function takes 4 arguments: \texttt{id,
+lastid, type, method}; if \texttt{method} is \texttt{undef}, the
+handler is disconnected.}
-\func{virtual long}{Default}{\void}
+\membersection{wxEvtHandler::Disconnect}\label{wxevthandlerdisconnect}
-Invokes default processing if this event handler is a window.
+\func{bool}{Disconnect}{\param{int}{ id},
+ \param{wxEventType }{eventType = wxEVT\_NULL}, \param{wxObjectEventFunction}{ function = NULL},
+ \param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}}
-\wxheading{Return value}
+\func{bool}{Disconnect}{\param{int}{ id}, \param{int}{ lastId = -1},
+ \param{wxEventType }{eventType = wxEVT\_NULL}, \param{wxObjectEventFunction}{ function = NULL},
+ \param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}}
-System dependent.
+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{Remarks}
+\wxheading{Parameters}
+
+\docparam{id}{The identifier (or first of the identifier range) associated with the event handler function.}
-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.
+\docparam{lastId}{The second part of the identifier range associated with the event handler function.}
-Normally the application should call a base member, such as \helpref{wxWindow::OnChar}{wxwindowonchar}, which itself
-may call {\bf Default}.
+\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{char* }{GetClientData}{\void}
+\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.
+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.
+Returns true if the event handler is enabled, false otherwise.
\wxheading{See also}
\wxheading{Return value}
-TRUE if a suitable event handler function was found and executed, and the function did not
+true if a suitable event handler function was found and executed, and the function did not
call \helpref{wxEvent::Skip}{wxeventskip}.
\wxheading{Remarks}
\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.
+\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.
+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{Return value}
-TRUE if a suitable event handler function was found and executed, and the function did not
+true if a suitable event handler function was found and executed, and the function did not
call \helpref{wxEvent::Skip}{wxeventskip}.
\wxheading{Remarks}
\membersection{wxEvtHandler::SetClientData}\label{wxevthandlersetclientdata}
-\func{void}{SetClientData}{\param{char* }{data}}
+\func{void}{SetClientData}{\param{void* }{data}}
Sets 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.
-%TODO: make this void*, char* only in compatibility mode.
+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}}
\wxheading{Parameters}
-\docparam{enabled}{TRUE if the event handler is to be enabled, FALSE if it is to be disabled.}
+\docparam{enabled}{true if the event handler is to be enabled, false if it is to be disabled.}
\wxheading{Remarks}
projects / wxWidgets.git / blobdiff