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