1\section{\class{wxEvtHandler}}\label{wxevthandler} 2 3A class that can handle events from the windowing system. 4wxWindow (and therefore all window classes) are derived from 5this class. 6 7When events are received, wxEvtHandler invokes the method listed in the 8event table using itself as the object. When using multiple inheritance 9it is imperative that the wxEvtHandler(-derived) class be the first 10class inherited such that the "this" pointer for the overall object 11will be identical to the "this" pointer for the wxEvtHandler portion. 12 13\wxheading{Derived from} 14 15\helpref{wxObject}{wxobject} 16 17\wxheading{Include files} 18 19<wx/event.h> 20 21\wxheading{See also} 22 23\overview{Event handling overview}{eventhandlingoverview} 24 25\latexignore{\rtfignore{\wxheading{Members}}} 26 27\membersection{wxEvtHandler::wxEvtHandler}\label{wxevthandlerctor} 28 29\func{}{wxEvtHandler}{\void} 30 31Constructor. 32 33\membersection{wxEvtHandler::\destruct{wxEvtHandler}}\label{wxevthandlerdtor} 34 35\func{}{\destruct{wxEvtHandler}}{\void} 36 37Destructor. If the handler is part of a chain, the destructor will 38unlink itself and restore the previous and next handlers so that they point to 39each other. 40 41\membersection{wxEvtHandler::AddPendingEvent}\label{wxevthandleraddpendingevent} 42 43\func{void}{AddPendingEvent}{\param{wxEvent\& }{event}} 44 45This function posts an event to be processed later. 46 47\wxheading{Parameters} 48 49\docparam{event}{Event to add to process queue.} 50 51\wxheading{Remarks} 52 53The difference between sending an event (using the 54\helpref{ProcessEvent}{wxevthandlerprocessevent} method) and posting it is 55that in the first case the event is processed before the function returns, 56while in the second case, the function returns immediately and the event will 57be processed sometime later (usually during the next event loop iteration). 58 59A copy of {\it event} is made by the function, so the original can be deleted 60as soon as function returns (it is common that the original is created on the 61stack). This requires that the \helpref{wxEvent::Clone}{wxeventclone} method 62be implemented by {\it event} so that it can be duplicated and stored until 63it gets processed. 64 65This is also the method to call for inter-thread communication---it will 66post events safely between different threads which means that this method is 67thread-safe by using critical sections where needed. In a multi-threaded 68program, you often need to inform the main GUI thread about the status of 69other working threads and such notification should be done using this method. 70 71This method automatically wakes up idle handling if the underlying window 72system is currently idle and thus would not send any idle events. (Waking 73up idle handling is done calling \helpref{::wxWakeUpIdle}{wxwakeupidle}.) 74 75\membersection{wxEvtHandler::Connect}\label{wxevthandlerconnect} 76 77\func{void}{Connect}{\param{int}{ id}, \param{int}{ lastId}, 78 \param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function}, 79 \param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}} 80 81\func{void}{Connect}{\param{int}{ id}, 82 \param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function}, 83 \param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}} 84 85\func{void}{Connect}{\param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function}, 86 \param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}} 87 88Connects the given function dynamically with the event handler, id and event type. This 89is an alternative to the use of static event tables. See the 'event' or the old 'dynamic' sample for usage. 90 91\wxheading{Parameters} 92 93\docparam{id}{The identifier (or first of the identifier range) to be 94associated with the event handler function. For the version not taking this 95argument, it defaults to \texttt{wxID\_ANY}.} 96 97\docparam{lastId}{The second part of the identifier range to be associated with the event handler function.} 98 99\docparam{eventType}{The event type to be associated with this event handler.} 100 101\docparam{function}{The event handler function. Note that this function should 102be explicitly converted to the correct type which can be done using a macro 103called \texttt{wxFooHandler} for the handler for any \texttt{wxFooEvent}.} 104 105\docparam{userData}{Data to be associated with the event table entry.} 106 107\docparam{eventSink}{Object whose member function should be called. If this is NULL, 108\textit{this} will be used.} 109 110\wxheading{Example} 111 112\begin{verbatim} 113 frame->Connect( wxID_EXIT, 114 wxEVT_COMMAND_MENU_SELECTED, 115 wxCommandEventHandler(MyFrame::OnQuit) ); 116\end{verbatim} 117 118\perlnote{In wxPerl this function takes 4 arguments: \texttt{id, 119lastid, type, method}; if \texttt{method} is \texttt{undef}, the 120handler is disconnected.} 121 122\membersection{wxEvtHandler::Disconnect}\label{wxevthandlerdisconnect} 123 124\func{bool}{Disconnect}{\param{wxEventType }{eventType = wxEVT\_NULL}, \param{wxObjectEventFunction}{ function = NULL}, 125 \param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}} 126 127\func{bool}{Disconnect}{\param{int}{ id = \texttt{wxID\_ANY}}, 128 \param{wxEventType }{eventType = wxEVT\_NULL}, \param{wxObjectEventFunction}{ function = NULL}, 129 \param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}} 130 131\func{bool}{Disconnect}{\param{int}{ id}, \param{int}{ lastId = \texttt{wxID\_ANY}}, 132 \param{wxEventType }{eventType = wxEVT\_NULL}, \param{wxObjectEventFunction}{ function = NULL}, 133 \param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}} 134 135Disconnects the given function dynamically from the event handler, using the specified 136parameters as search criteria and returning true if a matching function has been 137found and removed. This method can only disconnect functions which have been added 138using the \helpref{wxEvtHandler::Connect}{wxevthandlerconnect} method. There is no way 139to disconnect functions connected using the (static) event tables. 140 141\wxheading{Parameters} 142 143\docparam{id}{The identifier (or first of the identifier range) associated with the event handler function.} 144 145\docparam{lastId}{The second part of the identifier range associated with the event handler function.} 146 147\docparam{eventType}{The event type associated with this event handler.} 148 149\docparam{function}{The event handler function.} 150 151\docparam{userData}{Data associated with the event table entry.} 152 153\docparam{eventSink}{Object whose member function should be called.} 154 155\perlnote{In wxPerl this function takes 3 arguments: \texttt{id, 156lastid, type}.} 157 158\membersection{wxEvtHandler::GetClientData}\label{wxevthandlergetclientdata} 159 160\func{void* }{GetClientData}{\void} 161 162Gets user-supplied client data. 163 164\wxheading{Remarks} 165 166Normally, any extra data the programmer wishes to associate with the object 167should be made available by deriving a new class with new data members. 168 169\wxheading{See also} 170 171\helpref{wxEvtHandler::SetClientData}{wxevthandlersetclientdata} 172 173\membersection{wxEvtHandler::GetClientObject}\label{wxevthandlergetclientobject} 174 175\constfunc{wxClientData*}{GetClientObject}{\void} 176 177Get a pointer to the user-supplied client data object. 178 179\wxheading{See also} 180 181\helpref{wxEvtHandler::SetClientObject}{wxevthandlersetclientobject}, 182\helpref{wxClientData}{wxclientdata} 183 184\membersection{wxEvtHandler::GetEvtHandlerEnabled}\label{wxevthandlergetevthandlerenabled} 185 186\func{bool}{GetEvtHandlerEnabled}{\void} 187 188Returns true if the event handler is enabled, false otherwise. 189 190\wxheading{See also} 191 192\helpref{wxEvtHandler::SetEvtHandlerEnabled}{wxevthandlersetevthandlerenabled} 193 194\membersection{wxEvtHandler::GetNextHandler}\label{wxevthandlergetnexthandler} 195 196\func{wxEvtHandler*}{GetNextHandler}{\void} 197 198Gets the pointer to the next handler in the chain. 199 200\wxheading{See also} 201 202\helpref{wxEvtHandler::SetNextHandler}{wxevthandlersetnexthandler},\rtfsp 203\helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp 204\helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp 205\helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp 206\helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler} 207 208\membersection{wxEvtHandler::GetPreviousHandler}\label{wxevthandlergetprevioushandler} 209 210\func{wxEvtHandler*}{GetPreviousHandler}{\void} 211 212Gets the pointer to the previous handler in the chain. 213 214\wxheading{See also} 215 216\helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp 217\helpref{wxEvtHandler::GetNextHandler}{wxevthandlergetnexthandler},\rtfsp 218\helpref{wxEvtHandler::SetNextHandler}{wxevthandlersetnexthandler},\rtfsp 219\helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp 220\helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler} 221 222\membersection{wxEvtHandler::ProcessEvent}\label{wxevthandlerprocessevent} 223 224\func{virtual bool}{ProcessEvent}{\param{wxEvent\& }{event}} 225 226Processes an event, searching event tables and calling zero or more suitable event handler function(s). 227 228\wxheading{Parameters} 229 230\docparam{event}{Event to process.} 231 232\wxheading{Return value} 233 234true if a suitable event handler function was found and executed, and the function did not 235call \helpref{wxEvent::Skip}{wxeventskip}. 236 237\wxheading{Remarks} 238 239Normally, your application would not call this function: it is called in the wxWidgets 240implementation to dispatch incoming user interface events to the framework (and application). 241 242However, you might need to call it if implementing new functionality (such as a new control) where 243you define new event types, as opposed to allowing the user to override virtual functions. 244 245An instance where you might actually override the {\bf ProcessEvent} function is where you want 246to direct event processing to event handlers not normally noticed by wxWidgets. For example, 247in the document/view architecture, documents and views are potential event handlers. 248When an event reaches a frame, {\bf ProcessEvent} will need to be called on the associated 249document and view in case event handler functions are associated with these objects. 250The property classes library (wxProperty) also overrides {\bf ProcessEvent} for similar reasons. 251 252The normal order of event table searching is as follows: 253 254\begin{enumerate}\itemsep=0pt 255\item If the object is disabled (via a call to \helpref{wxEvtHandler::SetEvtHandlerEnabled}{wxevthandlersetevthandlerenabled}) 256the function skips to step (6). 257\item If the object is a wxWindow, {\bf ProcessEvent} is recursively called on the window's\rtfsp 258\helpref{wxValidator}{wxvalidator}. If this returns true, the function exits. 259\item {\bf SearchEventTable} is called for this event handler. If this fails, the base 260class table is tried, and so on until no more tables exist or an appropriate function was found, 261in which case the function exits. 262\item The search is applied down the entire chain of event handlers (usually the chain has a length 263of one). If this succeeds, the function exits. 264\item If the object is a wxWindow and the event is a wxCommandEvent, {\bf ProcessEvent} is 265recursively applied to the parent window's event handler. If this returns true, the function exits. 266\item Finally, {\bf ProcessEvent} is called on the wxApp object. 267\end{enumerate} 268 269\wxheading{See also} 270 271\helpref{wxEvtHandler::SearchEventTable}{wxevthandlersearcheventtable} 272 273\membersection{wxEvtHandler::SearchEventTable}\label{wxevthandlersearcheventtable} 274 275\func{virtual bool}{SearchEventTable}{\param{wxEventTable\& }{table}, \param{wxEvent\& }{event}} 276 277Searches the event table, executing an event handler function if an appropriate one 278is found. 279 280\wxheading{Parameters} 281 282\docparam{table}{Event table to be searched.} 283 284\docparam{event}{Event to be matched against an event table entry.} 285 286\wxheading{Return value} 287 288true if a suitable event handler function was found and executed, and the function did not 289call \helpref{wxEvent::Skip}{wxeventskip}. 290 291\wxheading{Remarks} 292 293This function looks through the object's event table and tries to find an entry 294that will match the event. 295 296An entry will match if: 297 298\begin{enumerate}\itemsep=0pt 299\item The event type matches, and 300\item the identifier or identifier range matches, or the event table entry's identifier is zero. 301\end{enumerate} 302 303If a suitable function is called but calls \helpref{wxEvent::Skip}{wxeventskip}, this function will 304fail, and searching will continue. 305 306\wxheading{See also} 307 308\helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent} 309 310\membersection{wxEvtHandler::SetClientData}\label{wxevthandlersetclientdata} 311 312\func{void}{SetClientData}{\param{void* }{data}} 313 314Sets user-supplied client data. 315 316\wxheading{Parameters} 317 318\docparam{data}{Data to be associated with the event handler.} 319 320\wxheading{Remarks} 321 322Normally, any extra data the programmer wishes to associate with 323the object should be made available by deriving a new class 324with new data members. You must not call this method and 325\helpref{SetClientObject}{wxevthandlersetclientobject} on the 326same class - only one of them. 327 328\wxheading{See also} 329 330\helpref{wxEvtHandler::GetClientData}{wxevthandlergetclientdata} 331 332\membersection{wxEvtHandler::SetClientObject}\label{wxevthandlersetclientobject} 333 334\func{void}{SetClientObject}{\param{wxClientData* }{data}} 335 336Set the client data object. Any previous object will be deleted. 337 338\wxheading{See also} 339 340\helpref{wxEvtHandler::GetClientObject}{wxevthandlergetclientobject}, 341\helpref{wxClientData}{wxclientdata} 342 343\membersection{wxEvtHandler::SetEvtHandlerEnabled}\label{wxevthandlersetevthandlerenabled} 344 345\func{void}{SetEvtHandlerEnabled}{\param{bool }{enabled}} 346 347Enables or disables the event handler. 348 349\wxheading{Parameters} 350 351\docparam{enabled}{true if the event handler is to be enabled, false if it is to be disabled.} 352 353\wxheading{Remarks} 354 355You can use this function to avoid having to remove the event handler from the chain, for example 356when implementing a dialog editor and changing from edit to test mode. 357 358\wxheading{See also} 359 360\helpref{wxEvtHandler::GetEvtHandlerEnabled}{wxevthandlergetevthandlerenabled} 361 362\membersection{wxEvtHandler::SetNextHandler}\label{wxevthandlersetnexthandler} 363 364\func{void}{SetNextHandler}{\param{wxEvtHandler* }{handler}} 365 366Sets the pointer to the next handler. 367 368\wxheading{Parameters} 369 370\docparam{handler}{Event handler to be set as the next handler.} 371 372\wxheading{See also} 373 374\helpref{wxEvtHandler::GetNextHandler}{wxevthandlergetnexthandler},\rtfsp 375\helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp 376\helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp 377\helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp 378\helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler} 379 380\membersection{wxEvtHandler::SetPreviousHandler}\label{wxevthandlersetprevioushandler} 381 382\func{void}{SetPreviousHandler}{\param{wxEvtHandler* }{handler}} 383 384Sets the pointer to the previous handler. 385 386\wxheading{Parameters} 387 388\docparam{handler}{Event handler to be set as the previous handler.} 389 390\wxheading{See also} 391 392\helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp 393\helpref{wxEvtHandler::SetNextHandler}{wxevthandlersetnexthandler},\rtfsp 394\helpref{wxEvtHandler::GetNextHandler}{wxevthandlergetnexthandler},\rtfsp 395\helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp 396\helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler} 397 398 399