AppendixH.How wxWidgets Processes Events

Appendix H. How wxWidgets Processes Events

This appendix takes a closer look at how wxWidgets processes events, going into details omitted from the simplified view we've seen so far.

When an event is received from the windowing system, wxWidgets calls wxEvtHandler::ProcessEvent on the first event handler object belonging to the window generating the event.

Figure H-1 summarizes the order of event table searching by ProcessEvent. Here's how it works:

1.	If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled), the function skips to Step 6.
2.	If the object is a wxWindow, ProcessEvent is recursively called on the window's wxValidator. If this returns true, the function exits.
3.	SearchEventTable is called for this event handler. If this fails, the base class table is tried, the next base class table is tried, and so on, until no more tables exist or an appropriate function is found, in which case the function exits.
4.	The search is applied down the entire chain of event handlers. (Usually the chain has a length of one.) If this succeeds, the function exits.
5.	If the object is a wxWindow and the event is set to propagate (only wxCommandEvent objects are normally set to propagate), ProcessEvent is recursively applied to the parent window's event handler. If this returns true, the function exits.
6.	Finally, ProcessEvent is called on the wxApp object.

Figure H-1. Event processing flow

Pay close attention to Step 5. People often overlook or get confused by this powerful feature of the wxWidgets event processing system. To put it a different way, events set to propagate (most likely derived either directly or indirectly from wxCommandEvent) will travel up the containment hierarchy from child to parent until the maximal propagation level is reached or an event handler is found that doesn't call Skip.

When propagating command events upwards to the parent window, event propagation stops when it reaches the parent dialog, if any. This means that you don't risk getting unexpected events from dialog controls (which might be left unprocessed by the dialog itself because it doesn't care about them) when a modal dialog is popped up. The events do propagate beyond frames, however. The rationale for this choice is that a typical application has only a few frames, and their parent-child relationships are well understood by the programmer, whereas in a complex program, it may be very difficult, if not impossible, to track down all the dialogs that may be popped up (remember that some are created automatically by wxWidgets). If you need to specify a different behavior for some reason, you can use SetExtraStyle(wxWS_EX_ BLOCK_EVENTS) explicitly to prevent events from being propagated beyond the given window, or you can unset this flag for dialogs, which have it set by default.

Fundamental window events (size, motion, paint, mouse, keyboard, and so on) are sent only to the window. Events that have a higher level of meaning or that are generated by the window itselffor example, button clicks, menu selection, tree expansion, and so onare command events and are sent up to the parent to see if it is interested in the event.

Note that you might want your application to override ProcessEvent to redirect processing of events. This is done in the document-view framework, for example, to enable event handlers to be defined in the document or view. To test for command events (which will probably be the only events you want to redirect), you can use wxEvent::IsCommandEvent for efficiency instead of using the slower run-time type system.