| 1 | \section{\class{wxEvtHandler}}\label{wxevthandler} |
| 2 | |
| 3 | A class that can handle events from the windowing system. |
| 4 | wxWindow (and therefore all window classes) are derived from |
| 5 | this class. |
| 6 | |
| 7 | When events are received, wxEvtHandler invokes the method listed in the |
| 8 | event table using itself as the object. When using multiple inheritance |
| 9 | it is imperative that the wxEvtHandler(-derived) class be the first |
| 10 | class inherited such that the "this" pointer for the overall object |
| 11 | will 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 | |
| 31 | Constructor. |
| 32 | |
| 33 | \membersection{wxEvtHandler::\destruct{wxEvtHandler}}\label{wxevthandlerdtor} |
| 34 | |
| 35 | \func{}{\destruct{wxEvtHandler}}{\void} |
| 36 | |
| 37 | Destructor. If the handler is part of a chain, the destructor will |
| 38 | unlink itself and restore the previous and next handlers so that they point to |
| 39 | each other. |
| 40 | |
| 41 | \membersection{wxEvtHandler::AddPendingEvent}\label{wxevthandleraddpendingevent} |
| 42 | |
| 43 | \func{void}{AddPendingEvent}{\param{wxEvent\& }{event}} |
| 44 | |
| 45 | This 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 | |
| 53 | The difference between sending an event (using the |
| 54 | \helpref{ProcessEvent}{wxevthandlerprocessevent} method) and posting it is |
| 55 | that in the first case the event is processed before the function returns, |
| 56 | while in the second case, the function returns immediately and the event will |
| 57 | be processed sometime later (usually during the next event loop iteration). |
| 58 | |
| 59 | A copy of {\it event} is made by the function, so the original can be deleted |
| 60 | as soon as function returns (it is common that the original is created on the |
| 61 | stack). This requires that the \helpref{wxEvent::Clone}{wxeventclone} method |
| 62 | be implemented by {\it event} so that it can be duplicated and stored until |
| 63 | it gets processed. |
| 64 | |
| 65 | This is also the method to call for inter-thread communication---it will |
| 66 | post events safely between different threads which means that this method is |
| 67 | thread-safe by using critical sections where needed. In a multi-threaded |
| 68 | program, you often need to inform the main GUI thread about the status of |
| 69 | other working threads and such notification should be done using this method. |
| 70 | |
| 71 | This method automatically wakes up idle handling if the underlying window |
| 72 | system is currently idle and thus would not send any idle events. (Waking |
| 73 | up 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 | |
| 88 | Connects the given function dynamically with the event handler, id and event type. This |
| 89 | is 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 |
| 94 | associated with the event handler function. For the version not taking this |
| 95 | argument, 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 |
| 102 | be explicitly converted to the correct type which can be done using a macro |
| 103 | called \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, |
| 119 | lastid, type, method}; if \texttt{method} is \texttt{undef}, the |
| 120 | handler 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 | |
| 135 | Disconnects the given function dynamically from the event handler, using the specified |
| 136 | parameters as search criteria and returning true if a matching function has been |
| 137 | found and removed. This method can only disconnect functions which have been added |
| 138 | using the \helpref{wxEvtHandler::Connect}{wxevthandlerconnect} method. There is no way |
| 139 | to 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, |
| 156 | lastid, type}.} |
| 157 | |
| 158 | \membersection{wxEvtHandler::GetClientData}\label{wxevthandlergetclientdata} |
| 159 | |
| 160 | \func{void* }{GetClientData}{\void} |
| 161 | |
| 162 | Gets user-supplied client data. |
| 163 | |
| 164 | \wxheading{Remarks} |
| 165 | |
| 166 | Normally, any extra data the programmer wishes to associate with the object |
| 167 | should 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 | |
| 177 | Get 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 | |
| 188 | Returns 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 | |
| 198 | Gets 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 | |
| 212 | Gets 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 | |
| 226 | Processes 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 | |
| 234 | true if a suitable event handler function was found and executed, and the function did not |
| 235 | call \helpref{wxEvent::Skip}{wxeventskip}. |
| 236 | |
| 237 | \wxheading{Remarks} |
| 238 | |
| 239 | Normally, your application would not call this function: it is called in the wxWidgets |
| 240 | implementation to dispatch incoming user interface events to the framework (and application). |
| 241 | |
| 242 | However, you might need to call it if implementing new functionality (such as a new control) where |
| 243 | you define new event types, as opposed to allowing the user to override virtual functions. |
| 244 | |
| 245 | An instance where you might actually override the {\bf ProcessEvent} function is where you want |
| 246 | to direct event processing to event handlers not normally noticed by wxWidgets. For example, |
| 247 | in the document/view architecture, documents and views are potential event handlers. |
| 248 | When an event reaches a frame, {\bf ProcessEvent} will need to be called on the associated |
| 249 | document and view in case event handler functions are associated with these objects. |
| 250 | The property classes library (wxProperty) also overrides {\bf ProcessEvent} for similar reasons. |
| 251 | |
| 252 | The 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}) |
| 256 | the 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 |
| 260 | class table is tried, and so on until no more tables exist or an appropriate function was found, |
| 261 | in which case the function exits. |
| 262 | \item The search is applied down the entire chain of event handlers (usually the chain has a length |
| 263 | of one). If this succeeds, the function exits. |
| 264 | \item If the object is a wxWindow and the event is a wxCommandEvent, {\bf ProcessEvent} is |
| 265 | recursively 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 | |
| 277 | Searches the event table, executing an event handler function if an appropriate one |
| 278 | is 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 | |
| 288 | true if a suitable event handler function was found and executed, and the function did not |
| 289 | call \helpref{wxEvent::Skip}{wxeventskip}. |
| 290 | |
| 291 | \wxheading{Remarks} |
| 292 | |
| 293 | This function looks through the object's event table and tries to find an entry |
| 294 | that will match the event. |
| 295 | |
| 296 | An 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 | |
| 303 | If a suitable function is called but calls \helpref{wxEvent::Skip}{wxeventskip}, this function will |
| 304 | fail, 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 | |
| 314 | Sets 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 | |
| 322 | Normally, any extra data the programmer wishes to associate with |
| 323 | the object should be made available by deriving a new class |
| 324 | with new data members. You must not call this method and |
| 325 | \helpref{SetClientObject}{wxevthandlersetclientobject} on the |
| 326 | same 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 | |
| 336 | Set 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 | |
| 347 | Enables 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 | |
| 355 | You can use this function to avoid having to remove the event handler from the chain, for example |
| 356 | when 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 | |
| 366 | Sets 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 | |
| 384 | Sets 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 | |