docs/latex/wx/evthand.tex

   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},
  78  \param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function},
  79  \param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}}
  80
  81 \func{void}{Connect}{\param{int}{ id}, \param{int}{ lastId},
  82  \param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function},
  83  \param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}}
  84
  85 Connects the given function dynamically with the event handler, id and event type. This
  86 is an alternative to the use of static event tables. See the 'event' or the old 'dynamic' sample for usage.
  87
  88 \wxheading{Parameters}
  89
  90 \docparam{id}{The identifier (or first of the identifier range) to be associated with the event handler function.}
  91
  92 \docparam{lastId}{The second part of the identifier range to be associated with the event handler function.}
  93
  94 \docparam{eventType}{The event type to be associated with this event handler.}
  95
  96 \docparam{function}{The event handler function.}
  97
  98 \docparam{userData}{Data to be associated with the event table entry.}
  99
 100 \docparam{eventSink}{Object whose member function should be called. If this is NULL,
 101 'this' will be used.}
 102
 103 \wxheading{Example}
 104
 105 \begin{verbatim}
 106   frame->Connect( wxID_EXIT,
 107     wxEVT_COMMAND_MENU_SELECTED,
 108     (wxObjectEventFunction) (wxEventFunction) (wxCommandEventFunction) MyFrame::OnQuit );
 109 \end{verbatim}
 110
 111 \perlnote{In wxPerl this function takes 4 arguments: \texttt{id,
 112 lastid, type, method}; if \texttt{method} is \texttt{undef}, the
 113 handler is disconnected.}
 114
 115 \membersection{wxEvtHandler::Disconnect}\label{wxevthandlerdisconnect}
 116
 117 \func{bool}{Disconnect}{\param{int}{ id},
 118  \param{wxEventType }{eventType = wxEVT\_NULL}, \param{wxObjectEventFunction}{ function = NULL},
 119  \param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}}
 120
 121 \func{bool}{Disconnect}{\param{int}{ id}, \param{int}{ lastId = -1},
 122  \param{wxEventType }{eventType = wxEVT\_NULL}, \param{wxObjectEventFunction}{ function = NULL},
 123  \param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}}
 124
 125 Disconnects the given function dynamically from the event handler, using the specified
 126 parameters as search criteria and returning true if a matching function has been
 127 found and removed. This method can only disconnect functions which have been added
 128 using the \helpref{wxEvtHandler::Connect}{wxevthandlerconnect} method. There is no way
 129 to disconnect functions connected using the (static) event tables.
 130
 131 \wxheading{Parameters}
 132
 133 \docparam{id}{The identifier (or first of the identifier range) associated with the event handler function.}
 134
 135 \docparam{lastId}{The second part of the identifier range associated with the event handler function.}
 136
 137 \docparam{eventType}{The event type associated with this event handler.}
 138
 139 \docparam{function}{The event handler function.}
 140
 141 \docparam{userData}{Data associated with the event table entry.}
 142
 143 \docparam{eventSink}{Object whose member function should be called.}
 144
 145 \perlnote{In wxPerl this function takes 3 arguments: \texttt{id,
 146 lastid, type}.}
 147
 148 \membersection{wxEvtHandler::GetClientData}\label{wxevthandlergetclientdata}
 149
 150 \func{void* }{GetClientData}{\void}
 151
 152 Gets user-supplied client data.
 153
 154 \wxheading{Remarks}
 155
 156 Normally, any extra data the programmer wishes to associate with the object
 157 should be made available by deriving a new class with new data members.
 158
 159 \wxheading{See also}
 160
 161 \helpref{wxEvtHandler::SetClientData}{wxevthandlersetclientdata}
 162
 163 \membersection{wxEvtHandler::GetClientObject}\label{wxevthandlergetclientobject}
 164
 165 \constfunc{wxClientData*}{GetClientObject}{\void}
 166
 167 Get a pointer to the user-supplied client data object.
 168
 169 \wxheading{See also}
 170
 171 \helpref{wxEvtHandler::SetClientObject}{wxevthandlersetclientobject},
 172 \helpref{wxClientData}{wxclientdata}
 173
 174 \membersection{wxEvtHandler::GetEvtHandlerEnabled}\label{wxevthandlergetevthandlerenabled}
 175
 176 \func{bool}{GetEvtHandlerEnabled}{\void}
 177
 178 Returns true if the event handler is enabled, false otherwise.
 179
 180 \wxheading{See also}
 181
 182 \helpref{wxEvtHandler::SetEvtHandlerEnabled}{wxevthandlersetevthandlerenabled}
 183
 184 \membersection{wxEvtHandler::GetNextHandler}\label{wxevthandlergetnexthandler}
 185
 186 \func{wxEvtHandler*}{GetNextHandler}{\void}
 187
 188 Gets the pointer to the next handler in the chain.
 189
 190 \wxheading{See also}
 191
 192 \helpref{wxEvtHandler::SetNextHandler}{wxevthandlersetnexthandler},\rtfsp
 193 \helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp
 194 \helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp
 195 \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
 196 \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler}
 197
 198 \membersection{wxEvtHandler::GetPreviousHandler}\label{wxevthandlergetprevioushandler}
 199
 200 \func{wxEvtHandler*}{GetPreviousHandler}{\void}
 201
 202 Gets the pointer to the previous handler in the chain.
 203
 204 \wxheading{See also}
 205
 206 \helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp
 207 \helpref{wxEvtHandler::GetNextHandler}{wxevthandlergetnexthandler},\rtfsp
 208 \helpref{wxEvtHandler::SetNextHandler}{wxevthandlersetnexthandler},\rtfsp
 209 \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
 210 \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler}
 211
 212 \membersection{wxEvtHandler::ProcessEvent}\label{wxevthandlerprocessevent}
 213
 214 \func{virtual bool}{ProcessEvent}{\param{wxEvent\& }{event}}
 215
 216 Processes an event, searching event tables and calling zero or more suitable event handler function(s).
 217
 218 \wxheading{Parameters}
 219
 220 \docparam{event}{Event to process.}
 221
 222 \wxheading{Return value}
 223
 224 true if a suitable event handler function was found and executed, and the function did not
 225 call \helpref{wxEvent::Skip}{wxeventskip}.
 226
 227 \wxheading{Remarks}
 228
 229 Normally, your application would not call this function: it is called in the wxWidgets
 230 implementation to dispatch incoming user interface events to the framework (and application).
 231
 232 However, you might need to call it if implementing new functionality (such as a new control) where
 233 you define new event types, as opposed to allowing the user to override virtual functions.
 234
 235 An instance where you might actually override the {\bf ProcessEvent} function is where you want
 236 to direct event processing to event handlers not normally noticed by wxWidgets. For example,
 237 in the document/view architecture, documents and views are potential event handlers.
 238 When an event reaches a frame, {\bf ProcessEvent} will need to be called on the associated
 239 document and view in case event handler functions are associated with these objects.
 240 The property classes library (wxProperty) also overrides {\bf ProcessEvent} for similar reasons.
 241
 242 The normal order of event table searching is as follows:
 243
 244 \begin{enumerate}\itemsep=0pt
 245 \item If the object is disabled (via a call to \helpref{wxEvtHandler::SetEvtHandlerEnabled}{wxevthandlersetevthandlerenabled})
 246 the function skips to step (6).
 247 \item If the object is a wxWindow, {\bf ProcessEvent} is recursively called on the window's\rtfsp
 248 \helpref{wxValidator}{wxvalidator}. If this returns true, the function exits.
 249 \item {\bf SearchEventTable} is called for this event handler. If this fails, the base
 250 class table is tried, and so on until no more tables exist or an appropriate function was found,
 251 in which case the function exits.
 252 \item The search is applied down the entire chain of event handlers (usually the chain has a length
 253 of one). If this succeeds, the function exits.
 254 \item If the object is a wxWindow and the event is a wxCommandEvent, {\bf ProcessEvent} is
 255 recursively applied to the parent window's event handler. If this returns true, the function exits.
 256 \item Finally, {\bf ProcessEvent} is called on the wxApp object.
 257 \end{enumerate}
 258
 259 \wxheading{See also}
 260
 261 \helpref{wxEvtHandler::SearchEventTable}{wxevthandlersearcheventtable}
 262
 263 \membersection{wxEvtHandler::SearchEventTable}\label{wxevthandlersearcheventtable}
 264
 265 \func{bool}{SearchEventTable}{\param{wxEventTable\& }{table}, \param{wxEvent\& }{event}}
 266
 267 Searches the event table, executing an event handler function if an appropriate one
 268 is found.
 269
 270 \wxheading{Parameters}
 271
 272 \docparam{table}{Event table to be searched.}
 273
 274 \docparam{event}{Event to be matched against an event table entry.}
 275
 276 \wxheading{Return value}
 277
 278 true if a suitable event handler function was found and executed, and the function did not
 279 call \helpref{wxEvent::Skip}{wxeventskip}.
 280
 281 \wxheading{Remarks}
 282
 283 This function looks through the object's event table and tries to find an entry
 284 that will match the event.
 285
 286 An entry will match if:
 287
 288 \begin{enumerate}\itemsep=0pt
 289 \item The event type matches, and
 290 \item the identifier or identifier range matches, or the event table entry's identifier is zero.
 291 \end{enumerate}
 292
 293 If a suitable function is called but calls \helpref{wxEvent::Skip}{wxeventskip}, this function will
 294 fail, and searching will continue.
 295
 296 \wxheading{See also}
 297
 298 \helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent}
 299
 300 \membersection{wxEvtHandler::SetClientData}\label{wxevthandlersetclientdata}
 301
 302 \func{void}{SetClientData}{\param{void* }{data}}
 303
 304 Sets user-supplied client data.
 305
 306 \wxheading{Parameters}
 307
 308 \docparam{data}{Data to be associated with the event handler.}
 309
 310 \wxheading{Remarks}
 311
 312 Normally, any extra data the programmer wishes to associate with
 313 the object should be made available by deriving a new class
 314 with new data members. You must not call this method and
 315 \helpref{SetClientObject}{wxevthandlersetclientobject} on the
 316 same class - only one of them.
 317
 318 \wxheading{See also}
 319
 320 \helpref{wxEvtHandler::GetClientData}{wxevthandlergetclientdata}
 321
 322 \membersection{wxEvtHandler::SetClientObject}\label{wxevthandlersetclientobject}
 323
 324 \func{void}{SetClientObject}{\param{wxClientData* }{data}}
 325
 326 Set the client data object. Any previous object will be deleted.
 327
 328 \wxheading{See also}
 329
 330 \helpref{wxEvtHandler::GetClientObject}{wxevthandlergetclientobject},
 331 \helpref{wxClientData}{wxclientdata}
 332
 333 \membersection{wxEvtHandler::SetEvtHandlerEnabled}\label{wxevthandlersetevthandlerenabled}
 334
 335 \func{void}{SetEvtHandlerEnabled}{\param{bool }{enabled}}
 336
 337 Enables or disables the event handler.
 338
 339 \wxheading{Parameters}
 340
 341 \docparam{enabled}{true if the event handler is to be enabled, false if it is to be disabled.}
 342
 343 \wxheading{Remarks}
 344
 345 You can use this function to avoid having to remove the event handler from the chain, for example
 346 when implementing a dialog editor and changing from edit to test mode.
 347
 348 \wxheading{See also}
 349
 350 \helpref{wxEvtHandler::GetEvtHandlerEnabled}{wxevthandlergetevthandlerenabled}
 351
 352 \membersection{wxEvtHandler::SetNextHandler}\label{wxevthandlersetnexthandler}
 353
 354 \func{void}{SetNextHandler}{\param{wxEvtHandler* }{handler}}
 355
 356 Sets the pointer to the next handler.
 357
 358 \wxheading{Parameters}
 359
 360 \docparam{handler}{Event handler to be set as the next handler.}
 361
 362 \wxheading{See also}
 363
 364 \helpref{wxEvtHandler::GetNextHandler}{wxevthandlergetnexthandler},\rtfsp
 365 \helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp
 366 \helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp
 367 \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
 368 \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler}
 369
 370 \membersection{wxEvtHandler::SetPreviousHandler}\label{wxevthandlersetprevioushandler}
 371
 372 \func{void}{SetPreviousHandler}{\param{wxEvtHandler* }{handler}}
 373
 374 Sets the pointer to the previous handler.
 375
 376 \wxheading{Parameters}
 377
 378 \docparam{handler}{Event handler to be set as the previous handler.}
 379
 380 \wxheading{See also}
 381
 382 \helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp
 383 \helpref{wxEvtHandler::SetNextHandler}{wxevthandlersetnexthandler},\rtfsp
 384 \helpref{wxEvtHandler::GetNextHandler}{wxevthandlergetnexthandler},\rtfsp
 385 \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
 386 \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler}
 387
 388