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