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 Adds an event to be processed later. The function will return immediately and the
  40 event will get processed in idle time using the \helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent}
  41 method.
  42
  43 \wxheading{Parameters}
  44
  45 \docparam{event}{Event to add to process queue.}
  46
  47 \wxheading{Remarks}
  48
  49 Note that this requires that the event has a fully implemented Clone()
  50 method so that the event can be duplicated and stored until it gets processed later.
  51 Not all events in wxWindows currently have a fully implemented Clone() method,
  52 so you may have to look at the source to verify this.
  53
  54 This methods automatically wakes up idle handling even if the underlying window
  55 system is currently idle anyway and thus would not send any idle events. (Waking
  56 up the idle handling is done calling \helpref{::wxWakeUpIdle}{wxwakeupidle}.)
  57
  58 This is also the method to call for inter-thread communication. In
  59 a multi-threaded program, you will often have to inform the main GUI thread
  60 about the status of other working threads and this has to be done using this
  61 method - which also means that this method is thread safe by means of using
  62 crtical sections where needed.
  63
  64 Furthermore, it may be noted that some ports of wxWindows will probably move
  65 to using this method more and more in preference over calling ProcessEvent()
  66 directly so as to avoid problems with reentrant code.
  67
  68 \membersection{wxEvtHandler::Connect}\label{wxevthandlerconnect}
  69
  70 \func{void}{Connect}{\param{int}{ id},
  71  \param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function},
  72  \param{wxObject*}{ userData = NULL}}
  73
  74 \func{void}{Connect}{\param{int}{ id}, \param{int}{ lastId},
  75  \param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function},
  76  \param{wxObject*}{ userData = NULL}}
  77
  78 Connects the given function dynamically with the event handler, id and event type. This
  79 is an alternative to the use of static event tables. See the 'dynamic' sample for usage.
  80
  81 \wxheading{Parameters}
  82
  83 \docparam{id}{The identifier (or first of the identifier range) to be associated with the event handler function.}
  84
  85 \docparam{lastId}{The second part of the identifier range to be associated with the event handler function.}
  86
  87 \docparam{eventType}{The event type to be associated with this event handler.}
  88
  89 \docparam{function}{The event handler function.}
  90
  91 \docparam{userData}{Data to be associated with the event table entry.}
  92
  93 \wxheading{Example}
  94
  95 \begin{verbatim}
  96   frame->Connect( wxID_EXIT,
  97     wxEVT_COMMAND_MENU_SELECTED,
  98     (wxObjectEventFunction) (wxEventFunction) (wxCommandEventFunction) MyFrame::OnQuit );
  99 \end{verbatim}
 100
 101 \membersection{wxEvtHandler::Disconnect}\label{wxevthandlerdisconnect}
 102
 103 \func{bool}{Disconnect}{\param{int}{ id},
 104  \param{wxEventType }{eventType = wxEVT\_NULL}, \param{wxObjectEventFunction}{ function = NULL},
 105  \param{wxObject*}{ userData = NULL}}
 106
 107 \func{bool}{Disconnect}{\param{int}{ id}, \param{int}{ lastId = -1},
 108  \param{wxEventType }{eventType = wxEVT\_NULL}, \param{wxObjectEventFunction}{ function = NULL},
 109  \param{wxObject*}{ userData = NULL}}
 110
 111 Disconnects the given function dynamically from the event handler, using the specified
 112 parameters as search criteria and returning TRUE if a matching function has been
 113 found and removed. This method can only disconnect functions which have been added
 114 using the \helpref{wxEvtHandler::Connect}{wxevthandlerconnect} method. There is no way
 115 to disconnect functions connected using the (static) event tables.
 116
 117 \wxheading{Parameters}
 118
 119 \docparam{id}{The identifier (or first of the identifier range) associated with the event handler function.}
 120
 121 \docparam{lastId}{The second part of the identifier range associated with the event handler function.}
 122
 123 \docparam{eventType}{The event type associated with this event handler.}
 124
 125 \docparam{function}{The event handler function.}
 126
 127 \docparam{userData}{Data associated with the event table entry.}
 128
 129 \membersection{wxEvtHandler::GetClientData}\label{wxevthandlergetclientdata}
 130
 131 \func{void* }{GetClientData}{\void}
 132
 133 Gets user-supplied client data.
 134
 135 \wxheading{Remarks}
 136
 137 Normally, any extra data the programmer wishes to associate with the object
 138 should be made available by deriving a new class with new data members.
 139
 140 \wxheading{See also}
 141
 142 \helpref{wxEvtHandler::SetClientData}{wxevthandlersetclientdata}
 143
 144 \membersection{wxEvtHandler::GetEvtHandlerEnabled}\label{wxevthandlergetevthandlerenabled}
 145
 146 \func{bool}{GetEvtHandlerEnabled}{\void}
 147
 148 Returns TRUE if the event handler is enabled, FALSE otherwise.
 149
 150 \wxheading{See also}
 151
 152 \helpref{wxEvtHandler::SetEvtHandlerEnabled}{wxevthandlersetevthandlerenabled}
 153
 154 \membersection{wxEvtHandler::GetNextHandler}\label{wxevthandlergetnexthandler}
 155
 156 \func{wxEvtHandler*}{GetNextHandler}{\void}
 157
 158 Gets the pointer to the next handler in the chain.
 159
 160 \wxheading{See also}
 161
 162 \helpref{wxEvtHandler::SetNextHandler}{wxevthandlersetnexthandler},\rtfsp
 163 \helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp
 164 \helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp
 165 \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
 166 \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler}
 167
 168 \membersection{wxEvtHandler::GetPreviousHandler}\label{wxevthandlergetprevioushandler}
 169
 170 \func{wxEvtHandler*}{GetPreviousHandler}{\void}
 171
 172 Gets the pointer to the previous handler in the chain.
 173
 174 \wxheading{See also}
 175
 176 \helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp
 177 \helpref{wxEvtHandler::GetNextHandler}{wxevthandlergetnexthandler},\rtfsp
 178 \helpref{wxEvtHandler::SetNextHandler}{wxevthandlersetnexthandler},\rtfsp
 179 \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
 180 \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler}
 181
 182 \membersection{wxEvtHandler::ProcessEvent}\label{wxevthandlerprocessevent}
 183
 184 \func{virtual bool}{ProcessEvent}{\param{wxEvent\& }{event}}
 185
 186 Processes an event, searching event tables and calling zero or more suitable event handler function(s).
 187
 188 \wxheading{Parameters}
 189
 190 \docparam{event}{Event to process.}
 191
 192 \wxheading{Return value}
 193
 194 TRUE if a suitable event handler function was found and executed, and the function did not
 195 call \helpref{wxEvent::Skip}{wxeventskip}.
 196
 197 \wxheading{Remarks}
 198
 199 Normally, your application would not call this function: it is called in the wxWindows
 200 implementation to dispatch incoming user interface events to the framework (and application).
 201
 202 However, you might need to call it if implementing new functionality (such as a new control) where
 203 you define new event types, as opposed to allowing the user to override virtual functions.
 204
 205 An instance where you might actually override the {\bf ProcessEvent} function is where you want
 206 to direct event processing to event handlers not normally noticed by wxWindows. For example,
 207 in the document/view architecture, documents and views are potential event handlers.
 208 When an event reaches a frame, {\bf ProcessEvent} will need to be called on the associated
 209 document and view in case event handler functions are associated with these objects.
 210 The property classes library (wxProperty) also overrides {\bf ProcessEvent} for similar reasons.
 211
 212 The normal order of event table searching is as follows:
 213
 214 \begin{enumerate}\itemsep=0pt
 215 \item If the object is disabled (via a call to \helpref{wxEvtHandler::SetEvtHandlerEnabled}{wxevthandlersetevthandlerenabled})
 216 the function skips to step (6).
 217 \item If the object is a wxWindow, {\bf ProcessEvent} is recursively called on the window's\rtfsp
 218 \helpref{wxValidator}{wxvalidator}. If this returns TRUE, the function exits.
 219 \item {\bf SearchEventTable} is called for this event handler. If this fails, the base
 220 class table is tried, and so on until no more tables exist or an appropriate function was found,
 221 in which case the function exits.
 222 \item The search is applied down the entire chain of event handlers (usually the chain has a length
 223 of one). If this succeeds, the function exits.
 224 \item If the object is a wxWindow and the event is a wxCommandEvent, {\bf ProcessEvent} is
 225 recursively applied to the parent window's event handler. If this returns TRUE, the function exits.
 226 \item Finally, {\bf ProcessEvent} is called on the wxApp object.
 227 \end{enumerate}
 228
 229 \wxheading{See also}
 230
 231 \helpref{wxEvtHandler::SearchEventTable}{wxevthandlersearcheventtable}
 232
 233 \membersection{wxEvtHandler::SearchEventTable}\label{wxevthandlersearcheventtable}
 234
 235 \func{bool}{SearchEventTable}{\param{wxEventTable\& }{table}, \param{wxEvent\& }{event}}
 236
 237 Searches the event table, executing an event handler function if an appropriate one
 238 is found.
 239
 240 \wxheading{Parameters}
 241
 242 \docparam{table}{Event table to be searched.}
 243
 244 \docparam{event}{Event to be matched against an event table entry.}
 245
 246 \wxheading{Return value}
 247
 248 TRUE if a suitable event handler function was found and executed, and the function did not
 249 call \helpref{wxEvent::Skip}{wxeventskip}.
 250
 251 \wxheading{Remarks}
 252
 253 This function looks through the object's event table and tries to find an entry
 254 that will match the event.
 255
 256 An entry will match if:
 257
 258 \begin{enumerate}\itemsep=0pt
 259 \item The event type matches, and
 260 \item the identifier or identifier range matches, or the event table entry's identifier is zero.
 261 \end{enumerate}
 262
 263 If a suitable function is called but calls \helpref{wxEvent::Skip}{wxeventskip}, this function will
 264 fail, and searching will continue.
 265
 266 \wxheading{See also}
 267
 268 \helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent}
 269
 270 \membersection{wxEvtHandler::SetClientData}\label{wxevthandlersetclientdata}
 271
 272 \func{void}{SetClientData}{\param{void* }{data}}
 273
 274 Sets user-supplied client data.
 275
 276 \wxheading{Parameters}
 277
 278 \docparam{data}{Data to be associated with the event handler.}
 279
 280 \wxheading{Remarks}
 281
 282 Normally, any extra data the programmer wishes to associate with
 283 the object should be made available by deriving a new class
 284 with new data members.
 285
 286 \wxheading{See also}
 287
 288 \helpref{wxEvtHandler::GetClientData}{wxevthandlergetclientdata}
 289
 290 \membersection{wxEvtHandler::SetEvtHandlerEnabled}\label{wxevthandlersetevthandlerenabled}
 291
 292 \func{void}{SetEvtHandlerEnabled}{\param{bool }{enabled}}
 293
 294 Enables or disables the event handler.
 295
 296 \wxheading{Parameters}
 297
 298 \docparam{enabled}{TRUE if the event handler is to be enabled, FALSE if it is to be disabled.}
 299
 300 \wxheading{Remarks}
 301
 302 You can use this function to avoid having to remove the event handler from the chain, for example
 303 when implementing a dialog editor and changing from edit to test mode.
 304
 305 \wxheading{See also}
 306
 307 \helpref{wxEvtHandler::GetEvtHandlerEnabled}{wxevthandlergetevthandlerenabled}
 308
 309 \membersection{wxEvtHandler::SetNextHandler}\label{wxevthandlersetnexthandler}
 310
 311 \func{void}{SetNextHandler}{\param{wxEvtHandler* }{handler}}
 312
 313 Sets the pointer to the next handler.
 314
 315 \wxheading{Parameters}
 316
 317 \docparam{handler}{Event handler to be set as the next handler.}
 318
 319 \wxheading{See also}
 320
 321 \helpref{wxEvtHandler::GetNextHandler}{wxevthandlergetnexthandler},\rtfsp
 322 \helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp
 323 \helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp
 324 \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
 325 \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler}
 326
 327 \membersection{wxEvtHandler::SetPreviousHandler}\label{wxevthandlersetprevioushandler}
 328
 329 \func{void}{SetPreviousHandler}{\param{wxEvtHandler* }{handler}}
 330
 331 Sets the pointer to the previous handler.
 332
 333 \wxheading{Parameters}
 334
 335 \docparam{handler}{Event handler to be set as the previous handler.}
 336
 337 \wxheading{See also}
 338
 339 \helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp
 340 \helpref{wxEvtHandler::SetNextHandler}{wxevthandlersetnexthandler},\rtfsp
 341 \helpref{wxEvtHandler::GetNextHandler}{wxevthandlergetnexthandler},\rtfsp
 342 \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
 343 \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler}
 344
 345