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