]>
Commit | Line | Data |
---|---|---|
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 | When events are received, wxEvtHandler invokes the method listed in the | |
8 | event table using itself as the object. When using multiple inheritance | |
9 | it is imperative that the wxEvtHandler(-derived) class be the first | |
10 | class inherited such that the "this" pointer for the overall object | |
11 | will be identical to the "this" pointer for the wxEvtHandler portion. | |
12 | ||
13 | \wxheading{Derived from} | |
14 | ||
15 | \helpref{wxObject}{wxobject} | |
16 | ||
17 | \wxheading{Include files} | |
18 | ||
19 | <wx/event.h> | |
20 | ||
21 | \wxheading{See also} | |
22 | ||
23 | \overview{Event handling overview}{eventhandlingoverview} | |
24 | ||
25 | \latexignore{\rtfignore{\wxheading{Members}}} | |
26 | ||
27 | \membersection{wxEvtHandler::wxEvtHandler} | |
28 | ||
29 | \func{}{wxEvtHandler}{\void} | |
30 | ||
31 | Constructor. | |
32 | ||
33 | \membersection{wxEvtHandler::\destruct{wxEvtHandler}} | |
34 | ||
35 | \func{}{\destruct{wxEvtHandler}}{\void} | |
36 | ||
37 | Destructor. If the handler is part of a chain, the destructor will | |
38 | unlink itself and restore the previous and next handlers so that they point to | |
39 | each other. | |
40 | ||
41 | \membersection{wxEvtHandler::AddPendingEvent}\label{wxevthandleraddpendingevent} | |
42 | ||
43 | \func{void}{AddPendingEvent}{\param{wxEvent\& }{event}} | |
44 | ||
45 | This function posts an event to be processed later. | |
46 | ||
47 | \wxheading{Parameters} | |
48 | ||
49 | \docparam{event}{Event to add to process queue.} | |
50 | ||
51 | \wxheading{Remarks} | |
52 | ||
53 | The difference between sending an event (using the | |
54 | \helpref{ProcessEvent}{wxevthandlerprocessevent} method) and posting it is | |
55 | that in the first case the event is processed before the function returns, | |
56 | while in the second case, the function returns immediately and the event will | |
57 | be processed sometime later (usually during the next event loop iteration). | |
58 | ||
59 | A copy of {\it event} is made by the function, so the original can be deleted | |
60 | as soon as function returns (it is common that the original is created on the | |
61 | stack). This requires that the \helpref{wxEvent::Clone}{wxeventclone} method | |
62 | be implemented by {\it event} so that it can be duplicated and stored until | |
63 | it gets processed. | |
64 | ||
65 | This is also the method to call for inter-thread communication---it will | |
66 | post events safely between different threads which means that this method is | |
67 | thread-safe by using critical sections where needed. In a multi-threaded | |
68 | program, you often need to inform the main GUI thread about the status of | |
69 | other working threads and such notification should be done using this method. | |
70 | ||
71 | This method automatically wakes up idle handling if the underlying window | |
72 | system is currently idle and thus would not send any idle events. (Waking | |
73 | up idle handling is done calling \helpref{::wxWakeUpIdle}{wxwakeupidle}.) | |
74 | ||
75 | \membersection{wxEvtHandler::Connect}\label{wxevthandlerconnect} | |
76 | ||
77 | \func{void}{Connect}{\param{int}{ id}, | |
78 | \param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function}, | |
79 | \param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}} | |
80 | ||
81 | \func{void}{Connect}{\param{int}{ id}, \param{int}{ lastId}, | |
82 | \param{wxEventType }{eventType}, \param{wxObjectEventFunction}{ function}, | |
83 | \param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}} | |
84 | ||
85 | Connects the given function dynamically with the event handler, id and event type. This | |
86 | is an alternative to the use of static event tables. See the 'dynamic' sample for usage. | |
87 | ||
88 | \wxheading{Parameters} | |
89 | ||
90 | \docparam{id}{The identifier (or first of the identifier range) to be associated with the event handler function.} | |
91 | ||
92 | \docparam{lastId}{The second part of the identifier range to be associated with the event handler function.} | |
93 | ||
94 | \docparam{eventType}{The event type to be associated with this event handler.} | |
95 | ||
96 | \docparam{function}{The event handler function.} | |
97 | ||
98 | \docparam{userData}{Data to be associated with the event table entry.} | |
99 | ||
100 | \docparam{eventSink}{Object whose member function should be called. If this is NULL, | |
101 | 'this' will be used.} | |
102 | ||
103 | \wxheading{Example} | |
104 | ||
105 | \begin{verbatim} | |
106 | frame->Connect( wxID_EXIT, | |
107 | wxEVT_COMMAND_MENU_SELECTED, | |
108 | (wxObjectEventFunction) (wxEventFunction) (wxCommandEventFunction) MyFrame::OnQuit ); | |
109 | \end{verbatim} | |
110 | ||
111 | \perlnote{In wxPerl this function takes 4 arguments: \texttt{id, | |
112 | lastid, type, method}; if \texttt{method} is \texttt{undef}, the | |
113 | handler is disconnected.} | |
114 | ||
115 | \membersection{wxEvtHandler::Disconnect}\label{wxevthandlerdisconnect} | |
116 | ||
117 | \func{bool}{Disconnect}{\param{int}{ id}, | |
118 | \param{wxEventType }{eventType = wxEVT\_NULL}, \param{wxObjectEventFunction}{ function = NULL}, | |
119 | \param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}} | |
120 | ||
121 | \func{bool}{Disconnect}{\param{int}{ id}, \param{int}{ lastId = -1}, | |
122 | \param{wxEventType }{eventType = wxEVT\_NULL}, \param{wxObjectEventFunction}{ function = NULL}, | |
123 | \param{wxObject*}{ userData = NULL}, \param{wxEvtHandler*}{ eventSink = NULL}} | |
124 | ||
125 | Disconnects the given function dynamically from the event handler, using the specified | |
126 | parameters as search criteria and returning true if a matching function has been | |
127 | found and removed. This method can only disconnect functions which have been added | |
128 | using the \helpref{wxEvtHandler::Connect}{wxevthandlerconnect} method. There is no way | |
129 | to disconnect functions connected using the (static) event tables. | |
130 | ||
131 | \wxheading{Parameters} | |
132 | ||
133 | \docparam{id}{The identifier (or first of the identifier range) associated with the event handler function.} | |
134 | ||
135 | \docparam{lastId}{The second part of the identifier range associated with the event handler function.} | |
136 | ||
137 | \docparam{eventType}{The event type associated with this event handler.} | |
138 | ||
139 | \docparam{function}{The event handler function.} | |
140 | ||
141 | \docparam{userData}{Data associated with the event table entry.} | |
142 | ||
143 | \docparam{eventSink}{Object whose member function should be called.} | |
144 | ||
145 | \perlnote{In wxPerl this function takes 3 arguments: \texttt{id, | |
146 | lastid, type}.} | |
147 | ||
148 | \membersection{wxEvtHandler::GetClientData}\label{wxevthandlergetclientdata} | |
149 | ||
150 | \func{void* }{GetClientData}{\void} | |
151 | ||
152 | Gets user-supplied client data. | |
153 | ||
154 | \wxheading{Remarks} | |
155 | ||
156 | Normally, any extra data the programmer wishes to associate with the object | |
157 | should be made available by deriving a new class with new data members. | |
158 | ||
159 | \wxheading{See also} | |
160 | ||
161 | \helpref{wxEvtHandler::SetClientData}{wxevthandlersetclientdata} | |
162 | ||
163 | \membersection{wxEvtHandler::GetClientObject}\label{wxevthandlergetclientobject} | |
164 | ||
165 | \constfunc{wxClientData*}{GetClientObject}{\void} | |
166 | ||
167 | Get a pointer to the user-supplied client data object. | |
168 | ||
169 | \wxheading{See also} | |
170 | ||
171 | \helpref{wxEvtHandler::SetClientObject}{wxevthandlersetclientobject}, | |
172 | \helpref{wxClientData}{wxclientdata} | |
173 | ||
174 | \membersection{wxEvtHandler::GetEvtHandlerEnabled}\label{wxevthandlergetevthandlerenabled} | |
175 | ||
176 | \func{bool}{GetEvtHandlerEnabled}{\void} | |
177 | ||
178 | Returns true if the event handler is enabled, false otherwise. | |
179 | ||
180 | \wxheading{See also} | |
181 | ||
182 | \helpref{wxEvtHandler::SetEvtHandlerEnabled}{wxevthandlersetevthandlerenabled} | |
183 | ||
184 | \membersection{wxEvtHandler::GetNextHandler}\label{wxevthandlergetnexthandler} | |
185 | ||
186 | \func{wxEvtHandler*}{GetNextHandler}{\void} | |
187 | ||
188 | Gets the pointer to the next handler in the chain. | |
189 | ||
190 | \wxheading{See also} | |
191 | ||
192 | \helpref{wxEvtHandler::SetNextHandler}{wxevthandlersetnexthandler},\rtfsp | |
193 | \helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp | |
194 | \helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp | |
195 | \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp | |
196 | \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler} | |
197 | ||
198 | \membersection{wxEvtHandler::GetPreviousHandler}\label{wxevthandlergetprevioushandler} | |
199 | ||
200 | \func{wxEvtHandler*}{GetPreviousHandler}{\void} | |
201 | ||
202 | Gets the pointer to the previous handler in the chain. | |
203 | ||
204 | \wxheading{See also} | |
205 | ||
206 | \helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp | |
207 | \helpref{wxEvtHandler::GetNextHandler}{wxevthandlergetnexthandler},\rtfsp | |
208 | \helpref{wxEvtHandler::SetNextHandler}{wxevthandlersetnexthandler},\rtfsp | |
209 | \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp | |
210 | \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler} | |
211 | ||
212 | \membersection{wxEvtHandler::ProcessEvent}\label{wxevthandlerprocessevent} | |
213 | ||
214 | \func{virtual bool}{ProcessEvent}{\param{wxEvent\& }{event}} | |
215 | ||
216 | Processes an event, searching event tables and calling zero or more suitable event handler function(s). | |
217 | ||
218 | \wxheading{Parameters} | |
219 | ||
220 | \docparam{event}{Event to process.} | |
221 | ||
222 | \wxheading{Return value} | |
223 | ||
224 | true if a suitable event handler function was found and executed, and the function did not | |
225 | call \helpref{wxEvent::Skip}{wxeventskip}. | |
226 | ||
227 | \wxheading{Remarks} | |
228 | ||
229 | Normally, your application would not call this function: it is called in the wxWidgets | |
230 | implementation to dispatch incoming user interface events to the framework (and application). | |
231 | ||
232 | However, you might need to call it if implementing new functionality (such as a new control) where | |
233 | you define new event types, as opposed to allowing the user to override virtual functions. | |
234 | ||
235 | An instance where you might actually override the {\bf ProcessEvent} function is where you want | |
236 | to direct event processing to event handlers not normally noticed by wxWidgets. For example, | |
237 | in the document/view architecture, documents and views are potential event handlers. | |
238 | When an event reaches a frame, {\bf ProcessEvent} will need to be called on the associated | |
239 | document and view in case event handler functions are associated with these objects. | |
240 | The property classes library (wxProperty) also overrides {\bf ProcessEvent} for similar reasons. | |
241 | ||
242 | The normal order of event table searching is as follows: | |
243 | ||
244 | \begin{enumerate}\itemsep=0pt | |
245 | \item If the object is disabled (via a call to \helpref{wxEvtHandler::SetEvtHandlerEnabled}{wxevthandlersetevthandlerenabled}) | |
246 | the function skips to step (6). | |
247 | \item If the object is a wxWindow, {\bf ProcessEvent} is recursively called on the window's\rtfsp | |
248 | \helpref{wxValidator}{wxvalidator}. If this returns true, the function exits. | |
249 | \item {\bf SearchEventTable} is called for this event handler. If this fails, the base | |
250 | class table is tried, and so on until no more tables exist or an appropriate function was found, | |
251 | in which case the function exits. | |
252 | \item The search is applied down the entire chain of event handlers (usually the chain has a length | |
253 | of one). If this succeeds, the function exits. | |
254 | \item If the object is a wxWindow and the event is a wxCommandEvent, {\bf ProcessEvent} is | |
255 | recursively applied to the parent window's event handler. If this returns true, the function exits. | |
256 | \item Finally, {\bf ProcessEvent} is called on the wxApp object. | |
257 | \end{enumerate} | |
258 | ||
259 | \wxheading{See also} | |
260 | ||
261 | \helpref{wxEvtHandler::SearchEventTable}{wxevthandlersearcheventtable} | |
262 | ||
263 | \membersection{wxEvtHandler::SearchEventTable}\label{wxevthandlersearcheventtable} | |
264 | ||
265 | \func{bool}{SearchEventTable}{\param{wxEventTable\& }{table}, \param{wxEvent\& }{event}} | |
266 | ||
267 | Searches the event table, executing an event handler function if an appropriate one | |
268 | is found. | |
269 | ||
270 | \wxheading{Parameters} | |
271 | ||
272 | \docparam{table}{Event table to be searched.} | |
273 | ||
274 | \docparam{event}{Event to be matched against an event table entry.} | |
275 | ||
276 | \wxheading{Return value} | |
277 | ||
278 | true if a suitable event handler function was found and executed, and the function did not | |
279 | call \helpref{wxEvent::Skip}{wxeventskip}. | |
280 | ||
281 | \wxheading{Remarks} | |
282 | ||
283 | This function looks through the object's event table and tries to find an entry | |
284 | that will match the event. | |
285 | ||
286 | An entry will match if: | |
287 | ||
288 | \begin{enumerate}\itemsep=0pt | |
289 | \item The event type matches, and | |
290 | \item the identifier or identifier range matches, or the event table entry's identifier is zero. | |
291 | \end{enumerate} | |
292 | ||
293 | If a suitable function is called but calls \helpref{wxEvent::Skip}{wxeventskip}, this function will | |
294 | fail, and searching will continue. | |
295 | ||
296 | \wxheading{See also} | |
297 | ||
298 | \helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent} | |
299 | ||
300 | \membersection{wxEvtHandler::SetClientData}\label{wxevthandlersetclientdata} | |
301 | ||
302 | \func{void}{SetClientData}{\param{void* }{data}} | |
303 | ||
304 | Sets user-supplied client data. | |
305 | ||
306 | \wxheading{Parameters} | |
307 | ||
308 | \docparam{data}{Data to be associated with the event handler.} | |
309 | ||
310 | \wxheading{Remarks} | |
311 | ||
312 | Normally, any extra data the programmer wishes to associate with | |
313 | the object should be made available by deriving a new class | |
314 | with new data members. You must not call this method and | |
315 | \helpref{SetClientObject}{wxevthandlersetclientobject} on the | |
316 | same class - only one of them. | |
317 | ||
318 | \wxheading{See also} | |
319 | ||
320 | \helpref{wxEvtHandler::GetClientData}{wxevthandlergetclientdata} | |
321 | ||
322 | \membersection{wxEvtHandler::SetClientObject}\label{wxevthandlersetclientobject} | |
323 | ||
324 | \func{void}{SetClientObject}{\param{wxClientData* }{data}} | |
325 | ||
326 | Set the client data object. Any previous object will be deleted. | |
327 | ||
328 | \wxheading{See also} | |
329 | ||
330 | \helpref{wxEvtHandler::GetClientObject}{wxevthandlergetclientobject}, | |
331 | \helpref{wxClientData}{wxclientdata} | |
332 | ||
333 | \membersection{wxEvtHandler::SetEvtHandlerEnabled}\label{wxevthandlersetevthandlerenabled} | |
334 | ||
335 | \func{void}{SetEvtHandlerEnabled}{\param{bool }{enabled}} | |
336 | ||
337 | Enables or disables the event handler. | |
338 | ||
339 | \wxheading{Parameters} | |
340 | ||
341 | \docparam{enabled}{true if the event handler is to be enabled, false if it is to be disabled.} | |
342 | ||
343 | \wxheading{Remarks} | |
344 | ||
345 | You can use this function to avoid having to remove the event handler from the chain, for example | |
346 | when implementing a dialog editor and changing from edit to test mode. | |
347 | ||
348 | \wxheading{See also} | |
349 | ||
350 | \helpref{wxEvtHandler::GetEvtHandlerEnabled}{wxevthandlergetevthandlerenabled} | |
351 | ||
352 | \membersection{wxEvtHandler::SetNextHandler}\label{wxevthandlersetnexthandler} | |
353 | ||
354 | \func{void}{SetNextHandler}{\param{wxEvtHandler* }{handler}} | |
355 | ||
356 | Sets the pointer to the next handler. | |
357 | ||
358 | \wxheading{Parameters} | |
359 | ||
360 | \docparam{handler}{Event handler to be set as the next handler.} | |
361 | ||
362 | \wxheading{See also} | |
363 | ||
364 | \helpref{wxEvtHandler::GetNextHandler}{wxevthandlergetnexthandler},\rtfsp | |
365 | \helpref{wxEvtHandler::SetPreviousHandler}{wxevthandlersetprevioushandler},\rtfsp | |
366 | \helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp | |
367 | \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp | |
368 | \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler} | |
369 | ||
370 | \membersection{wxEvtHandler::SetPreviousHandler}\label{wxevthandlersetprevioushandler} | |
371 | ||
372 | \func{void}{SetPreviousHandler}{\param{wxEvtHandler* }{handler}} | |
373 | ||
374 | Sets the pointer to the previous handler. | |
375 | ||
376 | \wxheading{Parameters} | |
377 | ||
378 | \docparam{handler}{Event handler to be set as the previous handler.} | |
379 | ||
380 | \wxheading{See also} | |
381 | ||
382 | \helpref{wxEvtHandler::GetPreviousHandler}{wxevthandlergetprevioushandler},\rtfsp | |
383 | \helpref{wxEvtHandler::SetNextHandler}{wxevthandlersetnexthandler},\rtfsp | |
384 | \helpref{wxEvtHandler::GetNextHandler}{wxevthandlergetnexthandler},\rtfsp | |
385 | \helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler},\rtfsp | |
386 | \helpref{wxWindow::PopEventHandler}{wxwindowpopeventhandler} | |
387 | ||
388 |