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