latex/wx/tevent.tex

13 An event table is placed in an implementation file to tell wxWidgets how to map
14 events to member functions. These member functions are not virtual functions, but
29 The first two entries map menu commands to two different member functions. The
33 The EVT\_BUTTON macro demonstrates that the originating event does not have to
40 As mentioned before, the member functions that handle events do not have to be
44 functions take an event argument, and the class of event differs according to
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
80 tables you may also use \helpref{wxEvtHandler::Connect}{wxevthandlerconnect} to
81 connect the events to the handlers dynamically, during run-time. See the
89 event handler object belonging to the window generating the event.
92 very close to virtual methods in normal C++, i.e. it is possible to alter
95 For example it is possible to filter out a number of key events sent by the
96 system to a native text control by overriding wxTextCtrl and defining a
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()
100 so as to indicate that the search for the event handler should continue.
107 accepts 'a' to 'z' and 'A' to 'Z':
136 \item If the object is disabled (via a call to \helpref{wxEvtHandler::SetEvtHandlerEnabled}{wxevthandlersetevthandlerenabled})
137 the function skips to step (6).
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.
151 {\bf Pay close attention to Step 5.}  People often overlook or get
153 system.  To put it a different way, events set to propagate
156 will travel up the containment hierarchy from child to parent until the
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
169 may be very difficult, if not impossible, to track down all the dialogs which
171 automatically by wxWidgets). If you need to specify a different behaviour for
174 explicitly to prevent the events from being propagated beyond the given window
178 paint, mouse, keyboard, etc.) are sent only to the window.  Events
181 events and are sent up to the parent to see if it is interested in the
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
186 to be defined in the document or view. To test for command events (which will probably
187 be the only events you wish to redirect), you may use
191 As mentioned above, only command events are recursively applied to the parents event
193 here is a list of system events which will NOT get sent to the parent's event handler:
209 \twocolitem{\helpref{wxQueryLayoutInfoEvent}{wxquerylayoutinfoevent}}{Used to query layout information}
216 In some cases, it might be desired by the programmer to get a certain number
217 of system events in a parent window, for example all key events sent to, but not
219 will have to be written that will override ProcessEvent() in order to pass
220 all events (or any selection of them) to the parent window.
226 actions (e.g. resize of a \helpref{wxWindow}{wxwindow}) and by calls to functions
229 the user-generated events. The only {\bf exceptions} to this rule are:
249 % \subsection{Redirection of command events to the window with the focus}
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
260 % requests, so no extra coding is required to support them in your menus and
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,
269 \rtfsp\helpref{wxWindow::PushEventHandler}{wxwindowpusheventhandler}) to make this
270 event handler the object that responds to events. This way, you can avoid
272 objects as the same event handler object shouldn't be used more than once) to
273 handle events from instances of different widget classes. If you ever have to call a window's event handler
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
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
282 before restoring its behaviour to normal. So even if the application
283 has derived new classes to customize behaviour, your utility can indulge
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
289 to form a chain of event handlers, where each handler processes a different
294 \index{identifiers}\index{wxID}Window identifiers are integers, and are used to
296 for other purposes). In fact, identifiers do not need to be unique
302 If you pass {\tt wxID\_ANY} to a window constructor, an identifier will be
304 care about the exact identifier either because you're not going to process the
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,
386 to these sections for details.
397 \twocolitem{\helpref{wxEraseEvent}{wxeraseevent}}{The EVT\_ERASE\_BACKGROUND macro is used to handle window erase requests.}
398 \twocolitem{\helpref{wxFocusEvent}{wxfocusevent}}{The EVT\_SET\_FOCUS and EVT\_KILL\_FOCUS macros are used to handle keyboard focus events.}
402 (to process background tasks, for example).}
404 to handle dialog initialisation.}
409 \twocolitem{\helpref{wxMoveEvent}{wxmoveevent}}{The EVT\_MOVE macro is used to handle a window move.}
410 \twocolitem{\helpref{wxPaintEvent}{wxpaintevent}}{The EVT\_PAINT macro is used to handle window paint requests.}
411 \twocolitem{\helpref{wxScrollEvent}{wxscrollevent}}{These macros are used to handle scroll events from
414 \twocolitem{\helpref{wxSizeEvent}{wxsizeevent}}{The EVT\_SIZE macro is used to handle a window resize.}
416 and EVT\_SPLITTER\_DCLICK macros are used to handle the various splitter window events.}
417 \twocolitem{\helpref{wxSysColourChangedEvent}{wxsyscolourchangedevent}}{The EVT\_SYS\_COLOUR\_CHANGED macro is used to handle
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,
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
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
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,
454 applications where you have to give the event type ID an explicit value.
461 If you just want to use a \helpref{wxCommandEvent}{wxcommandevent} with
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}
508 \twocolitem{\windowstyle{EVT\_CUSTOM(event, id, func)}}{Allows you to add a custom event table
510 and a member function to call.}
512 but responds to a range of window identifiers.}
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
530 casts to the inherited event function. Here is an example, taken mostly