]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/evthand.tex
don't call wxYield() from EnsureVisible(), this is too dangerous - and unnecessary...
[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 Adds an event to be processed later. The function will return immediately and the
40 event will get processed in idle time using the \helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent}
41 method.
42
43 \wxheading{Parameters}
44
45 \docparam{event}{Event to add to process queue.}
46
47 \wxheading{Remarks}
48
49 Note that this requires that the event implements
50 \helpref{CopyObject}{wxobjectcopyobject}
51 method so that the event can be duplicated and stored until it gets processed later.
52 Not all events in wxWindows currently fully implement this method,
53 so you may have to look at the source to verify this.
54
55 This methods automatically wakes up idle handling even if the underlying window
56 system is currently idle anyway and thus would not send any idle events. (Waking
57 up the idle handling is done calling \helpref{::wxWakeUpIdle}{wxwakeupidle}.)
58
59 This is also the method to call for inter-thread communication. In
60 a multi-threaded program, you will often have to inform the main GUI thread
61 about the status of other working threads and this has to be done using this
62 method - which also means that this method is thread safe by means of using
63 crtical sections where needed.
64
65 % VZ: bad idea IMHO - we're going to have a lot of problems with this
66 Furthermore, it may be noted that some ports of wxWindows will probably move
67 to using this method more and more in preference over calling ProcessEvent()
68 directly so as to avoid problems with reentrant code.
69
70 \membersection{wxEvtHandler::Connect}\label{wxevthandlerconnect}
71
72 \func{void}{Connect}{\param{int}{ id},
73 \param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function},
74 \param{wxObject*}{ userData = NULL}}
75
76 \func{void}{Connect}{\param{int}{ id}, \param{int}{ lastId},
77 \param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function},
78 \param{wxObject*}{ userData = NULL}}
79
80 Connects the given function dynamically with the event handler, id and event type. This
81 is an alternative to the use of static event tables. See the 'dynamic' sample for usage.
82
83 \wxheading{Parameters}
84
85 \docparam{id}{The identifier (or first of the identifier range) to be associated with the event handler function.}
86
87 \docparam{lastId}{The second part of the identifier range to be associated with the event handler function.}
88
89 \docparam{eventType}{The event type to be associated with this event handler.}
90
91 \docparam{function}{The event handler function.}
92
93 \docparam{userData}{Data to be associated with the event table entry.}
94
95 \wxheading{Example}
96
97 \begin{verbatim}
98 frame->Connect( wxID_EXIT,
99 wxEVT_COMMAND_MENU_SELECTED,
100 (wxObjectEventFunction) (wxEventFunction) (wxCommandEventFunction) MyFrame::OnQuit );
101 \end{verbatim}
102
103 \membersection{wxEvtHandler::Disconnect}\label{wxevthandlerdisconnect}
104
105 \func{bool}{Disconnect}{\param{int}{ id},
106 \param{wxEventType }{eventType = wxEVT\_NULL}, \param{wxObjectEventFunction}{ function = NULL},
107 \param{wxObject*}{ userData = NULL}}
108
109 \func{bool}{Disconnect}{\param{int}{ id}, \param{int}{ lastId = -1},
110 \param{wxEventType }{eventType = wxEVT\_NULL}, \param{wxObjectEventFunction}{ function = NULL},
111 \param{wxObject*}{ userData = NULL}}
112
113 Disconnects the given function dynamically from the event handler, using the specified
114 parameters as search criteria and returning TRUE if a matching function has been
115 found and removed. This method can only disconnect functions which have been added
116 using the \helpref{wxEvtHandler::Connect}{wxevthandlerconnect} method. There is no way
117 to disconnect functions connected using the (static) event tables.
118
119 \wxheading{Parameters}
120
121 \docparam{id}{The identifier (or first of the identifier range) associated with the event handler function.}
122
123 \docparam{lastId}{The second part of the identifier range associated with the event handler function.}
124
125 \docparam{eventType}{The event type associated with this event handler.}
126
127 \docparam{function}{The event handler function.}
128
129 \docparam{userData}{Data associated with the event table entry.}
130
131 \membersection{wxEvtHandler::GetClientData}\label{wxevthandlergetclientdata}
132
133 \func{void* }{GetClientData}{\void}
134
135 Gets user-supplied client data.
136
137 \wxheading{Remarks}
138
139 Normally, any extra data the programmer wishes to associate with the object
140 should be made available by deriving a new class with new data members.
141
142 \wxheading{See also}
143
144 \helpref{wxEvtHandler::SetClientData}{wxevthandlersetclientdata}
145
146 \membersection{wxEvtHandler::GetEvtHandlerEnabled}\label{wxevthandlergetevthandlerenabled}
147
148 \func{bool}{GetEvtHandlerEnabled}{\void}
149
150 Returns TRUE if the event handler is enabled, FALSE otherwise.
151
152 \wxheading{See also}
153
154 \helpref{wxEvtHandler::SetEvtHandlerEnabled}{wxevthandlersetevthandlerenabled}
155
156 \membersection{wxEvtHandler::GetNextHandler}\label{wxevthandlergetnexthandler}
157
158 \func{wxEvtHandler*}{GetNextHandler}{\void}
159
160 Gets the pointer to the next handler in the chain.
161
162 \wxheading{See also}
163
164 \helpref{wxEvtHandler::SetNextHandler}{wxevthandlersetnexthandler},\rtfsp
165 \helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp
166 \helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp
167 \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
168 \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler}
169
170 \membersection{wxEvtHandler::GetPreviousHandler}\label{wxevthandlergetprevioushandler}
171
172 \func{wxEvtHandler*}{GetPreviousHandler}{\void}
173
174 Gets the pointer to the previous handler in the chain.
175
176 \wxheading{See also}
177
178 \helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp
179 \helpref{wxEvtHandler::GetNextHandler}{wxevthandlergetnexthandler},\rtfsp
180 \helpref{wxEvtHandler::SetNextHandler}{wxevthandlersetnexthandler},\rtfsp
181 \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
182 \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler}
183
184 \membersection{wxEvtHandler::ProcessEvent}\label{wxevthandlerprocessevent}
185
186 \func{virtual bool}{ProcessEvent}{\param{wxEvent\& }{event}}
187
188 Processes an event, searching event tables and calling zero or more suitable event handler function(s).
189
190 \wxheading{Parameters}
191
192 \docparam{event}{Event to process.}
193
194 \wxheading{Return value}
195
196 TRUE if a suitable event handler function was found and executed, and the function did not
197 call \helpref{wxEvent::Skip}{wxeventskip}.
198
199 \wxheading{Remarks}
200
201 Normally, your application would not call this function: it is called in the wxWindows
202 implementation to dispatch incoming user interface events to the framework (and application).
203
204 However, you might need to call it if implementing new functionality (such as a new control) where
205 you define new event types, as opposed to allowing the user to override virtual functions.
206
207 An instance where you might actually override the {\bf ProcessEvent} function is where you want
208 to direct event processing to event handlers not normally noticed by wxWindows. For example,
209 in the document/view architecture, documents and views are potential event handlers.
210 When an event reaches a frame, {\bf ProcessEvent} will need to be called on the associated
211 document and view in case event handler functions are associated with these objects.
212 The property classes library (wxProperty) also overrides {\bf ProcessEvent} for similar reasons.
213
214 The normal order of event table searching is as follows:
215
216 \begin{enumerate}\itemsep=0pt
217 \item If the object is disabled (via a call to \helpref{wxEvtHandler::SetEvtHandlerEnabled}{wxevthandlersetevthandlerenabled})
218 the function skips to step (6).
219 \item If the object is a wxWindow, {\bf ProcessEvent} is recursively called on the window's\rtfsp
220 \helpref{wxValidator}{wxvalidator}. If this returns TRUE, the function exits.
221 \item {\bf SearchEventTable} is called for this event handler. If this fails, the base
222 class table is tried, and so on until no more tables exist or an appropriate function was found,
223 in which case the function exits.
224 \item The search is applied down the entire chain of event handlers (usually the chain has a length
225 of one). If this succeeds, the function exits.
226 \item If the object is a wxWindow and the event is a wxCommandEvent, {\bf ProcessEvent} is
227 recursively applied to the parent window's event handler. If this returns TRUE, the function exits.
228 \item Finally, {\bf ProcessEvent} is called on the wxApp object.
229 \end{enumerate}
230
231 \wxheading{See also}
232
233 \helpref{wxEvtHandler::SearchEventTable}{wxevthandlersearcheventtable}
234
235 \membersection{wxEvtHandler::SearchEventTable}\label{wxevthandlersearcheventtable}
236
237 \func{bool}{SearchEventTable}{\param{wxEventTable\& }{table}, \param{wxEvent\& }{event}}
238
239 Searches the event table, executing an event handler function if an appropriate one
240 is found.
241
242 \wxheading{Parameters}
243
244 \docparam{table}{Event table to be searched.}
245
246 \docparam{event}{Event to be matched against an event table entry.}
247
248 \wxheading{Return value}
249
250 TRUE if a suitable event handler function was found and executed, and the function did not
251 call \helpref{wxEvent::Skip}{wxeventskip}.
252
253 \wxheading{Remarks}
254
255 This function looks through the object's event table and tries to find an entry
256 that will match the event.
257
258 An entry will match if:
259
260 \begin{enumerate}\itemsep=0pt
261 \item The event type matches, and
262 \item the identifier or identifier range matches, or the event table entry's identifier is zero.
263 \end{enumerate}
264
265 If a suitable function is called but calls \helpref{wxEvent::Skip}{wxeventskip}, this function will
266 fail, and searching will continue.
267
268 \wxheading{See also}
269
270 \helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent}
271
272 \membersection{wxEvtHandler::SetClientData}\label{wxevthandlersetclientdata}
273
274 \func{void}{SetClientData}{\param{void* }{data}}
275
276 Sets user-supplied client data.
277
278 \wxheading{Parameters}
279
280 \docparam{data}{Data to be associated with the event handler.}
281
282 \wxheading{Remarks}
283
284 Normally, any extra data the programmer wishes to associate with
285 the object should be made available by deriving a new class
286 with new data members.
287
288 \wxheading{See also}
289
290 \helpref{wxEvtHandler::GetClientData}{wxevthandlergetclientdata}
291
292 \membersection{wxEvtHandler::SetEvtHandlerEnabled}\label{wxevthandlersetevthandlerenabled}
293
294 \func{void}{SetEvtHandlerEnabled}{\param{bool }{enabled}}
295
296 Enables or disables the event handler.
297
298 \wxheading{Parameters}
299
300 \docparam{enabled}{TRUE if the event handler is to be enabled, FALSE if it is to be disabled.}
301
302 \wxheading{Remarks}
303
304 You can use this function to avoid having to remove the event handler from the chain, for example
305 when implementing a dialog editor and changing from edit to test mode.
306
307 \wxheading{See also}
308
309 \helpref{wxEvtHandler::GetEvtHandlerEnabled}{wxevthandlergetevthandlerenabled}
310
311 \membersection{wxEvtHandler::SetNextHandler}\label{wxevthandlersetnexthandler}
312
313 \func{void}{SetNextHandler}{\param{wxEvtHandler* }{handler}}
314
315 Sets the pointer to the next handler.
316
317 \wxheading{Parameters}
318
319 \docparam{handler}{Event handler to be set as the next handler.}
320
321 \wxheading{See also}
322
323 \helpref{wxEvtHandler::GetNextHandler}{wxevthandlergetnexthandler},\rtfsp
324 \helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp
325 \helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp
326 \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
327 \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler}
328
329 \membersection{wxEvtHandler::SetPreviousHandler}\label{wxevthandlersetprevioushandler}
330
331 \func{void}{SetPreviousHandler}{\param{wxEvtHandler* }{handler}}
332
333 Sets the pointer to the previous handler.
334
335 \wxheading{Parameters}
336
337 \docparam{handler}{Event handler to be set as the previous handler.}
338
339 \wxheading{See also}
340
341 \helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp
342 \helpref{wxEvtHandler::SetNextHandler}{wxevthandlersetnexthandler},\rtfsp
343 \helpref{wxEvtHandler::GetNextHandler}{wxevthandlergetnexthandler},\rtfsp
344 \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp
345 \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler}
346
347