]>
Commit | Line | Data |
---|---|---|
a660d684 KB |
1 | \section{Event handling overview}\label{eventhandlingoverview} |
2 | ||
3 | Classes: \helpref{wxEvtHandler}{wxevthandler}, \helpref{wxWindow}{wxwindow}, \helpref{wxEvent}{wxevent} | |
4 | ||
a203f6c0 | 5 | \subsection{Introduction}\label{eventintroduction} |
a660d684 | 6 | |
fc2171bd | 7 | Before version 2.0 of wxWidgets, events were handled by the application |
a660d684 KB |
8 | either by supplying callback functions, or by overriding virtual member |
9 | functions such as {\bf OnSize}. | |
10 | ||
fc2171bd | 11 | From wxWidgets 2.0, {\it event tables} are used instead, with a few exceptions. |
a660d684 | 12 | |
fc2171bd | 13 | An event table is placed in an implementation file to tell wxWidgets how to map |
a660d684 | 14 | events to member functions. These member functions are not virtual functions, but |
42bcb12b | 15 | they are all similar in form: they take a single wxEvent-derived argument, and have a void return |
a660d684 KB |
16 | type. |
17 | ||
18 | Here's an example of an event table. | |
19 | ||
20 | \begin{verbatim} | |
21 | BEGIN_EVENT_TABLE(MyFrame, wxFrame) | |
22 | EVT_MENU (wxID_EXIT, MyFrame::OnExit) | |
23 | EVT_MENU (DO_TEST, MyFrame::DoTest) | |
24 | EVT_SIZE ( MyFrame::OnSize) | |
25 | EVT_BUTTON (BUTTON1, MyFrame::OnButton1) | |
26 | END_EVENT_TABLE() | |
27 | \end{verbatim} | |
28 | ||
2862acde VZ |
29 | The first two entries map menu commands to two different member functions. The |
30 | EVT\_SIZE macro doesn't need a window identifier, since normally you are only | |
31 | interested in the current window's size events. | |
32 | ||
33 | The EVT\_BUTTON macro demonstrates that the originating event does not have to | |
34 | come from the window class implementing the event table -- if the event source | |
35 | is a button within a panel within a frame, this will still work, because event | |
36 | tables are searched up through the hierarchy of windows for the command events. | |
37 | In this case, the button's event table will be searched, then the parent | |
38 | panel's, then the frame's. | |
39 | ||
40 | As mentioned before, the member functions that handle events do not have to be | |
41 | virtual. Indeed, the member functions should not be virtual as the event | |
42 | handler ignores that the functions are virtual, i.e. overriding a virtual | |
43 | member function in a derived class will not have any effect. These member | |
44 | functions take an event argument, and the class of event differs according to | |
45 | the type of event and the class of the originating window. For size events, | |
46 | \helpref{wxSizeEvent}{wxsizeevent} is used. For menu commands and most | |
47 | control commands (such as button presses), | |
48 | \helpref{wxCommandEvent}{wxcommandevent} is used. When controls get more | |
49 | complicated, then specific event classes are used, such as | |
50 | \helpref{wxTreeEvent}{wxtreeevent} for events from | |
51 | \helpref{wxTreeCtrl}{wxtreectrl} windows. | |
52 | ||
53 | As well as the event table in the implementation file, there must also be a | |
54 | DECLARE\_EVENT\_TABLE macro somewhere in the class declaration. For example: | |
a660d684 KB |
55 | |
56 | {\small% | |
57 | \begin{verbatim} | |
2862acde VZ |
58 | class MyFrame : public wxFrame |
59 | { | |
a660d684 KB |
60 | public: |
61 | ... | |
62 | void OnExit(wxCommandEvent& event); | |
63 | void OnSize(wxSizeEvent& event); | |
2862acde | 64 | |
a660d684 KB |
65 | protected: |
66 | int m_count; | |
67 | ... | |
2862acde | 68 | |
a660d684 KB |
69 | DECLARE_EVENT_TABLE() |
70 | }; | |
71 | \end{verbatim} | |
72 | }% | |
73 | ||
2862acde VZ |
74 | Note that this macro may occur in any section of the class (public, protected |
75 | or private) but that it is probably better to insert it at the end, as shown, | |
76 | because this macro implicitly changes the access to protected which may be | |
77 | quite unexpected if there is anything following it. | |
78 | ||
79 | Finally, if you don't like using macros for static initialization of the event | |
80 | tables you may also use \helpref{wxEvtHandler::Connect}{wxevthandlerconnect} to | |
81 | connect the events to the handlers dynamically, during run-time. See the | |
82 | \helpref{event sample}{sampleevent} for an example of doing it. | |
83 | ||
84 | ||
a660d684 KB |
85 | \subsection{How events are processed}\label{eventprocessing} |
86 | ||
fc2171bd | 87 | When an event is received from the windowing system, wxWidgets calls |
e4b713a2 VZ |
88 | \helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent} on the first |
89 | event handler object belonging to the window generating the event. | |
a660d684 | 90 | |
fc2171bd | 91 | It may be noted that wxWidgets' event processing system implements something |
5fc02438 RR |
92 | very close to virtual methods in normal C++, i.e. it is possible to alter |
93 | the behaviour of a class by overriding its event handling functions. In | |
94 | many cases this works even for changing the behaviour of native controls. | |
1f112209 | 95 | For example it is possible to filter out a number of key events sent by the |
5fc02438 | 96 | system to a native text control by overriding wxTextCtrl and defining a |
1f112209 | 97 | handler for key events using EVT\_KEY\_DOWN. This would indeed prevent |
5fc02438 RR |
98 | any key events from being sent to the native control - which might not be |
99 | what is desired. In this case the event handler function has to call Skip() | |
d6d62686 VZ |
100 | so as to indicate that the search for the event handler should continue. |
101 | ||
102 | To summarize, instead of explicitly calling the base class version as you | |
103 | would have done with C++ virtual functions (i.e. {\it wxTextCtrl::OnChar()}), | |
104 | you should instead call \helpref{Skip}{wxeventskip}. | |
5fc02438 RR |
105 | |
106 | In practice, this would look like this if the derived text control only | |
107 | accepts 'a' to 'z' and 'A' to 'Z': | |
108 | ||
109 | {\small% | |
110 | \begin{verbatim} | |
111 | void MyTextCtrl::OnChar(wxKeyEvent& event) | |
112 | { | |
113 | if ( isalpha( event.KeyCode() ) ) | |
114 | { | |
115 | // key code is within legal range. we call event.Skip() so the | |
fc2171bd | 116 | // event can be processed either in the base wxWidgets class |
5fc02438 | 117 | // or the native control. |
b32c6ff0 RD |
118 | |
119 | event.Skip(); | |
5fc02438 RR |
120 | } |
121 | else | |
122 | { | |
123 | // illegal key hit. we don't call event.Skip() so the | |
124 | // event is not processed anywhere else. | |
b32c6ff0 | 125 | |
5fc02438 RR |
126 | wxBell(); |
127 | } | |
128 | } | |
5fc02438 RR |
129 | \end{verbatim} |
130 | }% | |
131 | ||
132 | ||
a660d684 KB |
133 | The normal order of event table searching by ProcessEvent is as follows: |
134 | ||
135 | \begin{enumerate}\itemsep=0pt | |
136 | \item If the object is disabled (via a call to \helpref{wxEvtHandler::SetEvtHandlerEnabled}{wxevthandlersetevthandlerenabled}) | |
137 | the function skips to step (6). | |
138 | \item If the object is a wxWindow, {\bf ProcessEvent} is recursively called on the window's\rtfsp | |
cc81d32f | 139 | \helpref{wxValidator}{wxvalidator}. If this returns true, the function exits. |
a660d684 KB |
140 | \item {\bf SearchEventTable} is called for this event handler. If this fails, the base |
141 | class table is tried, and so on until no more tables exist or an appropriate function was found, | |
142 | in which case the function exits. | |
143 | \item The search is applied down the entire chain of event handlers (usually the chain has a length | |
144 | of one). If this succeeds, the function exits. | |
1648d51b VZ |
145 | \item If the object is a wxWindow and the event is set to set to propagate (in the library only |
146 | wxCommandEvent based events are set to propagate), {\bf ProcessEvent} is recursively applied | |
147 | to the parent window's event handler. If this returns true, the function exits. | |
a660d684 KB |
148 | \item Finally, {\bf ProcessEvent} is called on the wxApp object. |
149 | \end{enumerate} | |
150 | ||
b32c6ff0 | 151 | {\bf Pay close attention to Step 5.} People often overlook or get |
fc2171bd | 152 | confused by this powerful feature of the wxWidgets event processing |
1648d51b VZ |
153 | system. To put it a different way, events set to propagate |
154 | (\helpref{See: wxEvent::ShouldPropagate}{wxeventshouldpropagate}) | |
155 | (most likely derived either directly or indirectly from wxCommandEvent) | |
156 | will travel up the containment hierarchy from child to parent until the | |
157 | maximal propagation level is reached or an event handler is found that | |
158 | doesn't call \helpref{event.Skip()}{wxeventskip}. | |
b32c6ff0 | 159 | |
e4b713a2 | 160 | Finally, there is another additional complication (which, in fact, simplifies |
fc2171bd | 161 | life of wxWidgets programmers significantly): when propagating the command |
e4b713a2 VZ |
162 | events upwards to the parent window, the event propagation stops when it |
163 | reaches the parent dialog, if any. This means that you don't risk to get | |
164 | unexpected events from the dialog controls (which might be left unprocessed by | |
165 | the dialog itself because it doesn't care about them) when a modal dialog is | |
166 | popped up. The events do propagate beyond the frames, however. The rationale | |
167 | for this choice is that there are only a few frames in a typical application | |
168 | and their parent-child relation are well understood by the programmer while it | |
169 | may be very difficult, if not impossible, to track down all the dialogs which | |
170 | may be popped up in a complex program (remember that some are created | |
fc2171bd | 171 | automatically by wxWidgets). If you need to specify a different behaviour for |
e4b713a2 VZ |
172 | some reason, you can use |
173 | \helpref{SetExtraStyle(wxWS\_EX\_BLOCK\_EVENTS)}{wxwindowsetextrastyle} | |
174 | explicitly to prevent the events from being propagated beyond the given window | |
175 | or unset this flag for the dialogs which have it on by default. | |
176 | ||
b32c6ff0 RD |
177 | Typically events that deal with a window as a window (size, motion, |
178 | paint, mouse, keyboard, etc.) are sent only to the window. Events | |
179 | that have a higher level of meaning and/or are generated by the window | |
180 | itself, (button click, menu select, tree expand, etc.) are command | |
181 | events and are sent up to the parent to see if it is interested in the | |
182 | event. | |
183 | ||
a660d684 KB |
184 | Note that your application may wish to override ProcessEvent to redirect processing of |
185 | events. This is done in the document/view framework, for example, to allow event handlers | |
e702ff0f | 186 | to be defined in the document or view. To test for command events (which will probably |
1648d51b VZ |
187 | be the only events you wish to redirect), you may use |
188 | \helpref{wxEvent::IsCommandEvent}{wxeventiscommandevent} for efficiency, | |
189 | instead of using the slower run-time type system. | |
a660d684 | 190 | |
5fc02438 | 191 | As mentioned above, only command events are recursively applied to the parents event |
dbd94b75 | 192 | handler in the library itself. As this quite often causes confusion for users, |
1648d51b | 193 | here is a list of system events which will NOT get sent to the parent's event handler: |
5fc02438 RR |
194 | |
195 | \begin{twocollist}\itemsep=0pt | |
196 | \twocolitem{\helpref{wxEvent}{wxevent}}{The event base class} | |
197 | \twocolitem{\helpref{wxActivateEvent}{wxactivateevent}}{A window or application activation event} | |
198 | \twocolitem{\helpref{wxCloseEvent}{wxcloseevent}}{A close window or end session event} | |
199 | \twocolitem{\helpref{wxEraseEvent}{wxeraseevent}}{An erase background event} | |
200 | \twocolitem{\helpref{wxFocusEvent}{wxfocusevent}}{A window focus event} | |
201 | \twocolitem{\helpref{wxKeyEvent}{wxkeyevent}}{A keypress event} | |
202 | \twocolitem{\helpref{wxIdleEvent}{wxidleevent}}{An idle event} | |
203 | \twocolitem{\helpref{wxInitDialogEvent}{wxinitdialogevent}}{A dialog initialisation event} | |
204 | \twocolitem{\helpref{wxJoystickEvent}{wxjoystickevent}}{A joystick event} | |
205 | \twocolitem{\helpref{wxMenuEvent}{wxmenuevent}}{A menu event} | |
206 | \twocolitem{\helpref{wxMouseEvent}{wxmouseevent}}{A mouse event} | |
207 | \twocolitem{\helpref{wxMoveEvent}{wxmoveevent}}{A move event} | |
208 | \twocolitem{\helpref{wxPaintEvent}{wxpaintevent}}{A paint event} | |
209 | \twocolitem{\helpref{wxQueryLayoutInfoEvent}{wxquerylayoutinfoevent}}{Used to query layout information} | |
15b0d048 | 210 | \twocolitem{\helpref{wxSetCursorEvent}{wxsetcursorevent}}{Used for special cursor processing based on current mouse position} |
5fc02438 | 211 | \twocolitem{\helpref{wxSizeEvent}{wxsizeevent}}{A size event} |
8a293590 | 212 | \twocolitem{\helpref{wxScrollWinEvent}{wxscrollwinevent}}{A scroll event sent by a scrolled window (not a scroll bar)} |
5fc02438 | 213 | \twocolitem{\helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}}{A system colour change event} |
5fc02438 RR |
214 | \end{twocollist} |
215 | ||
216 | In some cases, it might be desired by the programmer to get a certain number | |
1f112209 | 217 | of system events in a parent window, for example all key events sent to, but not |
5fc02438 RR |
218 | used by, the native controls in a dialog. In this case, a special event handler |
219 | will have to be written that will override ProcessEvent() in order to pass | |
e702ff0f JS |
220 | all events (or any selection of them) to the parent window. |
221 | ||
e0c664bf VZ |
222 | |
223 | \subsection{Events generated by the user vs programmatically generated events}\label{progevent} | |
224 | ||
225 | While generically \helpref{wxEvents}{wxevent} can be generated both by user | |
226 | actions (e.g. resize of a \helpref{wxWindow}{wxwindow}) and by calls to functions | |
227 | (e.g. \helpref{wxWindow::SetSize}{wxwindowsetsize}), wxWidgets controls | |
228 | normally send \helpref{wxCommandEvent}{wxcommandevent}-derived events only for | |
229 | the user-generated events. The only {\bf exceptions} to this rule are: | |
230 | ||
231 | \begin{twocollist}\itemsep=0pt | |
232 | \twocolitem{\helpref{wxNotebook::AddPage}{wxnotebookaddpage}}{No event-free alternatives} | |
233 | \twocolitem{\helpref{wxNotebook::AdvanceSelection}{wxnotebookadvanceselection}}{No event-free alternatives} | |
234 | \twocolitem{\helpref{wxNotebook::DeletePage}{wxnotebookdeletepage}}{No event-free alternatives} | |
235 | \twocolitem{\helpref{wxNotebook::SetSelection}{wxnotebooksetselection}}{Use \helpref{wxNotebook::ChangeSelection}{wxnotebookchangeselection} instead, as \helpref{wxNotebook::SetSelection}{wxnotebooksetselection} is deprecated} | |
236 | \twocolitem{\helpref{wxTreeCtrl::Delete}{wxtreectrldelete}}{No event-free alternatives} | |
237 | \twocolitem{\helpref{wxTreeCtrl::DeleteAllItems}{wxtreectrldeleteallitems}}{No event-free alternatives} | |
238 | \twocolitem{\helpref{wxTreeCtrl::EditLabel}{wxtreectrleditlabel}}{No event-free alternatives} | |
b72979e9 | 239 | \twocolitem{All \helpref{wxTextCtrl}{wxtextctrl} methods}{\helpref{wxTextCtrl::ChangeValue}{wxtextctrlchangevalue} can be used instead |
e0c664bf VZ |
240 | of \helpref{wxTextCtrl::SetValue}{wxtextctrlsetvalue} but the other functions, |
241 | such as \helpref{Replace}{wxtextctrlreplace} or \helpref{WriteText}{wxtextctrlwritetext} | |
242 | don't have event-free equivalents} | |
243 | \end{twocollist} | |
244 | ||
245 | ||
d2d93fdd VZ |
246 | % VZ: it doesn't work like this, but just in case we ever reenable this |
247 | % behaviour, I leave it here | |
248 | % | |
249 | % \subsection{Redirection of command events to the window with the focus} | |
250 | % | |
251 | % The usual upward search through the window hierarchy for command event | |
252 | % handlers does not always meet an application's requirements. Say you have two | |
253 | % wxTextCtrl windows in a frame, plus a toolbar with Cut, Copy and Paste | |
254 | % buttons. To avoid the need to define event handlers in the frame | |
255 | % and redirect them explicitly to the window with the focus, command events | |
256 | % are sent to the window with the focus first, for | |
257 | % menu and toolbar command and UI update events only. This means that | |
258 | % each window can handle its own commands and UI updates independently. In | |
259 | % fact wxTextCtrl can handle Cut, Copy, Paste, Undo and Redo commands and UI update | |
260 | % requests, so no extra coding is required to support them in your menus and | |
261 | % toolbars. | |
5fc02438 | 262 | |
a203f6c0 | 263 | \subsection{Pluggable event handlers}\label{pluggablehandlers} |
a660d684 KB |
264 | |
265 | In fact, you don't have to derive a new class from a window class | |
266 | if you don't want to. You can derive a new class from wxEvtHandler instead, | |
267 | defining the appropriate event table, and then call | |
268 | \rtfsp\helpref{wxWindow::SetEventHandler}{wxwindowseteventhandler} (or, preferably, | |
269 | \rtfsp\helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler}) to make this | |
270 | event handler the object that responds to events. This way, you can avoid | |
a36885a0 | 271 | a lot of class derivation, and use instances of the same event handler class (but different |
f463afe3 | 272 | objects as the same event handler object shouldn't be used more than once) to |
44124088 | 273 | handle events from instances of different widget classes. If you ever have to call a window's event handler |
a660d684 KB |
274 | manually, use the GetEventHandler function to retrieve the window's event handler and use that |
275 | to call the member function. By default, GetEventHandler returns a pointer to the window itself | |
276 | unless an application has redirected event handling using SetEventHandler or PushEventHandler. | |
277 | ||
278 | One use of PushEventHandler is to temporarily or permanently change the | |
279 | behaviour of the GUI. For example, you might want to invoke a dialog editor | |
280 | in your application that changes aspects of dialog boxes. You can | |
281 | grab all the input for an existing dialog box, and edit it `in situ', | |
282 | before restoring its behaviour to normal. So even if the application | |
283 | has derived new classes to customize behaviour, your utility can indulge | |
284 | in a spot of body-snatching. It could be a useful technique for on-line | |
285 | tutorials, too, where you take a user through a serious of steps and | |
286 | don't want them to diverge from the lesson. Here, you can examine the events | |
287 | coming from buttons and windows, and if acceptable, pass them through to | |
288 | the original event handler. Use PushEventHandler/PopEventHandler | |
289 | to form a chain of event handlers, where each handler processes a different | |
290 | range of events independently from the other handlers. | |
291 | ||
1f112209 | 292 | \subsection{Window identifiers}\label{windowids} |
a660d684 | 293 | |
2862acde VZ |
294 | \index{identifiers}\index{wxID}Window identifiers are integers, and are used to |
295 | uniquely determine window identity in the event system (though you can use it | |
296 | for other purposes). In fact, identifiers do not need to be unique | |
297 | across your entire application just so long as they are unique within a | |
298 | particular context you're interested in, such as a frame and its children. You | |
299 | may use the {\tt wxID\_OK} identifier, for example, on any number of dialogs so | |
300 | long as you don't have several within the same dialog. | |
301 | ||
302 | If you pass {\tt wxID\_ANY} to a window constructor, an identifier will be | |
fc2171bd | 303 | generated for you automatically by wxWidgets. This is useful when you don't |
2862acde VZ |
304 | care about the exact identifier either because you're not going to process the |
305 | events from the control being created at all or because you process the events | |
306 | from all controls in one place (in which case you should specify {\tt wxID\_ANY} | |
307 | in the event table or \helpref{wxEvtHandler::Connect}{wxevthandlerconnect} call | |
308 | as well. The automatically generated identifiers are always negative and so | |
309 | will never conflict with the user-specified identifiers which must be always | |
310 | positive. | |
311 | ||
312 | The following standard identifiers are supplied. You can use wxID\_HIGHEST to | |
313 | determine the number above which it is safe to define your own identifiers. Or, | |
314 | you can use identifiers below wxID\_LOWEST. | |
1f112209 JS |
315 | |
316 | \begin{verbatim} | |
2862acde VZ |
317 | #define wxID_ANY -1 |
318 | ||
1f112209 JS |
319 | #define wxID_LOWEST 4999 |
320 | ||
321 | #define wxID_OPEN 5000 | |
322 | #define wxID_CLOSE 5001 | |
323 | #define wxID_NEW 5002 | |
324 | #define wxID_SAVE 5003 | |
325 | #define wxID_SAVEAS 5004 | |
326 | #define wxID_REVERT 5005 | |
327 | #define wxID_EXIT 5006 | |
328 | #define wxID_UNDO 5007 | |
329 | #define wxID_REDO 5008 | |
330 | #define wxID_HELP 5009 | |
331 | #define wxID_PRINT 5010 | |
332 | #define wxID_PRINT_SETUP 5011 | |
333 | #define wxID_PREVIEW 5012 | |
334 | #define wxID_ABOUT 5013 | |
335 | #define wxID_HELP_CONTENTS 5014 | |
336 | #define wxID_HELP_COMMANDS 5015 | |
337 | #define wxID_HELP_PROCEDURES 5016 | |
338 | #define wxID_HELP_CONTEXT 5017 | |
339 | ||
340 | #define wxID_CUT 5030 | |
341 | #define wxID_COPY 5031 | |
342 | #define wxID_PASTE 5032 | |
343 | #define wxID_CLEAR 5033 | |
344 | #define wxID_FIND 5034 | |
345 | #define wxID_DUPLICATE 5035 | |
346 | #define wxID_SELECTALL 5036 | |
bf95a04f JS |
347 | #define wxID_DELETE 5037 |
348 | #define wxID_REPLACE 5038 | |
349 | #define wxID_REPLACE_ALL 5039 | |
350 | #define wxID_PROPERTIES 5040 | |
351 | ||
352 | #define wxID_VIEW_DETAILS 5041 | |
353 | #define wxID_VIEW_LARGEICONS 5042 | |
354 | #define wxID_VIEW_SMALLICONS 5043 | |
355 | #define wxID_VIEW_LIST 5044 | |
356 | #define wxID_VIEW_SORTDATE 5045 | |
357 | #define wxID_VIEW_SORTNAME 5046 | |
358 | #define wxID_VIEW_SORTSIZE 5047 | |
359 | #define wxID_VIEW_SORTTYPE 5048 | |
1f112209 JS |
360 | |
361 | #define wxID_FILE1 5050 | |
362 | #define wxID_FILE2 5051 | |
363 | #define wxID_FILE3 5052 | |
364 | #define wxID_FILE4 5053 | |
365 | #define wxID_FILE5 5054 | |
366 | #define wxID_FILE6 5055 | |
367 | #define wxID_FILE7 5056 | |
368 | #define wxID_FILE8 5057 | |
369 | #define wxID_FILE9 5058 | |
370 | ||
371 | #define wxID_OK 5100 | |
372 | #define wxID_CANCEL 5101 | |
373 | #define wxID_APPLY 5102 | |
374 | #define wxID_YES 5103 | |
375 | #define wxID_NO 5104 | |
376 | #define wxID_STATIC 5105 | |
377 | ||
378 | #define wxID_HIGHEST 5999 | |
379 | \end{verbatim} | |
380 | ||
381 | \subsection{Event macros summary}\label{eventmacros} | |
a660d684 | 382 | |
a660d684 KB |
383 | \wxheading{Macros listed by event class} |
384 | ||
385 | The documentation for specific event macros is organised by event class. Please refer | |
386 | to these sections for details. | |
387 | ||
388 | \twocolwidtha{8cm}% | |
389 | \begin{twocollist}\itemsep=0pt | |
390 | \twocolitem{\helpref{wxActivateEvent}{wxactivateevent}}{The EVT\_ACTIVATE and EVT\_ACTIVATE\_APP macros intercept | |
391 | activation and deactivation events.} | |
392 | \twocolitem{\helpref{wxCommandEvent}{wxcommandevent}}{A range of commonly-used control events.} | |
393 | \twocolitem{\helpref{wxCloseEvent}{wxcloseevent}}{The EVT\_CLOSE macro handles window closure | |
394 | called via \helpref{wxWindow::Close}{wxwindowclose}.} | |
395 | \twocolitem{\helpref{wxDropFilesEvent}{wxdropfilesevent}}{The EVT\_DROP\_FILES macros handles | |
396 | file drop events.} | |
397 | \twocolitem{\helpref{wxEraseEvent}{wxeraseevent}}{The EVT\_ERASE\_BACKGROUND macro is used to handle window erase requests.} | |
f6bcfd97 | 398 | \twocolitem{\helpref{wxFocusEvent}{wxfocusevent}}{The EVT\_SET\_FOCUS and EVT\_KILL\_FOCUS macros are used to handle keyboard focus events.} |
e4b713a2 VZ |
399 | \twocolitem{\helpref{wxKeyEvent}{wxkeyevent}}{EVT\_CHAR, EVT\_KEY\_DOWN and |
400 | EVT\_KEY\_UP macros handle keyboard input for any window.} | |
a660d684 KB |
401 | \twocolitem{\helpref{wxIdleEvent}{wxidleevent}}{The EVT\_IDLE macro handle application idle events |
402 | (to process background tasks, for example).} | |
403 | \twocolitem{\helpref{wxInitDialogEvent}{wxinitdialogevent}}{The EVT\_INIT\_DIALOG macro is used | |
404 | to handle dialog initialisation.} | |
405 | \twocolitem{\helpref{wxListEvent}{wxlistevent}}{These macros handle \helpref{wxListCtrl}{wxlistctrl} events.} | |
406 | \twocolitem{\helpref{wxMenuEvent}{wxmenuevent}}{These macros handle special menu events (not menu commands).} | |
407 | \twocolitem{\helpref{wxMouseEvent}{wxmouseevent}}{Mouse event macros can handle either individual | |
408 | mouse events or all mouse events.} | |
409 | \twocolitem{\helpref{wxMoveEvent}{wxmoveevent}}{The EVT\_MOVE macro is used to handle a window move.} | |
a660d684 | 410 | \twocolitem{\helpref{wxPaintEvent}{wxpaintevent}}{The EVT\_PAINT macro is used to handle window paint requests.} |
f6bcfd97 | 411 | \twocolitem{\helpref{wxScrollEvent}{wxscrollevent}}{These macros are used to handle scroll events from |
fd128b0c | 412 | \helpref{wxScrollBar}{wxscrollbar}, \helpref{wxSlider}{wxslider},and \helpref{wxSpinButton}{wxspinbutton}.} |
15b0d048 | 413 | \twocolitem{\helpref{wxSetCursorEvent}{wxsetcursorevent}}{The EVT\_SET\_CURSOR macro is used for special cursor processing.} |
a660d684 | 414 | \twocolitem{\helpref{wxSizeEvent}{wxsizeevent}}{The EVT\_SIZE macro is used to handle a window resize.} |
53f7bea5 | 415 | \twocolitem{\helpref{wxSplitterEvent}{wxsplitterevent}}{The EVT\_SPLITTER\_SASH\_POS\_CHANGED, EVT\_SPLITTER\_UNSPLIT |
552861bf | 416 | and EVT\_SPLITTER\_DCLICK macros are used to handle the various splitter window events.} |
a660d684 KB |
417 | \twocolitem{\helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}}{The EVT\_SYS\_COLOUR\_CHANGED macro is used to handle |
418 | events informing the application that the user has changed the system colours (Windows only).} | |
419 | \twocolitem{\helpref{wxTreeEvent}{wxtreeevent}}{These macros handle \helpref{wxTreeCtrl}{wxtreectrl} events.} | |
53f7bea5 UB |
420 | \twocolitem{\helpref{wxUpdateUIEvent}{wxupdateuievent}}{The EVT\_UPDATE\_UI macro is used to handle user interface |
421 | update pseudo-events, which are generated to give the application the chance to update the visual state of menus, | |
422 | toolbars and controls.} | |
a660d684 KB |
423 | \end{twocollist} |
424 | ||
265accbe RR |
425 | \subsection{Custom event summary}\label{customevents} |
426 | ||
427 | \wxheading{General approach} | |
428 | ||
429 | Since version 2.2.x of wxWidgets, each event type is identified by ID which | |
430 | is given to the event type {\it at runtime} which makes it possible to add | |
431 | new event types to the library or application without risking ID clashes | |
432 | (two different event types mistakingly getting the same event ID). This | |
433 | event type ID is stored in a struct of type {\bf const wxEventType}. | |
434 | ||
435 | In order to define a new event type, there are principally two choices. | |
436 | One is to define a entirely new event class (typically deriving from | |
437 | \helpref{wxEvent}{wxevent} or \helpref{wxCommandEvent}{wxcommandevent}. | |
438 | The other is to use the existing event classes and give them an new event | |
439 | type. You'll have to define and declare a new event type using either way, | |
440 | and this is done using the following macros: | |
441 | ||
442 | \begin{verbatim} | |
443 | // in the header of the source file | |
79b4c33a | 444 | BEGIN_DECLARE_EVENT_TYPES() |
265accbe | 445 | DECLARE_EVENT_TYPE(name, value) |
79b4c33a | 446 | END_DECLARE_EVENT_TYPES() |
265accbe RR |
447 | |
448 | // in the implementation | |
449 | DEFINE_EVENT_TYPE(name) | |
450 | \end{verbatim} | |
451 | ||
452 | You can ignore the {\it value} parameter of the DECLARE\_EVENT\_TYPE macro | |
fab86f26 | 453 | since it is used only for backwards compatibility with wxWidgets 2.0.x based |
265accbe RR |
454 | applications where you have to give the event type ID an explicit value. |
455 | ||
79b4c33a VZ |
456 | See also the \helpref{event sample}{sampleevent} for an example of code |
457 | defining and working with the custom event types. | |
458 | ||
265accbe RR |
459 | \wxheading{Using existing event classes} |
460 | ||
461 | If you just want to use a \helpref{wxCommandEvent}{wxcommandevent} with | |
462 | a new event type, you can then use one of the generic event table macros | |
463 | listed below, without having to define a new macro yourself. This also | |
464 | has the advantage that you won't have to define a new \helpref{wxEvent::Clone()}{wxeventclone} | |
465 | method for posting events between threads etc. This could look like this | |
466 | in your code: | |
467 | ||
468 | {\small% | |
469 | \begin{verbatim} | |
470 | DECLARE_EVENT_TYPE(wxEVT_MY_EVENT, -1) | |
471 | ||
472 | DEFINE_EVENT_TYPE(wxEVT_MY_EVENT) | |
473 | ||
474 | // user code intercepting the event | |
475 | ||
476 | BEGIN_EVENT_TABLE(MyFrame, wxFrame) | |
477 | EVT_MENU (wxID_EXIT, MyFrame::OnExit) | |
478 | // .... | |
78a445a8 | 479 | EVT_COMMAND (ID_MY_WINDOW, wxEVT_MY_EVENT, MyFrame::OnMyEvent) |
265accbe RR |
480 | END_EVENT_TABLE() |
481 | ||
482 | void MyFrame::OnMyEvent( wxCommandEvent &event ) | |
483 | { | |
484 | // do something | |
485 | wxString text = event.GetText(); | |
486 | } | |
487 | ||
488 | ||
489 | // user code sending the event | |
490 | ||
491 | void MyWindow::SendEvent() | |
492 | { | |
493 | wxCommandEvent event( wxEVT_MY_EVENT, GetId() ); | |
494 | event.SetEventObject( this ); | |
495 | // Give it some contents | |
496 | event.SetText( wxT("Hallo") ); | |
497 | // Send it | |
498 | GetEventHandler()->ProcessEvent( event ); | |
499 | } | |
500 | \end{verbatim} | |
501 | }% | |
502 | ||
503 | ||
504 | \wxheading{Generic event table macros} | |
505 | ||
506 | \twocolwidtha{8cm}% | |
507 | \begin{twocollist}\itemsep=0pt | |
508 | \twocolitem{\windowstyle{EVT\_CUSTOM(event, id, func)}}{Allows you to add a custom event table | |
509 | entry by specifying the event identifier (such as wxEVT\_SIZE), the window identifier, | |
510 | and a member function to call.} | |
511 | \twocolitem{\windowstyle{EVT\_CUSTOM\_RANGE(event, id1, id2, func)}}{The same as EVT\_CUSTOM, | |
512 | but responds to a range of window identifiers.} | |
513 | \twocolitem{\windowstyle{EVT\_COMMAND(id, event, func)}}{The same as EVT\_CUSTOM, but | |
514 | expects a member function with a wxCommandEvent argument.} | |
515 | \twocolitem{\windowstyle{EVT\_COMMAND\_RANGE(id1, id2, event, func)}}{The same as EVT\_CUSTOM\_RANGE, but | |
516 | expects a member function with a wxCommandEvent argument.} | |
6c4fc6a8 | 517 | \twocolitem{\windowstyle{EVT\_NOTIFY(event, id, func)}}{The same as EVT\_CUSTOM, but |
265accbe | 518 | expects a member function with a wxNotifyEvent argument.} |
6c4fc6a8 | 519 | \twocolitem{\windowstyle{EVT\_NOTIFY\_RANGE(event, id1, id2, func)}}{The same as EVT\_CUSTOM\_RANGE, but |
265accbe RR |
520 | expects a member function with a wxNotifyEvent argument.} |
521 | \end{twocollist} | |
522 | ||
523 | ||
524 | \wxheading{Defining your own event class} | |
525 | ||
526 | Under certain circumstances, it will be required to define your own event | |
527 | class e.g. for sending more complex data from one place to another. Apart | |
528 | from defining your event class, you will also need to define your own | |
529 | event table macro (which is quite long). Watch out to put in enough | |
8749ce0a | 530 | casts to the inherited event function. Here is an example: |
265accbe RR |
531 | |
532 | {\small% | |
533 | \begin{verbatim} | |
534 | ||
535 | // code defining event | |
536 | ||
537 | class wxPlotEvent: public wxNotifyEvent | |
538 | { | |
539 | public: | |
540 | wxPlotEvent( wxEventType commandType = wxEVT_NULL, int id = 0 ); | |
541 | ||
542 | // accessors | |
543 | wxPlotCurve *GetCurve() | |
544 | { return m_curve; } | |
545 | ||
546 | // required for sending with wxPostEvent() | |
51048c62 | 547 | virtual wxEvent *Clone() const; |
265accbe RR |
548 | |
549 | private: | |
550 | wxPlotCurve *m_curve; | |
551 | }; | |
552 | ||
7d2beb15 | 553 | DECLARE_EVENT_TYPE( wxEVT_PLOT_ACTION, -1 ) |
265accbe RR |
554 | |
555 | typedef void (wxEvtHandler::*wxPlotEventFunction)(wxPlotEvent&); | |
556 | ||
557 | #define EVT_PLOT(id, fn) \ | |
558 | DECLARE_EVENT_TABLE_ENTRY( wxEVT_PLOT_ACTION, id, -1, \ | |
559 | (wxObjectEventFunction) (wxEventFunction) (wxCommandEventFunction) (wxNotifyEventFunction) \ | |
560 | wxStaticCastEvent( wxPlotEventFunction, & fn ), (wxObject *) NULL ), | |
561 | ||
562 | ||
563 | // code implementing the event type and the event class | |
564 | ||
565 | DEFINE_EVENT_TYPE( wxEVT_PLOT_ACTION ) | |
566 | ||
567 | wxPlotEvent::wxPlotEvent( ... | |
568 | ||
569 | ||
570 | // user code intercepting the event | |
571 | ||
572 | BEGIN_EVENT_TABLE(MyFrame, wxFrame) | |
573 | EVT_PLOT (ID_MY_WINDOW, MyFrame::OnPlot) | |
574 | END_EVENT_TABLE() | |
575 | ||
576 | void MyFrame::OnPlot( wxPlotEvent &event ) | |
577 | { | |
578 | wxPlotCurve *curve = event.GetCurve(); | |
579 | } | |
580 | ||
581 | ||
582 | // user code sending the event | |
583 | ||
584 | void MyWindow::SendEvent() | |
585 | { | |
586 | wxPlotEvent event( wxEVT_PLOT_ACTION, GetId() ); | |
587 | event.SetEventObject( this ); | |
588 | event.SetCurve( m_curve ); | |
589 | GetEventHandler()->ProcessEvent( event ); | |
590 | } | |
591 | ||
592 | \end{verbatim} | |
593 | }% | |
594 |