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