From 04a7eed137acd6ca1f38e4bc7c0570b4035ae6c5 Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Sun, 29 Mar 2009 12:53:54 +0000 Subject: [PATCH] update documentation for Bind() (closes #10594) git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@59911 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/doxygen/overviews/eventhandling.h | 231 +++++++++++++++++-------- interface/wx/event.h | 166 ++++++++++++++++-- 2 files changed, 317 insertions(+), 80 deletions(-) diff --git a/docs/doxygen/overviews/eventhandling.h b/docs/doxygen/overviews/eventhandling.h index 9bdbd8c1a9..39abbaa3d1 100644 --- a/docs/doxygen/overviews/eventhandling.h +++ b/docs/doxygen/overviews/eventhandling.h @@ -61,23 +61,27 @@ To be more precise, each event is described by: @section overview_events_eventhandling Event Handling There are two principal ways to handle events in wxWidgets. One of them uses -event table macros and allows you to define the connection between events +event table macros and allows you to define the binding 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 the direct connection of the events of one object to a -handler method in another object. The static event tables can only handle -events in the object where they are defined so using Connect() is more flexible +one uses wxEvtHandler::Bind<>() call and can be used to bind and +unbind, the handlers dynamically, i.e. during run-time depending on some +conditions. It also allows the direct binding of events to: +@li A handler method in another object. +@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 handlers connection in one place. You can either +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_connect -for the discussion of Connect(). +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 @@ -90,7 +94,7 @@ containing the menu, so let's suppose that you need to handle some events in @c MyFrame class deriving from wxFrame. First define one or more event handlers. They -are just simple (non-virtual) methods of the class that take as a parameter a +are just simple methods of the class that take as a parameter a reference to an object of a 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 @@ -150,7 +154,7 @@ 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 by -wxFrame. The next four lines define connections of individual events to their +wxFrame. The next four lines define bindings 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 @@ -205,73 +209,59 @@ wxEvent-derived classes in the discussion of each control generating these events. -@subsection overview_events_connect Dynamic Event Handling - -As with the event tables, decide in which class you intend to -handle the events first and, as before, this class must 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 handling events in this way are rather different. +@subsection overview_events_bind Dynamic Event Handling +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 associated macros. Instead, in any place in your code, but usually in the code of the class defining the handler itself (and definitely not in the -global scope as with the event tables), call its Connect() method like this: +global scope as with the event tables), call its Bind<>() method like this: @code MyFrame::MyFrame(...) { - Connect(wxID_EXIT, wxEVT_COMMAND_MENU_SELECTED, - wxCommandEventHandler(MyFrame::OnExit)); + Bind(wxEVT_COMMAND_MENU_SELECTED, &MyFrame::OnExit, this, wxID_EXIT); } @endcode -This class should be self-explanatory except for wxCommandEventHandler part: -this is a macro that ensures that the method is of the correct type by using -static_cast in the same way as the event table macros. +Note that @c this pointer must be specified here. Now let us describe the semantic differences: