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::Connect}\label{wxevthandlerconnect}
  36
  37 \func{void}{Connect}{\param{int}{ id},
  38  \param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function},
  39  \param{wxObject*}{ userData = NULL}}
  40
  41 \func{void}{Connect}{\param{int}{ id}, \param{int}{ lastId},
  42  \param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function},
  43  \param{wxObject*}{ userData = NULL}}
  44
  45 Connects the given function dynamically with the event handler, id and event type. This
  46 is an alternative to the use of static event tables. See the 'dynamic' sample for usage.
  47
  48 \wxheading{Parameters}
  49
  50 \docparam{id}{The identifier (or first of the identifier range) to be associated with the event handler function.}
  51
  52 \docparam{lastId}{The second part of the identifier range to be associated with the event handler function.}
  53
  54 \docparam{eventType}{The event type to be associated with this event handler.}
  55
  56 \docparam{function}{The event handler function.}
  57
  58 \docparam{userData}{Data to be associated with the event table entry.}
  59
  60 \wxheading{Example}
  61
  62 \begin{verbatim}
  63   frame->Connect( wxID_EXIT,
  64     wxEVT_COMMAND_MENU_SELECTED,
  65     (wxObjectEventFunction) (wxEventFunction) (wxCommandEventFunction) MyFrame::OnQuit );
  66 \end{verbatim}
  67
  68 \membersection{wxEvtHandler::Default}\label{wxevthandlerdefault}
  69
  70 \func{virtual long}{Default}{\void}
  71
  72 Invokes default processing if this event handler is a window.
  73
  74 \wxheading{Return value}
  75
  76 System dependent.
  77
  78 \wxheading{Remarks}
  79
  80 A generic way of delegating processing to the default system behaviour. It calls a platform-dependent
  81 default function, with parameters dependent on the event or message parameters
  82 originally sent from the windowing system.
  83
  84 Normally the application should call a base member, such as \helpref{wxWindow::OnChar}{wxwindowonchar}, which itself
  85 may call {\bf Default}.
  86
  87 \membersection{wxEvtHandler::GetClientData}\label{wxevthandlergetclientdata}
  88
  89 \func{char* }{GetClientData}{\void}
  90
  91 Gets user-supplied client data.
  92
  93 \wxheading{Remarks}
  94
  95 Normally, any extra data the programmer wishes to associate with the object
  96 should be made available by deriving a new class
  97 with new data members.
  98
  99 \wxheading{See also}
 100
 101 \helpref{wxEvtHandler::SetClientData}{wxevthandlersetclientdata}
 102
 103 \membersection{wxEvtHandler::GetEvtHandlerEnabled}\label{wxevthandlergetevthandlerenabled}
 104
 105 \func{bool}{GetEvtHandlerEnabled}{\void}
 106
 107 Returns TRUE if the event handler is enabled, FALSE otherwise.
 108
 109 \wxheading{See also}
 110
 111 \helpref{wxEvtHandler::SetEvtHandlerEnabled}{wxevthandlersetevthandlerenabled}
 112
 113 \membersection{wxEvtHandler::GetNextHandler}\label{wxevthandlergetnexthandler}
 114
 115 \func{wxEvtHandler*}{GetNextHandler}{\void}
 116
 117 Gets the pointer to the next handler in the chain.
 118
 119 \wxheading{See also}
 120
 121 \helpref{wxEvtHandler::SetNextHandler}{wxevthandlersetnexthandler},\rtfsp
 122 \helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp
 123 \helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp
 124 \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
 125 \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler}
 126
 127 \membersection{wxEvtHandler::GetPreviousHandler}\label{wxevthandlergetprevioushandler}
 128
 129 \func{wxEvtHandler*}{GetPreviousHandler}{\void}
 130
 131 Gets the pointer to the previous handler in the chain.
 132
 133 \wxheading{See also}
 134
 135 \helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp
 136 \helpref{wxEvtHandler::GetNextHandler}{wxevthandlergetnexthandler},\rtfsp
 137 \helpref{wxEvtHandler::SetNextHandler}{wxevthandlersetnexthandler},\rtfsp
 138 \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
 139 \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler}
 140
 141 \membersection{wxEvtHandler::ProcessEvent}\label{wxevthandlerprocessevent}
 142
 143 \func{virtual bool}{ProcessEvent}{\param{wxEvent\& }{event}}
 144
 145 Processes an event, searching event tables and calling zero or more suitable event handler function(s).
 146
 147 \wxheading{Parameters}
 148
 149 \docparam{event}{Event to process.}
 150
 151 \wxheading{Return value}
 152
 153 TRUE if a suitable event handler function was found and executed, and the function did not
 154 call \helpref{wxEvent::Skip}{wxeventskip}.
 155
 156 \wxheading{Remarks}
 157
 158 Normally, your application would not call this function: it is called in the wxWindows
 159 implementation to dispatch incoming user interface events to the framework (and application).
 160
 161 However, you might need to call it if implementing new functionality (such as a new control) where
 162 you define new event types, as opposed to allowing the user to override virtual functions.
 163
 164 An instance where you might actually override the {\bf ProcessEvent} function is where you want
 165 to direct event processing to event handlers not normally noticed by wxWindows. For example,
 166 in the document/view architecture, documents and views are potential event handlers.
 167 When an event reaches a frame, {\bf ProcessEvent} will need to be called on the associated
 168 document and view in case event handler functions are associated with these objects.
 169 The property classes library (wxProperty) also overrides {\bf ProcessEvent} for similar reasons.
 170
 171 The normal order of event table searching is as follows:
 172
 173 \begin{enumerate}\itemsep=0pt
 174 \item If the object is disabled (via a call to \helpref{wxEvtHandler::SetEvtHandlerEnabled}{wxevthandlersetevthandlerenabled})
 175 the function skips to step (6).
 176 \item If the object is a wxWindow, {\bf ProcessEvent} is recursively called on the window's\rtfsp
 177 \helpref{wxValidator}{wxvalidator}. If this returns TRUE, the function exits.
 178 \item {\bf SearchEventTable} is called for this event handler. If this fails, the base
 179 class table is tried, and so on until no more tables exist or an appropriate function was found,
 180 in which case the function exits.
 181 \item The search is applied down the entire chain of event handlers (usually the chain has a length
 182 of one). If this succeeds, the function exits.
 183 \item If the object is a wxWindow and the event is a wxCommandEvent, {\bf ProcessEvent} is
 184 recursively applied to the parent window's event handler. If this returns TRUE, the function exits.
 185 \item Finally, {\bf ProcessEvent} is called on the wxApp object.
 186 \end{enumerate}
 187
 188 \wxheading{See also}
 189
 190 \helpref{wxEvtHandler::SearchEventTable}{wxevthandlersearcheventtable}
 191
 192 \membersection{wxEvtHandler::SearchEventTable}\label{wxevthandlersearcheventtable}
 193
 194 \func{bool}{SearchEventTable}{\param{wxEventTable\& }{table}, \param{wxEvent\& }{event}}
 195
 196 Searches the event table, executing an event handler function if an appropriate one
 197 is found.
 198
 199 \wxheading{Parameters}
 200
 201 \docparam{table}{Event table to be searched.}
 202
 203 \docparam{event}{Event to be matched against an event table entry.}
 204
 205 \wxheading{Return value}
 206
 207 TRUE if a suitable event handler function was found and executed, and the function did not
 208 call \helpref{wxEvent::Skip}{wxeventskip}.
 209
 210 \wxheading{Remarks}
 211
 212 This function looks through the object's event table and tries to find an entry
 213 that will match the event.
 214
 215 An entry will match if:
 216
 217 \begin{enumerate}\itemsep=0pt
 218 \item The event type matches, and
 219 \item the identifier or identifier range matches, or the event table entry's identifier is zero.
 220 \end{enumerate}
 221
 222 If a suitable function is called but calls \helpref{wxEvent::Skip}{wxeventskip}, this function will
 223 fail, and searching will continue.
 224
 225 \wxheading{See also}
 226
 227 \helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent}
 228
 229 \membersection{wxEvtHandler::SetClientData}\label{wxevthandlersetclientdata}
 230
 231 \func{void}{SetClientData}{\param{char* }{data}}
 232
 233 Sets user-supplied client data.
 234
 235 \wxheading{Parameters}
 236
 237 \docparam{data}{Data to be associated with the event handler.}
 238
 239 \wxheading{Remarks}
 240
 241 Normally, any extra data the programmer wishes
 242 to associate with the object should be made available by deriving a new class
 243 with new data members.
 244 %TODO: make this void*, char* only in compatibility mode.
 245
 246 \wxheading{See also}
 247
 248 \helpref{wxEvtHandler::GetClientData}{wxevthandlergetclientdata}
 249
 250 \membersection{wxEvtHandler::SetEvtHandlerEnabled}\label{wxevthandlersetevthandlerenabled}
 251
 252 \func{void}{SetEvtHandlerEnabled}{\param{bool }{enabled}}
 253
 254 Enables or disables the event handler.
 255
 256 \wxheading{Parameters}
 257
 258 \docparam{enabled}{TRUE if the event handler is to be enabled, FALSE if it is to be disabled.}
 259
 260 \wxheading{Remarks}
 261
 262 You can use this function to avoid having to remove the event handler from the chain, for example
 263 when implementing a dialog editor and changing from edit to test mode.
 264
 265 \wxheading{See also}
 266
 267 \helpref{wxEvtHandler::GetEvtHandlerEnabled}{wxevthandlergetevthandlerenabled}
 268
 269 \membersection{wxEvtHandler::SetNextHandler}\label{wxevthandlersetnexthandler}
 270
 271 \func{void}{SetNextHandler}{\param{wxEvtHandler* }{handler}}
 272
 273 Sets the pointer to the next handler.
 274
 275 \wxheading{Parameters}
 276
 277 \docparam{handler}{Event handler to be set as the next handler.}
 278
 279 \wxheading{See also}
 280
 281 \helpref{wxEvtHandler::GetNextHandler}{wxevthandlergetnexthandler},\rtfsp
 282 \helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp
 283 \helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp
 284 \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
 285 \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler}
 286
 287 \membersection{wxEvtHandler::SetPreviousHandler}\label{wxevthandlersetprevioushandler}
 288
 289 \func{void}{SetPreviousHandler}{\param{wxEvtHandler* }{handler}}
 290
 291 Sets the pointer to the previous handler.
 292
 293 \wxheading{Parameters}
 294
 295 \docparam{handler}{Event handler to be set as the previous handler.}
 296
 297 \wxheading{See also}
 298
 299 \helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp
 300 \helpref{wxEvtHandler::SetNextHandler}{wxevthandlersetnexthandler},\rtfsp
 301 \helpref{wxEvtHandler::GetNextHandler}{wxevthandlergetnexthandler},\rtfsp
 302 \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
 303 \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler}
 304
 305