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 | ||
5 | \subsection{Introduction} | |
6 | ||
7 | Before version 2.0 of wxWindows, events were handled by the application | |
8 | either by supplying callback functions, or by overriding virtual member | |
9 | functions such as {\bf OnSize}. | |
10 | ||
11 | From wxWindows 2.0, {\it event tables} are used instead, with a few exceptions. | |
12 | ||
13 | An event table is placed in an implementation file to tell wxWindows how to map | |
14 | events to member functions. These member functions are not virtual functions, but | |
15 | they all similar in form: they take a single wxEvent-derived argument, and have a void return | |
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 | ||
29 | The first two entries map menu commands to two different member functions. The EVT\_SIZE macro | |
30 | doesn't need a window identifier, since normally you are only interested in the | |
31 | current window's size events. (In fact you could intercept a particular window's size event | |
32 | by using EVT\_CUSTOM(wxEVT\_SIZE, id, func).) | |
33 | ||
34 | The EVT\_BUTTON macro demonstrates that the originating event does not have to come from | |
35 | the window class implementing the event table - if the event source is a button within a panel within a frame, this will still | |
36 | work, because event tables are searched up through the hierarchy of windows. In this | |
37 | case, the button's event table will be searched, then the parent panel's, then the frame's. | |
38 | ||
39 | As mentioned before, the member functions that handle events do not have to be virtual. | |
5fc02438 RR |
40 | Indeed, the member functions should not be virtual as the event handler ignores that |
41 | the functions are virtual, i.e. overriding a virtual member function in a derived class | |
42 | will not have any effect. | |
a660d684 KB |
43 | These member functions take an event argument, and the class of event differs according |
44 | to the type of event and the class of the originating window. For size | |
45 | events, \helpref{wxSizeEvent}{wxsizeevent} is used. For menu commands and most control | |
46 | commands (such as button presses), \helpref{wxCommandEvent}{wxcommandevent} is used. | |
47 | When controls get more complicated, then specific event classes are used, such | |
48 | as \helpref{wxTreeEvent}{wxtreeevent} for events from \helpref{wxTreeCtrl}{wxtreectrl} windows. | |
49 | ||
50 | As well as the event table in the implementation file, there must be a DECLARE\_EVENT\_TABLE | |
51 | macro in the class definition. For example: | |
52 | ||
53 | {\small% | |
54 | \begin{verbatim} | |
55 | class MyFrame: public wxFrame { | |
56 | ||
57 | DECLARE_DYNAMIC_CLASS(MyFrame) | |
58 | ||
59 | public: | |
60 | ... | |
61 | void OnExit(wxCommandEvent& event); | |
62 | void OnSize(wxSizeEvent& event); | |
63 | protected: | |
64 | int m_count; | |
65 | ... | |
66 | DECLARE_EVENT_TABLE() | |
67 | }; | |
68 | \end{verbatim} | |
69 | }% | |
70 | ||
71 | \subsection{How events are processed}\label{eventprocessing} | |
72 | ||
73 | When an event is received from the windowing system, wxWindows calls \helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent} on | |
74 | the first event handler object belonging to the window generating the event. | |
75 | ||
5fc02438 RR |
76 | It may be noted that wxWindows' event processing system implements something |
77 | very close to virtual methods in normal C++, i.e. it is possible to alter | |
78 | the behaviour of a class by overriding its event handling functions. In | |
79 | many cases this works even for changing the behaviour of native controls. | |
80 | E.g. it is possible to filter out a number of key events sent by the | |
81 | system to a native text control by overriding wxTextCtrl and defining a | |
82 | handler for key events using EVT_KEY_DOWN. This would in-deed prevent | |
83 | any key events from being sent to the native control - which might not be | |
84 | what is desired. In this case the event handler function has to call Skip() | |
85 | so as to indicate that it did NOT handle the event at all. | |
86 | ||
87 | In practice, this would look like this if the derived text control only | |
88 | accepts 'a' to 'z' and 'A' to 'Z': | |
89 | ||
90 | {\small% | |
91 | \begin{verbatim} | |
92 | void MyTextCtrl::OnChar(wxKeyEvent& event) | |
93 | { | |
94 | if ( isalpha( event.KeyCode() ) ) | |
95 | { | |
96 | // key code is within legal range. we call event.Skip() so the | |
97 | // event can be processed either in the base wxWindows class | |
98 | // or the native control. | |
99 | ||
100 | event.Skip(); | |
101 | } | |
102 | else | |
103 | { | |
104 | // illegal key hit. we don't call event.Skip() so the | |
105 | // event is not processed anywhere else. | |
106 | ||
107 | wxBell(); | |
108 | } | |
109 | } | |
110 | ||
111 | \end{verbatim} | |
112 | }% | |
113 | ||
114 | ||
a660d684 KB |
115 | The normal order of event table searching by ProcessEvent is as follows: |
116 | ||
117 | \begin{enumerate}\itemsep=0pt | |
118 | \item If the object is disabled (via a call to \helpref{wxEvtHandler::SetEvtHandlerEnabled}{wxevthandlersetevthandlerenabled}) | |
119 | the function skips to step (6). | |
120 | \item If the object is a wxWindow, {\bf ProcessEvent} is recursively called on the window's\rtfsp | |
121 | \helpref{wxValidator}{wxvalidator}. If this returns TRUE, the function exits. | |
122 | \item {\bf SearchEventTable} is called for this event handler. If this fails, the base | |
123 | class table is tried, and so on until no more tables exist or an appropriate function was found, | |
124 | in which case the function exits. | |
125 | \item The search is applied down the entire chain of event handlers (usually the chain has a length | |
126 | of one). If this succeeds, the function exits. | |
127 | \item If the object is a wxWindow and the event is a wxCommandEvent, {\bf ProcessEvent} is | |
128 | recursively applied to the parent window's event handler. If this returns TRUE, the function exits. | |
129 | \item Finally, {\bf ProcessEvent} is called on the wxApp object. | |
130 | \end{enumerate} | |
131 | ||
132 | Note that your application may wish to override ProcessEvent to redirect processing of | |
133 | events. This is done in the document/view framework, for example, to allow event handlers | |
134 | to be defined in the document or view. | |
135 | ||
5fc02438 RR |
136 | As mentioned above, only command events are recursively applied to the parents event |
137 | handler. As this quite often causes confusion for users, here is a list of system | |
138 | events which will NOT get sent to the parent's event handler: | |
139 | ||
140 | \begin{twocollist}\itemsep=0pt | |
141 | \twocolitem{\helpref{wxEvent}{wxevent}}{The event base class} | |
142 | \twocolitem{\helpref{wxActivateEvent}{wxactivateevent}}{A window or application activation event} | |
143 | \twocolitem{\helpref{wxCloseEvent}{wxcloseevent}}{A close window or end session event} | |
144 | \twocolitem{\helpref{wxEraseEvent}{wxeraseevent}}{An erase background event} | |
145 | \twocolitem{\helpref{wxFocusEvent}{wxfocusevent}}{A window focus event} | |
146 | \twocolitem{\helpref{wxKeyEvent}{wxkeyevent}}{A keypress event} | |
147 | \twocolitem{\helpref{wxIdleEvent}{wxidleevent}}{An idle event} | |
148 | \twocolitem{\helpref{wxInitDialogEvent}{wxinitdialogevent}}{A dialog initialisation event} | |
149 | \twocolitem{\helpref{wxJoystickEvent}{wxjoystickevent}}{A joystick event} | |
150 | \twocolitem{\helpref{wxMenuEvent}{wxmenuevent}}{A menu event} | |
151 | \twocolitem{\helpref{wxMouseEvent}{wxmouseevent}}{A mouse event} | |
152 | \twocolitem{\helpref{wxMoveEvent}{wxmoveevent}}{A move event} | |
153 | \twocolitem{\helpref{wxPaintEvent}{wxpaintevent}}{A paint event} | |
154 | \twocolitem{\helpref{wxQueryLayoutInfoEvent}{wxquerylayoutinfoevent}}{Used to query layout information} | |
155 | \twocolitem{\helpref{wxSizeEvent}{wxsizeevent}}{A size event} | |
156 | \twocolitem{\helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}}{A system colour change event} | |
157 | \twocolitem{\helpref{wxUpdateUIEvent}{wxupdateuievent}}{A user interface update event} | |
158 | \end{twocollist} | |
159 | ||
160 | In some cases, it might be desired by the programmer to get a certain number | |
161 | of system events in a parent window, e.g. all key events sent to, but not | |
162 | used by, the native controls in a dialog. In this case, a special event handler | |
163 | will have to be written that will override ProcessEvent() in order to pass | |
164 | all events (or any selection of them) to the parent window. See next section. | |
165 | ||
a660d684 KB |
166 | \subsection{Pluggable event handlers} |
167 | ||
168 | In fact, you don't have to derive a new class from a window class | |
169 | if you don't want to. You can derive a new class from wxEvtHandler instead, | |
170 | defining the appropriate event table, and then call | |
171 | \rtfsp\helpref{wxWindow::SetEventHandler}{wxwindowseteventhandler} (or, preferably, | |
172 | \rtfsp\helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler}) to make this | |
173 | event handler the object that responds to events. This way, you can avoid | |
174 | a lot of class derivation, and use the same event handler object to | |
175 | handle events from instances of different classes. If you ever have to call a window's event handler | |
176 | manually, use the GetEventHandler function to retrieve the window's event handler and use that | |
177 | to call the member function. By default, GetEventHandler returns a pointer to the window itself | |
178 | unless an application has redirected event handling using SetEventHandler or PushEventHandler. | |
179 | ||
180 | One use of PushEventHandler is to temporarily or permanently change the | |
181 | behaviour of the GUI. For example, you might want to invoke a dialog editor | |
182 | in your application that changes aspects of dialog boxes. You can | |
183 | grab all the input for an existing dialog box, and edit it `in situ', | |
184 | before restoring its behaviour to normal. So even if the application | |
185 | has derived new classes to customize behaviour, your utility can indulge | |
186 | in a spot of body-snatching. It could be a useful technique for on-line | |
187 | tutorials, too, where you take a user through a serious of steps and | |
188 | don't want them to diverge from the lesson. Here, you can examine the events | |
189 | coming from buttons and windows, and if acceptable, pass them through to | |
190 | the original event handler. Use PushEventHandler/PopEventHandler | |
191 | to form a chain of event handlers, where each handler processes a different | |
192 | range of events independently from the other handlers. | |
193 | ||
194 | \subsection{Event macros summary}\label{eventmacros} | |
195 | ||
196 | \wxheading{Specifying an event table} | |
197 | ||
198 | \twocolwidtha{8cm}% | |
199 | \begin{twocollist}\itemsep=0pt | |
200 | \twocolitem{\windowstyle{EVT\_CUSTOM(eventId, id, func)}}{Allows you to add a custom event table | |
201 | entry by specifying the event identifier (such as wxEVT\_SIZE), the window identifier, | |
202 | and a member function to call.} | |
203 | \twocolitem{\windowstyle{EVT\_CUSTOM\_RANGE(eventId, id1, id2, func)}}{The same as EVT\_CUSTOM, | |
204 | but responds to a range of window identifiers.} | |
205 | \end{twocollist} | |
206 | ||
207 | \wxheading{Generic event table macros} | |
208 | ||
209 | \twocolwidtha{8cm}% | |
210 | \begin{twocollist}\itemsep=0pt | |
211 | \twocolitem{\windowstyle{EVT\_CUSTOM(eventId, id, func)}}{Allows you to add a custom event table | |
212 | entry by specifying the event identifier (such as wxEVT\_SIZE), the window identifier, | |
213 | and a member function to call.} | |
214 | \twocolitem{\windowstyle{EVT\_CUSTOM\_RANGE(eventId, id1, id2, func)}}{The same as EVT\_CUSTOM, | |
215 | but responds to a range of window identifiers.} | |
216 | \twocolitem{\windowstyle{EVT\_COMMAND(eventId, id, func)}}{The same as EVT\_CUSTOM, but | |
217 | expects a member function with a wxCommandEvent argument.} | |
218 | \twocolitem{\windowstyle{EVT\_COMMAND\_RANGE(eventId, id1, id2, func)}}{The same as EVT\_CUSTOM\_RANGE, but | |
219 | expects a member function with a wxCommandEvent argument.} | |
220 | \end{twocollist} | |
221 | ||
222 | \wxheading{Macros listed by event class} | |
223 | ||
224 | The documentation for specific event macros is organised by event class. Please refer | |
225 | to these sections for details. | |
226 | ||
227 | \twocolwidtha{8cm}% | |
228 | \begin{twocollist}\itemsep=0pt | |
229 | \twocolitem{\helpref{wxActivateEvent}{wxactivateevent}}{The EVT\_ACTIVATE and EVT\_ACTIVATE\_APP macros intercept | |
230 | activation and deactivation events.} | |
231 | \twocolitem{\helpref{wxCommandEvent}{wxcommandevent}}{A range of commonly-used control events.} | |
232 | \twocolitem{\helpref{wxCloseEvent}{wxcloseevent}}{The EVT\_CLOSE macro handles window closure | |
233 | called via \helpref{wxWindow::Close}{wxwindowclose}.} | |
234 | \twocolitem{\helpref{wxDropFilesEvent}{wxdropfilesevent}}{The EVT\_DROP\_FILES macros handles | |
235 | file drop events.} | |
236 | \twocolitem{\helpref{wxEraseEvent}{wxeraseevent}}{The EVT\_ERASE\_BACKGROUND macro is used to handle window erase requests.} | |
237 | \twocolitem{\helpref{wxFocusEvent}{wxfocusevent}}{The EVT\_SET\_FOCUS and EVT\_KILL\_FOCUS macros are used to handle keybaord focus events.} | |
238 | \twocolitem{\helpref{wxKeyEvent}{wxkeyevent}}{EVT\_CHAR and EVT\_CHAR\_HOOK macros handle keyboard | |
239 | input for any window.} | |
240 | \twocolitem{\helpref{wxIdleEvent}{wxidleevent}}{The EVT\_IDLE macro handle application idle events | |
241 | (to process background tasks, for example).} | |
242 | \twocolitem{\helpref{wxInitDialogEvent}{wxinitdialogevent}}{The EVT\_INIT\_DIALOG macro is used | |
243 | to handle dialog initialisation.} | |
244 | \twocolitem{\helpref{wxListEvent}{wxlistevent}}{These macros handle \helpref{wxListCtrl}{wxlistctrl} events.} | |
245 | \twocolitem{\helpref{wxMenuEvent}{wxmenuevent}}{These macros handle special menu events (not menu commands).} | |
246 | \twocolitem{\helpref{wxMouseEvent}{wxmouseevent}}{Mouse event macros can handle either individual | |
247 | mouse events or all mouse events.} | |
248 | \twocolitem{\helpref{wxMoveEvent}{wxmoveevent}}{The EVT\_MOVE macro is used to handle a window move.} | |
249 | \twocolitem{\helpref{wxUpdateUIEvent}{wxupdateuievent}}{The EVT\_UPDATE\_UI macro is used to handle user interface | |
250 | update pseudo-events, which are generated to give the application the chance to update the visual state of menus, | |
251 | toolbars and controls.} | |
252 | \twocolitem{\helpref{wxPaintEvent}{wxpaintevent}}{The EVT\_PAINT macro is used to handle window paint requests.} | |
253 | \twocolitem{\helpref{wxScrollEvent}{wxscrollevent}}{These macros are used to handle scroll events from | |
254 | windows, \helpref{wxScrollBar}{wxscrollbar}, and \helpref{wxSpinButton}{wxspinbutton}.} | |
255 | \twocolitem{\helpref{wxSizeEvent}{wxsizeevent}}{The EVT\_SIZE macro is used to handle a window resize.} | |
256 | \twocolitem{\helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}}{The EVT\_SYS\_COLOUR\_CHANGED macro is used to handle | |
257 | events informing the application that the user has changed the system colours (Windows only).} | |
258 | \twocolitem{\helpref{wxTreeEvent}{wxtreeevent}}{These macros handle \helpref{wxTreeCtrl}{wxtreectrl} events.} | |
259 | \end{twocollist} | |
260 |