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