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