@li @ref overview_eventhandling_eventtables\r
@li @ref overview_eventhandling_connect\r
@li @ref overview_eventhandling_processing\r
+@li @ref overview_eventhandling_propagation\r
+@li @ref overview_eventhandling_virtual\r
@li @ref overview_eventhandling_prog\r
@li @ref overview_eventhandling_pluggable\r
@li @ref overview_eventhandling_winid\r
different.\r
\r
Let us start by looking at the syntax: the first obvious difference is that you\r
-don't need to use neither @c DECLARE_EVENT_TABLE() nor @c BEGIN_EVENT_TABLE and \r
+don't need to use neither @c DECLARE_EVENT_TABLE() nor @c BEGIN_EVENT_TABLE and\r
associated macros any more. Instead, in any place in your code, but usually in\r
the code of the class defining the handlers itself (and definitely not in the\r
global scope as with the event tables), you should call its Connect() method\r
generated the event -- and which is not the same as the frame -- via\r
wxEvent::GetEventObject() method of @c event argument passed to the\r
event handler.\r
- <li>\r
+ </li>\r
</ul>\r
\r
To summarize, using Connect() requires slightly more typing but is much more\r
\r
@section overview_eventhandling_processing How Events are Processed\r
\r
+The previous sections explain how to define event handlers but don't address\r
+the question of how exactly does wxWidgets find the handler to call for the\r
+given event. This section describes the algorithm used to do it in details.\r
+\r
When an event is received from the windowing system, wxWidgets calls\r
-wxEvtHandler::ProcessEvent on the first\r
-event handler object belonging to the window generating the event.\r
+wxEvtHandler::ProcessEvent() on the first event handler object belonging to the\r
+window generating the event. The normal order of event table searching by\r
+ProcessEvent() is as follows, with the event processing stopping as soon as a\r
+handler is found (unless the handler calls wxEvent::Skip() in which case it\r
+doesn't count as having handled the event and the search continues):\r
+<ol>\r
+ <li value="0">\r
+ Before anything else happens, wxApp::FilterEvent() is called. If it returns\r
+ anything but -1 (default), the event handling stops immediately.\r
+ </li>\r
\r
-It may be noted that wxWidgets' event processing system implements something\r
-very close to virtual methods in normal C++, i.e. it is possible to alter\r
-the behaviour of a class by overriding its event handling functions. In\r
-many cases this works even for changing the behaviour of native controls.\r
+ <li value="1">\r
+ If this event handler is disabled via a call to\r
+ wxEvtHandler::SetEvtHandlerEnabled() the next three steps are skipped and\r
+ the event handler resumes at step (5).\r
+ </li?\r
\r
-For example it is possible to filter out a number of key events sent by the\r
-system to a native text control by overriding wxTextCtrl and defining a\r
-handler for key events using EVT_KEY_DOWN. This would indeed prevent\r
-any key events from being sent to the native control - which might not be\r
-what is desired. In this case the event handler function has to call Skip()\r
-so as to indicate that the search for the event handler should continue.\r
+ <li value="2">\r
+ If the object is a wxWindow and has an associated validator, wxValidator\r
+ gets a chance to process the event.\r
+ </li>\r
\r
-To summarize, instead of explicitly calling the base class version as you\r
-would have done with C++ virtual functions (i.e. @e wxTextCtrl::OnChar()),\r
-you should instead call wxEvent::Skip.\r
+ <li value="3">\r
+ The list of dynamically connected event handlers, i.e. those for which\r
+ Connect() was called, is consulted. Notice that this is done before\r
+ checking the static event table entries, so if both a dynamic and a static\r
+ event handler match the same event, the static one is never going to be\r
+ used.\r
+ </li>\r
\r
-In practice, this would look like this if the derived text control only\r
-accepts 'a' to 'z' and 'A' to 'Z':\r
+ <li value="4">\r
+ The event table containing all the handlers defined using the event table\r
+ macros in this class and its base classes is examined. Notice that this\r
+ means that any event handler defined in a base class will be executed at\r
+ this step.\r
+ </li>\r
\r
-@code\r
-void MyTextCtrl::OnChar(wxKeyEvent& event)\r
-{\r
- if ( isalpha( event.KeyCode() ) )\r
- {\r
- // key code is within legal range. we call event.Skip() so the\r
- // event can be processed either in the base wxWidgets class\r
- // or the native control.\r
-\r
- event.Skip();\r
- }\r
- else\r
- {\r
- // illegal key hit. we don't call event.Skip() so the\r
- // event is not processed anywhere else.\r
-\r
- wxBell();\r
- }\r
-}\r
-@endcode\r
+ <li value="5">\r
+ The event is passed to the next event handler, if any, in the event handler\r
+ chain, i.e. the steps (1) to (4) are done for it. This chain can be formed\r
+ using wxEvtHandler::SetNextHandler() or wxWindow::PushEventHandler() but\r
+ usually there is no next event handler and chaining event handlers using\r
+ these functions is much less useful now that Connect() exists so this step\r
+ will almost never do anything.\r
+ </li>\r
\r
-The normal order of event table searching by ProcessEvent is as follows:\r
-<ol>\r
-<li> If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled)\r
- the function skips to step (6).\r
-<li> If the object is a wxWindow, @b ProcessEvent is recursively called on the window's\r
- wxValidator. If this returns @true, the function exits.\r
-<li> @b SearchEventTable is called for this event handler. If this fails, the base\r
- class table is tried, and so on until no more tables exist or an appropriate\r
- function was found, in which case the function exits.\r
-<li> The search is applied down the entire chain of event handlers (usually the chain has\r
- a length of one). If this succeeds, the function exits.\r
-<li> If the object is a wxWindow and the event is set to set to propagate (in the library only\r
- wxCommandEvent based events are set to propagate), @b ProcessEvent is recursively applied\r
- to the parent window's event handler. If this returns @true, the function exits.\r
-<li> Finally, @b ProcessEvent is called on the wxApp object.\r
+ <li value="6">\r
+ If the object is a wxWindow and the event is set to propagate (by default\r
+ only wxCommandEvent-derived events are set to propagate), then the\r
+ processing restarts from the step (1) (and excluding the step (7)) for the\r
+ parent window. If this object is not a window but the next handler exists,\r
+ the event is passed to its parent if it is a window. This ensures that in a\r
+ common case of (possibly several) non-window event handlers pushed on top\r
+ of a window, the event eventually reaches the window parent.\r
+ </li>\r
+\r
+ <li value="7">\r
+ Finally, i.e. if the event is still not processed, the wxApp object itself\r
+ gets a last chance to process it.\r
+ </li>\r
</ol>\r
-<b>Pay close attention to Step 5</b>. People often overlook or get\r
-confused by this powerful feature of the wxWidgets event processing\r
-system. To put it a different way, events set to propagate\r
-(see wxEvent::ShouldPropagate)\r
-(most likely derived either directly or indirectly from wxCommandEvent)\r
-will travel up the containment hierarchy from child to parent until the\r
-maximal propagation level is reached or an event handler is found that\r
-doesn't call @c event.Skip().\r
+\r
+<em>Please pay close attention to step 6!</em> People often overlook or get\r
+confused by this powerful feature of the wxWidgets event processing system. The\r
+details of event propagation upwards the window hierarchy are described in the\r
+next section.\r
+\r
+Also please notice that there are additional steps in the event handling for\r
+the windows making part of wxWidgets document-view framework, i.e.\r
+wxDocParentFrame, wxDocChildFrame and their MDI equivalents wxDocMDIParentFrame\r
+and wxDocMDIChildFrame. The parent frame classes modify the step (2) above to\r
+send the events received by them to wxDocManager object first. This object, in\r
+turn, sends the event to the current view and the view itself lets its\r
+associated document to process the event first. The child frame classes send\r
+the event directly to the associated view which still forwards it to its\r
+document object. Notice that to avoid remembering the exact order in which the\r
+events are processed in the document-view frame, the simplest, and recommended,\r
+solution is to only handle the events at the view classes level, but not in the\r
+document or document manager classes\r
+\r
+\r
+@section overview_eventhandling_propagation How Events Propagate Upwards\r
+\r
+As mentioned in the previous section, the events of the classes deriving from\r
+wxCommandEvent are propagated by default to the parent window if they are not\r
+processed in this window itself. But although by default only the command\r
+events are propagated like this, other events can be propagated as well because\r
+the event handling code uses wxEvent::ShouldPropagate() to check for whether an\r
+event should be propagated. It is also possible to propagate the event only a\r
+limited number of times and not until it is processed (or a top level parent\r
+window is reached).\r
\r
Finally, there is another additional complication (which, in fact, simplifies\r
life of wxWidgets programmers significantly): when propagating the command\r
itself, (button click, menu select, tree expand, etc.) are command\r
events and are sent up to the parent to see if it is interested in the event.\r
\r
-Note that your application may wish to override ProcessEvent to redirect processing of\r
-events. This is done in the document/view framework, for example, to allow event handlers\r
-to be defined in the document or view. To test for command events (which will probably\r
-be the only events you wish to redirect), you may use wxEvent::IsCommandEvent for efficiency,\r
-instead of using the slower run-time type system.\r
-\r
-As mentioned above, only command events are recursively applied to the parents event\r
-handler in the library itself. As this quite often causes confusion for users,\r
-here is a list of system events which will NOT get sent to the parent's event handler:\r
+As mentioned above, only command events are recursively applied to the parents\r
+event handler in the library itself. As this quite often causes confusion for\r
+users, here is a list of system events which will @em not get sent to the\r
+parent's event handler:\r
\r
@li wxEvent: The event base class\r
@li wxActivateEvent: A window or application activation event\r
all events (or any selection of them) to the parent window.\r
\r
\r
+@section overview_eventhandling_virtual Event Handlers vs Virtual Methods\r
+\r
+It may be noted that wxWidgets' event processing system implements something\r
+close to virtual methods in normal C++ in spirit: both of these mechanisms\r
+allow to alter the behaviour of the base class by defining the event handling\r
+functions in the derived classes.\r
+\r
+There is however an important difference between the two mechanisms when you\r
+want to invoke the default behaviour, as implemented by the base class, from a\r
+derived class handler. With the virtual functions, you need to call the base\r
+class function directly and you can do it either in the beginning of the\r
+derived class handler function (to post-process the event) or at its end (to\r
+pre-process the event). With the event handlers, you only have the option of\r
+pre-processing the events and in order to still let the default behaviour to\r
+happen you must call wxEvent::Skip() and @em not call the base class event\r
+handler directly. In fact, the event handler probably doesn't even exist in the\r
+base class as the default behaviour is often implemented in platform-specific\r
+code by the underlying toolkit or OS itself. But even if it does exist at\r
+wxWidgets level, it should never be called directly as the event handler are\r
+not part of wxWidgets API and should never be called directly.\r
+\r
+Finally, please notice that the event handlers themselves shouldn't be virtual.\r
+They should always be non-virtual and usually private (as there is no need to\r
+make them public) methods of a wxEvtHandler-derived class.\r
+\r
+\r
@section overview_eventhandling_prog User Generated Events vs Programmatically Generated Events\r
\r
While generically wxEvents can be generated both by user\r
Since version 2.2.x of wxWidgets, each event type is identified by ID which\r
is given to the event type @e at runtime which makes it possible to add\r
new event types to the library or application without risking ID clashes\r
-(two different event types mistakingly getting the same event ID). This\r
-event type ID is stored in a struct of type @b const wxEventType.\r
+(two different event types mistakingly getting the same event ID).\r
+This event type ID is stored in a struct of type <b>const wxEventType</b>.\r
\r
In order to define a new event type, there are principally two choices.\r
One is to define a entirely new event class (typically deriving from\r
-wxEvent or wxCommandEvent.\r
+wxEvent or wxCommandEvent).\r
\r
The other is to use the existing event classes and give them an new event\r
type. You'll have to define and declare a new event type using either way,\r
\r
@code\r
// in the header of the source file\r
-BEGIN_DECLARE_EVENT_TYPES()\r
-DECLARE_EVENT_TYPE(name, value)\r
-END_DECLARE_EVENT_TYPES()\r
+extern const wxEventType wxEVT_YOUR_EVENT_NAME;\r
\r
// in the implementation\r
-DEFINE_EVENT_TYPE(name)\r
+DEFINE_EVENT_TYPE(wxEVT_YOUR_EVENT_NAME)\r
@endcode\r
\r
-You can ignore the @e value parameter of the DECLARE_EVENT_TYPE macro\r
-since it is used only for backwards compatibility with wxWidgets 2.0.x based\r
-applications where you have to give the event type ID an explicit value.\r
See also the @ref page_samples_event for an example of code\r
defining and working with the custom event types.\r
\r
\r
@subsection overview_eventhandling_custom_existing Using Existing Event Classes\r
\r
-If you just want to use a wxCommandEvent with\r
-a new event type, you can then use one of the generic event table macros\r
-listed below, without having to define a new macro yourself. This also\r
-has the advantage that you won't have to define a new wxEvent::Clone()\r
-method for posting events between threads etc. This could look like this\r
-in your code:\r
+If you just want to use a wxCommandEvent with a new event type, you can then use\r
+one of the generic event table macros listed below, without having to define a\r
+new event class yourself. This also has the advantage that you won't have to define a\r
+new wxEvent::Clone() method for posting events between threads etc.\r
+\r
+Example:\r
\r
@code\r
-DECLARE_EVENT_TYPE(wxEVT_MY_EVENT, -1)\r
+extern const wxEventType wxEVT_MY_EVENT;\r
DEFINE_EVENT_TYPE(wxEVT_MY_EVENT)\r
\r
// user code intercepting the event\r
BEGIN_EVENT_TABLE(MyFrame, wxFrame)\r
EVT_MENU (wxID_EXIT, MyFrame::OnExit)\r
// ....\r
-EVT_COMMAND (ID_MY_WINDOW, wxEVT_MY_EVENT, MyFrame::OnMyEvent)\r
+EVT_COMMAND (ID_MY_WINDOW, wxEVT_MY_EVENT, MyFrame::OnMyEvent)\r
END_EVENT_TABLE()\r
\r
-void MyFrame::OnMyEvent( wxCommandEvent )\r
+void MyFrame::OnMyEvent( wxCommandEvent& event )\r
{\r
// do something\r
wxString text = event.GetText();\r
{\r
wxCommandEvent event( wxEVT_MY_EVENT, GetId() );\r
event.SetEventObject( this );\r
+\r
// Give it some contents\r
event.SetText( wxT("Hallo") );\r
+\r
// Send it\r
GetEventHandler()->ProcessEvent( event );\r
}\r
wxPlotCurve *m_curve;\r
};\r
\r
-DECLARE_EVENT_TYPE( wxEVT_PLOT_ACTION, -1 )\r
-\r
+extern const wxEventType wxEVT_PLOT_ACTION;\r
typedef void (wxEvtHandler::*wxPlotEventFunction)(wxPlotEvent&);\r
\r
+#define wxPlotEventHandler(func) \\r
+ (wxObjectEventFunction)(wxEventFunction)wxStaticCastEvent(wxPlotEventFunction, &func)\r
#define EVT_PLOT(id, fn) \\r
- DECLARE_EVENT_TABLE_ENTRY( wxEVT_PLOT_ACTION, id, -1, \\r
- (wxObjectEventFunction) (wxEventFunction) (wxCommandEventFunction) (wxNotifyEventFunction) \\r
- wxStaticCastEvent( wxPlotEventFunction, &fn ), (wxObject *) NULL ),\r
+ wx__DECLARE_EVT1(wxEVT_PLOT_ACTION, id, wxPlotEventHandler(fn))\r
\r
\r
// code implementing the event type and the event class\r
\r
DEFINE_EVENT_TYPE( wxEVT_PLOT_ACTION )\r
\r
-wxPlotEvent::wxPlotEvent( ...\r
+wxPlotEvent::wxPlotEvent( ... )\r
+{\r
+ ...\r
+}\r
\r
\r
// user code intercepting the event\r
@ref group_class_events "event classes group page".\r
\r
\r
-@todo for all controls state clearly when calling a member function results in an \r
- event being generated and when it doesn't (possibly updating also the \r
- 'Events generated by the user vs programmatically generated events' paragraph \r
- of the 'Event handling overview' with the list of the functions which break \r
+@todo for all controls state clearly when calling a member function results in an\r
+ event being generated and when it doesn't (possibly updating also the\r
+ 'Events generated by the user vs programmatically generated events' paragraph\r
+ of the 'Event handling overview' with the list of the functions which break\r
that rule).\r
\r
*/\r
projects / wxWidgets.git / blobdiff