]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/tevent.tex
Added first batch of docs and notes for wxPython.
[wxWidgets.git] / docs / latex / wx / tevent.tex
CommitLineData
a660d684
KB
1\section{Event handling overview}\label{eventhandlingoverview}
2
3Classes: \helpref{wxEvtHandler}{wxevthandler}, \helpref{wxWindow}{wxwindow}, \helpref{wxEvent}{wxevent}
4
5\subsection{Introduction}
6
7Before version 2.0 of wxWindows, events were handled by the application
8either by supplying callback functions, or by overriding virtual member
9functions such as {\bf OnSize}.
10
11From wxWindows 2.0, {\it event tables} are used instead, with a few exceptions.
12
13An event table is placed in an implementation file to tell wxWindows how to map
14events to member functions. These member functions are not virtual functions, but
15they all similar in form: they take a single wxEvent-derived argument, and have a void return
16type.
17
18Here's an example of an event table.
19
20\begin{verbatim}
21BEGIN_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)
26END_EVENT_TABLE()
27\end{verbatim}
28
29The first two entries map menu commands to two different member functions. The EVT\_SIZE macro
30doesn't need a window identifier, since normally you are only interested in the
31current window's size events. (In fact you could intercept a particular window's size event
32by using EVT\_CUSTOM(wxEVT\_SIZE, id, func).)
33
34The EVT\_BUTTON macro demonstrates that the originating event does not have to come from
35the window class implementing the event table - if the event source is a button within a panel within a frame, this will still
36work, because event tables are searched up through the hierarchy of windows. In this
37case, the button's event table will be searched, then the parent panel's, then the frame's.
38
39As mentioned before, the member functions that handle events do not have to be virtual.
5fc02438
RR
40Indeed, the member functions should not be virtual as the event handler ignores that
41the functions are virtual, i.e. overriding a virtual member function in a derived class
42will not have any effect.
a660d684
KB
43These member functions take an event argument, and the class of event differs according
44to the type of event and the class of the originating window. For size
45events, \helpref{wxSizeEvent}{wxsizeevent} is used. For menu commands and most control
46commands (such as button presses), \helpref{wxCommandEvent}{wxcommandevent} is used.
47When controls get more complicated, then specific event classes are used, such
48as \helpref{wxTreeEvent}{wxtreeevent} for events from \helpref{wxTreeCtrl}{wxtreectrl} windows.
49
50As well as the event table in the implementation file, there must be a DECLARE\_EVENT\_TABLE
51macro in the class definition. For example:
52
53{\small%
54\begin{verbatim}
55class MyFrame: public wxFrame {
56
57 DECLARE_DYNAMIC_CLASS(MyFrame)
58
59public:
60 ...
61 void OnExit(wxCommandEvent& event);
62 void OnSize(wxSizeEvent& event);
63protected:
64 int m_count;
65 ...
66 DECLARE_EVENT_TABLE()
67};
68\end{verbatim}
69}%
70
71\subsection{How events are processed}\label{eventprocessing}
72
73When an event is received from the windowing system, wxWindows calls \helpref{wxEvtHandler::ProcessEvent}{wxevthandlerprocessevent} on
74the first event handler object belonging to the window generating the event.
75
5fc02438
RR
76It may be noted that wxWindows' event processing system implements something
77very close to virtual methods in normal C++, i.e. it is possible to alter
78the behaviour of a class by overriding its event handling functions. In
79many cases this works even for changing the behaviour of native controls.
1f112209 80For example it is possible to filter out a number of key events sent by the
5fc02438 81system to a native text control by overriding wxTextCtrl and defining a
1f112209 82handler for key events using EVT\_KEY\_DOWN. This would indeed prevent
5fc02438
RR
83any key events from being sent to the native control - which might not be
84what is desired. In this case the event handler function has to call Skip()
85so as to indicate that it did NOT handle the event at all.
86
87In practice, this would look like this if the derived text control only
88accepts 'a' to 'z' and 'A' to 'Z':
89
90{\small%
91\begin{verbatim}
92void 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}
5fc02438
RR
110\end{verbatim}
111}%
112
113
a660d684
KB
114The normal order of event table searching by ProcessEvent is as follows:
115
116\begin{enumerate}\itemsep=0pt
117\item If the object is disabled (via a call to \helpref{wxEvtHandler::SetEvtHandlerEnabled}{wxevthandlersetevthandlerenabled})
118the function skips to step (6).
119\item If the object is a wxWindow, {\bf ProcessEvent} is recursively called on the window's\rtfsp
120\helpref{wxValidator}{wxvalidator}. If this returns TRUE, the function exits.
121\item {\bf SearchEventTable} is called for this event handler. If this fails, the base
122class table is tried, and so on until no more tables exist or an appropriate function was found,
123in which case the function exits.
124\item The search is applied down the entire chain of event handlers (usually the chain has a length
125of one). If this succeeds, the function exits.
126\item If the object is a wxWindow and the event is a wxCommandEvent, {\bf ProcessEvent} is
127recursively applied to the parent window's event handler. If this returns TRUE, the function exits.
128\item Finally, {\bf ProcessEvent} is called on the wxApp object.
129\end{enumerate}
130
131Note that your application may wish to override ProcessEvent to redirect processing of
132events. This is done in the document/view framework, for example, to allow event handlers
133to be defined in the document or view.
134
5fc02438
RR
135As mentioned above, only command events are recursively applied to the parents event
136handler. As this quite often causes confusion for users, here is a list of system
137events which will NOT get sent to the parent's event handler:
138
139\begin{twocollist}\itemsep=0pt
140\twocolitem{\helpref{wxEvent}{wxevent}}{The event base class}
141\twocolitem{\helpref{wxActivateEvent}{wxactivateevent}}{A window or application activation event}
142\twocolitem{\helpref{wxCloseEvent}{wxcloseevent}}{A close window or end session event}
143\twocolitem{\helpref{wxEraseEvent}{wxeraseevent}}{An erase background event}
144\twocolitem{\helpref{wxFocusEvent}{wxfocusevent}}{A window focus event}
145\twocolitem{\helpref{wxKeyEvent}{wxkeyevent}}{A keypress event}
146\twocolitem{\helpref{wxIdleEvent}{wxidleevent}}{An idle event}
147\twocolitem{\helpref{wxInitDialogEvent}{wxinitdialogevent}}{A dialog initialisation event}
148\twocolitem{\helpref{wxJoystickEvent}{wxjoystickevent}}{A joystick event}
149\twocolitem{\helpref{wxMenuEvent}{wxmenuevent}}{A menu event}
150\twocolitem{\helpref{wxMouseEvent}{wxmouseevent}}{A mouse event}
151\twocolitem{\helpref{wxMoveEvent}{wxmoveevent}}{A move event}
152\twocolitem{\helpref{wxPaintEvent}{wxpaintevent}}{A paint event}
153\twocolitem{\helpref{wxQueryLayoutInfoEvent}{wxquerylayoutinfoevent}}{Used to query layout information}
154\twocolitem{\helpref{wxSizeEvent}{wxsizeevent}}{A size event}
155\twocolitem{\helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}}{A system colour change event}
156\twocolitem{\helpref{wxUpdateUIEvent}{wxupdateuievent}}{A user interface update event}
157\end{twocollist}
158
159In some cases, it might be desired by the programmer to get a certain number
1f112209 160of system events in a parent window, for example all key events sent to, but not
5fc02438
RR
161used by, the native controls in a dialog. In this case, a special event handler
162will have to be written that will override ProcessEvent() in order to pass
163all events (or any selection of them) to the parent window. See next section.
164
a660d684
KB
165\subsection{Pluggable event handlers}
166
167In fact, you don't have to derive a new class from a window class
168if you don't want to. You can derive a new class from wxEvtHandler instead,
169defining the appropriate event table, and then call
170\rtfsp\helpref{wxWindow::SetEventHandler}{wxwindowseteventhandler} (or, preferably,
171\rtfsp\helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler}) to make this
172event handler the object that responds to events. This way, you can avoid
173a lot of class derivation, and use the same event handler object to
174handle events from instances of different classes. If you ever have to call a window's event handler
175manually, use the GetEventHandler function to retrieve the window's event handler and use that
176to call the member function. By default, GetEventHandler returns a pointer to the window itself
177unless an application has redirected event handling using SetEventHandler or PushEventHandler.
178
179One use of PushEventHandler is to temporarily or permanently change the
180behaviour of the GUI. For example, you might want to invoke a dialog editor
181in your application that changes aspects of dialog boxes. You can
182grab all the input for an existing dialog box, and edit it `in situ',
183before restoring its behaviour to normal. So even if the application
184has derived new classes to customize behaviour, your utility can indulge
185in a spot of body-snatching. It could be a useful technique for on-line
186tutorials, too, where you take a user through a serious of steps and
187don't want them to diverge from the lesson. Here, you can examine the events
188coming from buttons and windows, and if acceptable, pass them through to
189the original event handler. Use PushEventHandler/PopEventHandler
190to form a chain of event handlers, where each handler processes a different
191range of events independently from the other handlers.
192
1f112209 193\subsection{Window identifiers}\label{windowids}
a660d684 194
1f112209
JS
195\index{identifiers}\index{wxID}Window identifiers are integers, and are used to uniquely determine window identity in the
196event system (though you can use it for other purposes). In fact, identifiers do not need
197to be unique across your entire application just so long as they are unique within a particular context you're interested
198in, such as a frame and its children. You may use the wxID\_OK identifier, for example, on
199any number of dialogs so long as you don't have several within the same dialog.
a660d684 200
1f112209
JS
201If you pass -1 to a window constructor, an identifier will be generated for you, but beware:
202if things don't respond in the way they should, it could be because of an id conflict. It's safer
203to supply window ids at all times. Automatic generation of identifiers starts at 1 so may well conflict
204with your own identifiers.
205
206The following standard identifiers are supplied. You can use wxID\_HIGHEST to determine the
207number above which it is safe to define your own identifiers. Or, you can use identifiers below
208wxID\_LOWEST.
209
210\begin{verbatim}
211#define wxID_LOWEST 4999
212
213#define wxID_OPEN 5000
214#define wxID_CLOSE 5001
215#define wxID_NEW 5002
216#define wxID_SAVE 5003
217#define wxID_SAVEAS 5004
218#define wxID_REVERT 5005
219#define wxID_EXIT 5006
220#define wxID_UNDO 5007
221#define wxID_REDO 5008
222#define wxID_HELP 5009
223#define wxID_PRINT 5010
224#define wxID_PRINT_SETUP 5011
225#define wxID_PREVIEW 5012
226#define wxID_ABOUT 5013
227#define wxID_HELP_CONTENTS 5014
228#define wxID_HELP_COMMANDS 5015
229#define wxID_HELP_PROCEDURES 5016
230#define wxID_HELP_CONTEXT 5017
231
232#define wxID_CUT 5030
233#define wxID_COPY 5031
234#define wxID_PASTE 5032
235#define wxID_CLEAR 5033
236#define wxID_FIND 5034
237#define wxID_DUPLICATE 5035
238#define wxID_SELECTALL 5036
239
240#define wxID_FILE1 5050
241#define wxID_FILE2 5051
242#define wxID_FILE3 5052
243#define wxID_FILE4 5053
244#define wxID_FILE5 5054
245#define wxID_FILE6 5055
246#define wxID_FILE7 5056
247#define wxID_FILE8 5057
248#define wxID_FILE9 5058
249
250#define wxID_OK 5100
251#define wxID_CANCEL 5101
252#define wxID_APPLY 5102
253#define wxID_YES 5103
254#define wxID_NO 5104
255#define wxID_STATIC 5105
256
257#define wxID_HIGHEST 5999
258\end{verbatim}
259
260\subsection{Event macros summary}\label{eventmacros}
a660d684
KB
261
262\wxheading{Generic event table macros}
263
264\twocolwidtha{8cm}%
265\begin{twocollist}\itemsep=0pt
1f112209 266\twocolitem{\windowstyle{EVT\_CUSTOM(event, id, func)}}{Allows you to add a custom event table
a660d684
KB
267entry by specifying the event identifier (such as wxEVT\_SIZE), the window identifier,
268and a member function to call.}
1f112209 269\twocolitem{\windowstyle{EVT\_CUSTOM\_RANGE(event, id1, id2, func)}}{The same as EVT\_CUSTOM,
a660d684 270but responds to a range of window identifiers.}
1f112209 271\twocolitem{\windowstyle{EVT\_COMMAND(id, event, func)}}{The same as EVT\_CUSTOM, but
a660d684 272expects a member function with a wxCommandEvent argument.}
1f112209 273\twocolitem{\windowstyle{EVT\_COMMAND\_RANGE(id1, id2, event, func)}}{The same as EVT\_CUSTOM\_RANGE, but
a660d684
KB
274expects a member function with a wxCommandEvent argument.}
275\end{twocollist}
276
277\wxheading{Macros listed by event class}
278
279The documentation for specific event macros is organised by event class. Please refer
280to these sections for details.
281
282\twocolwidtha{8cm}%
283\begin{twocollist}\itemsep=0pt
284\twocolitem{\helpref{wxActivateEvent}{wxactivateevent}}{The EVT\_ACTIVATE and EVT\_ACTIVATE\_APP macros intercept
285activation and deactivation events.}
286\twocolitem{\helpref{wxCommandEvent}{wxcommandevent}}{A range of commonly-used control events.}
287\twocolitem{\helpref{wxCloseEvent}{wxcloseevent}}{The EVT\_CLOSE macro handles window closure
288called via \helpref{wxWindow::Close}{wxwindowclose}.}
289\twocolitem{\helpref{wxDropFilesEvent}{wxdropfilesevent}}{The EVT\_DROP\_FILES macros handles
290file drop events.}
291\twocolitem{\helpref{wxEraseEvent}{wxeraseevent}}{The EVT\_ERASE\_BACKGROUND macro is used to handle window erase requests.}
292\twocolitem{\helpref{wxFocusEvent}{wxfocusevent}}{The EVT\_SET\_FOCUS and EVT\_KILL\_FOCUS macros are used to handle keybaord focus events.}
293\twocolitem{\helpref{wxKeyEvent}{wxkeyevent}}{EVT\_CHAR and EVT\_CHAR\_HOOK macros handle keyboard
294input for any window.}
295\twocolitem{\helpref{wxIdleEvent}{wxidleevent}}{The EVT\_IDLE macro handle application idle events
296(to process background tasks, for example).}
297\twocolitem{\helpref{wxInitDialogEvent}{wxinitdialogevent}}{The EVT\_INIT\_DIALOG macro is used
298to handle dialog initialisation.}
299\twocolitem{\helpref{wxListEvent}{wxlistevent}}{These macros handle \helpref{wxListCtrl}{wxlistctrl} events.}
300\twocolitem{\helpref{wxMenuEvent}{wxmenuevent}}{These macros handle special menu events (not menu commands).}
301\twocolitem{\helpref{wxMouseEvent}{wxmouseevent}}{Mouse event macros can handle either individual
302mouse events or all mouse events.}
303\twocolitem{\helpref{wxMoveEvent}{wxmoveevent}}{The EVT\_MOVE macro is used to handle a window move.}
304\twocolitem{\helpref{wxUpdateUIEvent}{wxupdateuievent}}{The EVT\_UPDATE\_UI macro is used to handle user interface
305update pseudo-events, which are generated to give the application the chance to update the visual state of menus,
306toolbars and controls.}
307\twocolitem{\helpref{wxPaintEvent}{wxpaintevent}}{The EVT\_PAINT macro is used to handle window paint requests.}
308\twocolitem{\helpref{wxScrollEvent}{wxscrollevent}}{These macros are used to handle scroll events from
309windows, \helpref{wxScrollBar}{wxscrollbar}, and \helpref{wxSpinButton}{wxspinbutton}.}
310\twocolitem{\helpref{wxSizeEvent}{wxsizeevent}}{The EVT\_SIZE macro is used to handle a window resize.}
311\twocolitem{\helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}}{The EVT\_SYS\_COLOUR\_CHANGED macro is used to handle
312events informing the application that the user has changed the system colours (Windows only).}
313\twocolitem{\helpref{wxTreeEvent}{wxtreeevent}}{These macros handle \helpref{wxTreeCtrl}{wxtreectrl} events.}
314\end{twocollist}
315