@li An ordinary function like a static method or a global function.
@li An arbitrary functor like boost::function<>.
-The static event tables can only handle
-events in the object where they are defined so using Bind<>() is more flexible
-than using the event tables. On the other hand, event tables are more succinct
-and centralize all event handler bindings in one place. You can either
-choose a single approach that you find preferable or freely combine both
-methods in your program in different classes or even in one and the same class,
-although this is probably sufficiently confusing to be a bad idea.
-
-But before you make this choice, let us discuss these two ways in more
-detail. In the next section we provide a short introduction to handling the
-events using the event tables. Please see @ref overview_events_bind
-for the discussion of Bind<>().
+The static event tables can only handle events in the object where they are
+defined so using Bind<>() is more flexible than using the event tables. On the
+other hand, event tables are more succinct and centralize all event handler
+bindings in one place. You can either choose a single approach that you find
+preferable or freely combine both methods in your program in different classes
+or even in one and the same class, although this is probably sufficiently
+confusing to be a bad idea.
+
+Also notice that most of the existing wxWidgets tutorials and discussions use
+the event tables because they historically preceded the apparition of dynamic
+event handling in wxWidgets. But this absolutely doesn't mean that using the
+event tables is the preferred way: handling events dynamically is better in
+several aspects and you should strongly consider doing it if you are just
+starting with wxWidgets. On the other hand, you still need to know about the
+event tables if only because you are going to see them in many samples and
+examples.
+
+So before you make the choice between static event tables and dynamically
+connecting the event handlers, let us discuss these two ways in more detail. In
+the next section we provide a short introduction to handling the events using
+the event tables. Please see @ref overview_events_bind for the discussion of
+Bind<>().
@subsection overview_events_eventtables Event Handling with Event Tables
@subsection overview_events_bind Dynamic Event Handling
+@see @ref overview_cpp_rtti_disabled
+
The possibilities of handling events in this way are rather different.
Let us start by looking at the syntax: the first obvious difference is that you
need not use DECLARE_EVENT_TABLE() nor BEGIN_EVENT_TABLE() and the
</li>
</ul>
-Here are some more examples of how to use different event handlers.
+Let us now look at more examples of how to use different event handlers using
+the two overloads of Bind() function: first one for the object methods and the
+other one for arbitrary functors (callable objects, including simple functions):
-You can use a method from a completely different object as an event handler:
+In addition to using a method of the object generating the event itself, you
+can use a method from a completely different object as an event handler:
@code
void MyFrameHandler::OnFrameExit( wxCommandEvent & )
that of @c MyFrame object -- or at least it needs to be unbound before being
destroyed.
+
To use an ordinary function or a static method as an event handler you would
write something like this:
The previous sections explain how to define event handlers but don't address
the question of how exactly wxWidgets finds the handler to call for the
-given event. This section describes the algorithm used in detail.
+given event. This section describes the algorithm used in detail. Notice that
+you may want to run the @ref page_samples_event while reading this section and
+look at its code and the output when the button which can be used to test the
+event handlers execution order is clicked to understand it better.
When an event is received from the windowing system, wxWidgets calls
wxEvtHandler::ProcessEvent() on the first event handler object belonging to the
</li>
<li value="3">
- The list of dynamically bind event handlers, i.e., those for which
+ The list of dynamically bound event handlers, i.e., those for which
Bind<>() was called, is consulted. Notice that this is done before
checking the static event table entries, so if both a dynamic and a static
event handler match the same event, the static one is never going to be
- used.
+ used unless wxEvent::Skip() is called in the dynamic one.
</li>
<li value="4">
<li value="5">
The event is passed to the next event handler, if any, in the event handler
- chain, i.e., the steps (1) to (4) are done for it. This chain can be formed
- using wxEvtHandler::SetNextHandler():
- @image html overview_events_chain.png
- (referring to the image, if @c A->ProcessEvent is called and it doesn't handle
- the event, @c B->ProcessEvent will be called and so on...).
- In the case of wxWindow you can build a stack (implemented using wxEvtHandler
- double-linked list) using wxWindow::PushEventHandler():
- @image html overview_events_winstack.png
- (referring to the image, if @c W->ProcessEvent is called, it immediately calls
- @c A->ProcessEvent; if nor @c A nor @c B handle the event, then the wxWindow
- itself is used - i.e. the dynamically bind event handlers and static
- event table entries of wxWindow are looked as the last possibility, after
- all pushed event handlers were tested).
- Note however that usually there are no wxEvtHandler chains nor wxWindows stacks
- so this step will usually do anything.
+ chain, i.e., the steps (1) to (4) are done for it. Usually there is no next
+ event handler so the control passes to the next step but see @ref
+ overview_events_nexthandler for how the next handler may be defined.
</li>
<li value="6">
all events (or any selection of them) to the parent window.
+@subsection overview_events_nexthandler Event Handlers Chain
+
+The step 4 of the event propagation algorithm checks for the next handler in
+the event handler chain. This chain can be formed using
+wxEvtHandler::SetNextHandler():
+ @image html overview_events_chain.png
+(referring to the image, if @c A->ProcessEvent is called and it doesn't handle
+ the event, @c B->ProcessEvent will be called and so on...).
+
+Additionally, in the case of wxWindow you can build a stack (implemented using
+wxEvtHandler double-linked list) using wxWindow::PushEventHandler():
+ @image html overview_events_winstack.png
+(referring to the image, if @c W->ProcessEvent is called, it immediately calls
+ @c A->ProcessEvent; if nor @c A nor @c B handle the event, then the wxWindow
+itself is used -- i.e. the dynamically bind event handlers and static event
+table entries of wxWindow are looked as the last possibility, after all pushed
+event handlers were tested).
+
+By default the chain is empty, i.e. there is no next handler.
+
+
@section overview_events_custom Custom Event Summary
@subsection overview_events_custom_general General approach
projects / wxWidgets.git / blobdiff