Classes: wxEvtHandler, wxWindow, wxEvent
@li @ref overview_eventhandling_introduction
+@li @ref overview_eventhandling_eventtables
+@li @ref overview_eventhandling_connect
@li @ref overview_eventhandling_processing
@li @ref overview_eventhandling_prog
@li @ref overview_eventhandling_pluggable
@section overview_eventhandling_introduction Introduction
-Before version 2.0 of wxWidgets, events were handled by the application
-either by supplying callback functions, or by overriding virtual member
-functions such as @b OnSize.
+There are two principal ways to handle events in wxWidgets. One of them uses
+<em>event table</em> macros and allows to define the connection between events
+and their handlers only statically, i.e. during program compilation. The other
+one uses wxEvtHandler::Connect() call and can be used to connect, and
+disconnect, the handlers dynamically, i.e. during run-time depending on some
+conditions. It also allows directly connecting the events of one object to a
+handler method in another object while the static event tables can only handle
+events in the object where they are defined so using Connect() is more flexible
+than using the event tables. On the other hand, event tables are more succinct
+and centralize all event handlers connection in one place. You can either
+choose a single approach which 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 some more
+details: in the next section we provide a short introduction to handling the
+events using the event tables, please see @ref overview_eventhandling_connect
+for the discussion of Connect().
+
+@section overview_eventhandling_eventtables Event Handling with Event Tables
+
+To use an <em>event table</em> you must first decide in which class you wish to
+handle the events. The only requirement imposed by wxWidgets is that this class
+must derive from wxEvtHandler and so, considering that wxWindow derives from
+it, any classes representing windows can handle events. Simple events such as
+menu commands are usually processed at the level of a top-level window
+containing the menu, so let's suppose that you need to handle some events in @c
+MyFrame class deriving from wxFrame.
+
+First thing to do is to define one or more <em>event handlers</em>. They
+are just simple (non-virtual) methods of the class which take as a parameter a
+reference to an object of wxEvent-derived class and have no return value (any
+return information is passed via the argument, which is why it is non-const).
+You also need to insert a macro
-From wxWidgets 2.0, @e event tables are used instead, with a few exceptions.
-An event table is placed in an implementation file to tell wxWidgets how to map
-events to member functions. These member functions are not virtual functions, but
-they are all similar in form: they take a single wxEvent-derived argument,
-and have a void return type.
-Here's an example of an event table.
+@code
+DECLARE_EVENT_TABLE()
+@endcode
+
+somewhere in the class declaration. It doesn't matter where does it occur but
+it's customary to put it at the end of it because the macro changes the access
+type internally and so it's safest if there is nothing that follows it. So the
+full class declaration might look like this:
+
+@code
+class MyFrame : public wxFrame
+{
+public:
+ MyFrame(...) : wxFrame(...) { }
+
+ ...
+
+protected:
+ int m_whatever;
+
+private:
+ // notice that as the event handlers normally are not called from outside
+ // the class, they normally be private, in particular they don't need at
+ // all to be public
+ void OnExit(wxCommandEvent& event);
+ void OnButton1(wxCommandEvent& event);
+ void OnSize(wxSizeEvent& event);
+
+ // it's common to call the event handlers OnSomething() but there is no
+ // obligation to it, this one is an event handler too:
+ void DoTest(wxCommandEvent& event);
+
+ DECLARE_EVENT_TABLE()
+};
+@endcode
+
+Next the event table must be defined and, as any definition, it must be placed
+in an implementation file to tell. The event table tells wxWidgets how to map
+events to member functions and in our example it could look like this:
@code
BEGIN_EVENT_TABLE(MyFrame, wxFrame)
-EVT_MENU(wxID_EXIT, MyFrame::OnExit)
-EVT_MENU(DO_TEST, MyFrame::DoTest)
-EVT_SIZE(MyFrame::OnSize)
-EVT_BUTTON(BUTTON1, MyFrame::OnButton1)
+ EVT_MENU(wxID_EXIT, MyFrame::OnExit)
+ EVT_MENU(DO_TEST, MyFrame::DoTest)
+ EVT_SIZE(MyFrame::OnSize)
+ EVT_BUTTON(BUTTON1, MyFrame::OnButton1)
END_EVENT_TABLE()
@endcode
-The first two entries map menu commands to two different member functions. The
-EVT_SIZE macro doesn't need a window identifier, since normally you are only
-interested in the current window's size events.
+Notice that you must mention a method you want to use for the event handling in
+the event table definition, just defining it in MyFrame class is @e not enough.
+
+Let us now look at the details of this definition: the first line means that we
+are defining the event table for MyFrame class and that its base class is
+wxFrame, so events not processed by MyFrame will, by default, be handled to
+wxFrame. The next four lines define connections of individual events to their
+handlers: the first two of them map menu commands from the items with the
+identifiers specified as the first macro parameter to two different member
+functions. In the next one, @c EVT_SIZE means that any changes in the size of
+the frame will result in calling OnSize() method. Note that this macro doesn't
+need a window identifier, since normally you are only interested in the current
+window's size events.
The EVT_BUTTON macro demonstrates that the originating event does not have to
come from the window class implementing the event table -- if the event source
is a button within a panel within a frame, this will still work, because event
-tables are searched up through the hierarchy of windows for the command events.
-In this case, the button's event table will be searched, then the parent
-panel's, then the frame's.
-
-As mentioned before, the member functions that handle events do not have to be
-virtual. Indeed, the member functions should not be virtual as the event
-handler ignores that the functions are virtual, i.e. overriding a virtual
-member function in a derived class will not have any effect. These member
-functions take an event argument, and the class of event differs according to
-the type of event and the class of the originating window. For size events,
-wxSizeEvent is used. For menu commands and most control commands
-(such as button presses), wxCommandEvent is used. When controls get more
-complicated, then specific event classes are used, such as wxTreeEvent for
+tables are searched up through the hierarchy of windows for the command events
+(but only command events, so you can't catch mouse move events in a child
+control in the parent window in the same way because wxMouseEvent doesn't
+derive from wxCommandEvent, see below for how you can do it). In this case, the
+button's event table will be searched, then the parent panel's, then the
+frame's.
+
+Finally, you need to implement the event handlers. As mentioned before, all
+event handlers take a wxEvent-derived argument whose exact class differs
+according to the type of event and the class of the originating window. For
+size events, wxSizeEvent is used. For menu commands and most control commands
+(such as button presses), wxCommandEvent is used. And when controls get more
+complicated, more specific wxCommandEvent-derived event classes providing
+additional control-specific information can be used, such as wxTreeEvent for
events from wxTreeCtrl windows.
-As well as the event table in the implementation file, there must also be a
-DECLARE_EVENT_TABLE macro somewhere in the class declaration. For example:
+In the simplest possible case an event handler may not use the @c event
+parameter at all, e.g.
@code
-class MyFrame : public wxFrame
+void MyFrame::OnExit(wxCommandEvent&)
{
-public:
-...
-void OnExit(wxCommandEvent& event);
-void OnSize(wxSizeEvent& event);
+ // when the user selects "Exit" from the menu we should close
+ Close(true);
+}
+@endcode
-protected:
-int m_count;
-...
+In other cases you may need some information carried by the @c event argument,
+as in:
-DECLARE_EVENT_TABLE()
-};
+@code
+void MyFrame::OnSize(wxSizeEvent& event)
+{
+ wxSize size = event.GetSize();
+
+ ... update the frame using the new size ...
+}
@endcode
-Note that this macro may occur in any section of the class (public, protected
-or private) but that it is probably better to insert it at the end, as shown,
-because this macro implicitly changes the access to protected which may be
-quite unexpected if there is anything following it.
+You will find the details about the event table macros and the corresponding
+wxEvent-derived classes in the discussion of each control generating these
+events.
-Finally, if you don't like using macros for static initialization of the event
-tables you may also use wxEvtHandler::Connect to
-connect the events to the handlers dynamically, during run-time. See the
-@ref page_samples_event for an example of doing it.
+@section overview_eventhandling_connect Dynamic Event Handling
+As with the event tables, you need to decide in which class do you intend to
+handle the events first and, also as before, this class must still derive from
+wxEvtHandler (usually indirectly via wxWindow), see the declaration of MyFrame
+in the previous section. However the similarities end here and both the syntax
+and the possibilities of this way of handling events in this way are rather
+different.
-@section overview_eventhandling_processing How events are processed
+Let us start by looking at the syntax: the first obvious difference is that you
+don't need to use neither @c DECLARE_EVENT_TABLE() nor @c BEGIN_EVENT_TABLE and
+associated macros any more. Instead, in any place in your code, but usually in
+the code of the class defining the handlers itself (and definitely not in the
+global scope as with the event tables), you should call its Connect() method
+like this:
+
+@code
+MyFrame::MyFrame(...)
+{
+ Connect(wxID_EXIT, wxEVT_COMMAND_MENU_SELECTED,
+ wxCommandEventHandler(MyFrame::OnExit));
+}
+@endcode
+
+This class should be self-explanatory except for wxCommandEventHandler part:
+this is a macro which ensures that the method is of correct type by using
+static_cast in the same way as event table macros do it inside them.
+
+Now let us describe the semantic differences:
+<ul>
+ <li>
+ Event handlers can be connected at any moment, e.g. it's possible to do
+ some initialization first and only connect the handlers if and when it
+ succeeds. This can avoid the need to test that the object was properly
+ initialized in the event handlers themselves: with Connect() they
+ simply won't be called at all if it wasn't.
+ </li>
+
+ <li>
+ As a slight extension of the above, the handlers can also be
+ Disconnect()-ed at any time. And maybe later reconnected again. Of
+ course, it's also possible to emulate this behaviour with the classic
+ static (i.e. connected via event tables) handlers by using an internal
+ flag indicating whether the handler is currently enabled and returning
+ from it if it isn't, but using dynamically connected handlers requires
+ less code and is also usually more clear.
+ </li>
+
+ <li>
+ Also notice that you must derive a class inherited from, say,
+ wxTextCtrl even if you don't want to modify the control behaviour at
+ all but just want to handle some of its events. This is especially
+ inconvenient when the control is loaded from the XRC. Connecting the
+ event handler dynamically bypasses the need for this unwanted
+ sub-classing.
+ </li>
+
+ <li>
+ Last but very, very far from least is the possibility to connect an
+ event of some object to a method of another object. This is impossible
+ to do with event tables because there is no possibility to specify the
+ object to dispatch the event to so it necessarily needs to be sent to
+ the same object which generated the event. Not so with Connect() which
+ has an optional @c eventSink parameter which can be used to specify the
+ object which will handle the event. Of course, in this case the method
+ being connected must belong to the class which is the type of the
+ @c eventSink object! To give a quick example, people often want to catch
+ mouse movement events happening when the mouse is in one of the frame
+ children in the frame itself. Doing it in a naive way doesn't work:
+ <ul>
+ <li>
+ A @c EVT_LEAVE_WINDOW(MyFrame::OnMouseLeave) line in the frame
+ event table has no effect as mouse move (including entering and
+ leaving) events are not propagated upwards to the parent window
+ (at least not by default).
+ </li>
+
+ <li>
+ Putting the same line in a child event table will crash during
+ run-time because the MyFrame method will be called on a wrong
+ object -- it's easy to convince oneself that the only object
+ which can be used here is the pointer to the child, as
+ wxWidgets has nothing else. But calling a frame method with the
+ child window pointer instead of the pointer to the frame is, of
+ course, disastrous.
+ </li>
+ </ul>
+
+ However writing
+ @code
+ MyFrame::MyFrame(...)
+ {
+ m_child->Connect(wxID_ANY, wxEVT_LEAVE_WINDOW,
+ wxMouseEventHandler(MyFrame::OnMouseLeave),
+ NULL, // unused extra data parameter
+ this); // this indicates the object to connect to
+ }
+ @endcode
+ will work exactly as expected. Note that you can get the object which
+ generated the event -- and which is not the same as the frame -- via
+ wxEvent::GetEventObject() method of @c event argument passed to the
+ event handler.
+ <li>
+</ul>
+
+To summarize, using Connect() requires slightly more typing but is much more
+flexible than using static event tables so don't hesitate to use it when you
+need this extra power. On the other hand, event tables are still perfectly fine
+in simple situations where this extra flexibility is not needed.
+
+
+@section overview_eventhandling_processing How Events are Processed
When an event is received from the windowing system, wxWidgets calls
wxEvtHandler::ProcessEvent on the first
all events (or any selection of them) to the parent window.
-@section overview_eventhandling_prog Events generated by the user vs programmatically generated events
+@section overview_eventhandling_prog User Generated Events vs Programmatically Generated Events
While generically wxEvents can be generated both by user
actions (e.g. resize of a wxWindow) and by calls to functions
-@section overview_eventhandling_pluggable Pluggable event handlers
+@section overview_eventhandling_pluggable Pluggable Event Handlers
In fact, you don't have to derive a new class from a window class
if you don't want to. You can derive a new class from wxEvtHandler instead,
-@section overview_eventhandling_winid Window identifiers
+@section overview_eventhandling_winid Window Identifiers
Window identifiers are integers, and are used to
uniquely determine window identity in the event system (though you can use it
the your identifiers don't conflict accidentally.
-@section overview_eventhandling_custom Custom event summary
+@section overview_eventhandling_custom Custom Event Summary
@subsection overview_eventhandling_custom_general General approach
defining and working with the custom event types.
-@subsection overview_eventhandling_custom_existing Using existing event classes
+@subsection overview_eventhandling_custom_existing Using Existing Event Classes
If you just want to use a wxCommandEvent with
a new event type, you can then use one of the generic event table macros
@endcode
-@subsection overview_eventhandling_custom_generic Generic event table macros
+@subsection overview_eventhandling_custom_generic Generic Event Table Macros
@beginTable
@row2col{EVT_CUSTOM(event\, id\, func),
@endTable
-@subsection overview_eventhandling_custom_ownclass Defining your own event class
+@subsection overview_eventhandling_custom_ownclass Defining Your Own Event Class
Under certain circumstances, it will be required to define your own event
class e.g. for sending more complex data from one place to another. Apart
@endcode
+@section overview_eventhandling_macros Event Handling Summary
+For the full list of event classes, please see the
+@ref group_class_events "event classes group page".
-@section overview_eventhandling_macros Event macros summary
-For the full list of event classes, please see the
-@ref page_class_cat_events page.
+@todo for all controls state clearly when calling a member function results in an
+ event being generated and when it doesn't (possibly updating also the
+ 'Events generated by the user vs programmatically generated events' paragraph
+ of the 'Event handling overview' with the list of the functions which break
+ that rule).
*/
projects / wxWidgets.git / blobdiff