]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/evthand.tex
Fixed to work with the new wxMacControl system.
[wxWidgets.git] / docs / latex / wx / evthand.tex
... / ...
CommitLineData
1\section{\class{wxEvtHandler}}\label{wxevthandler}
2
3A class that can handle events from the windowing system.
4wxWindow (and therefore all window classes) are derived from
5this class.
6
7When events are received, wxEvtHandler invokes the method listed in the
8event table using itself as the object. When using multiple inheritance
9it is imperative that the wxEvtHandler(-derived) class be the first
10class inherited such that the "this" pointer for the overall object
11will 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
31Constructor.
32
33\membersection{wxEvtHandler::\destruct{wxEvtHandler}}
34
35\func{}{\destruct{wxEvtHandler}}{\void}
36
37Destructor. If the handler is part of a chain, the destructor will
38unlink itself and restore the previous and next handlers so that they point to
39each other.
40
41\membersection{wxEvtHandler::AddPendingEvent}\label{wxevthandleraddpendingevent}
42
43\func{void}{AddPendingEvent}{\param{wxEvent\& }{event}}
44
45This 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
53The difference between sending an event (using the
54\helpref{ProcessEvent}{wxevthandlerprocessevent} method) and posting it is
55that in the first case the event is processed before the function returns,
56while in the second case, the function returns immediately and the event will
57be processed sometime later (usually during the next event loop iteration).
58
59A copy of {\it event} is made by the function, so the original can be deleted
60as soon as function returns (it is common that the original is created on the
61stack). This requires that the \helpref{wxEvent::Clone}{wxeventclone} method
62be implemented by {\it event} so that it can be duplicated and stored until
63it gets processed.
64
65This is also the method to call for inter-thread communication---it will
66post events safely between different threads which means that this method is
67thread-safe by using critical sections where needed. In a multi-threaded
68program, you often need to inform the main GUI thread about the status of
69other working threads and such notification should be done using this method.
70
71This method automatically wakes up idle handling if the underlying window
72system is currently idle and thus would not send any idle events. (Waking
73up 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
85Connects the given function dynamically with the event handler, id and event type. This
86is 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,
112lastid, type, method}; if \texttt{method} is \texttt{undef}, the
113handler 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
125Disconnects the given function dynamically from the event handler, using the specified
126parameters as search criteria and returning true if a matching function has been
127found and removed. This method can only disconnect functions which have been added
128using the \helpref{wxEvtHandler::Connect}{wxevthandlerconnect} method. There is no way
129to 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,
146lastid, type}.}
147
148\membersection{wxEvtHandler::GetClientData}\label{wxevthandlergetclientdata}
149
150\func{void* }{GetClientData}{\void}
151
152Gets user-supplied client data.
153
154\wxheading{Remarks}
155
156Normally, any extra data the programmer wishes to associate with the object
157should 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
167Get 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
178Returns 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
188Gets 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
202Gets 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
216Processes 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
224true if a suitable event handler function was found and executed, and the function did not
225call \helpref{wxEvent::Skip}{wxeventskip}.
226
227\wxheading{Remarks}
228
229Normally, your application would not call this function: it is called in the wxWidgets
230implementation to dispatch incoming user interface events to the framework (and application).
231
232However, you might need to call it if implementing new functionality (such as a new control) where
233you define new event types, as opposed to allowing the user to override virtual functions.
234
235An instance where you might actually override the {\bf ProcessEvent} function is where you want
236to direct event processing to event handlers not normally noticed by wxWidgets. For example,
237in the document/view architecture, documents and views are potential event handlers.
238When an event reaches a frame, {\bf ProcessEvent} will need to be called on the associated
239document and view in case event handler functions are associated with these objects.
240The property classes library (wxProperty) also overrides {\bf ProcessEvent} for similar reasons.
241
242The 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})
246the 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
250class table is tried, and so on until no more tables exist or an appropriate function was found,
251in which case the function exits.
252\item The search is applied down the entire chain of event handlers (usually the chain has a length
253of one). If this succeeds, the function exits.
254\item If the object is a wxWindow and the event is a wxCommandEvent, {\bf ProcessEvent} is
255recursively 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
267Searches the event table, executing an event handler function if an appropriate one
268is 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
278true if a suitable event handler function was found and executed, and the function did not
279call \helpref{wxEvent::Skip}{wxeventskip}.
280
281\wxheading{Remarks}
282
283This function looks through the object's event table and tries to find an entry
284that will match the event.
285
286An 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
293If a suitable function is called but calls \helpref{wxEvent::Skip}{wxeventskip}, this function will
294fail, 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
304Sets 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
312Normally, any extra data the programmer wishes to associate with
313the object should be made available by deriving a new class
314with new data members. You must not call this method and
315\helpref{SetClientObject}{wxevthandlersetclientobject} on the
316same 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
326Set 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
337Enables 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
345You can use this function to avoid having to remove the event handler from the chain, for example
346when 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
356Sets 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
374Sets 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