From d76259e2fbcade4da705c8106012025b3c0870fe Mon Sep 17 00:00:00 2001 From: Francesco Montorsi Date: Sun, 23 Nov 2008 19:46:43 +0000 Subject: [PATCH] many document corrections by charles; partial commit of patch #10087 git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@56945 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/doxygen/overviews/eventhandling.h | 162 ++++++++++++------------- 1 file changed, 80 insertions(+), 82 deletions(-) diff --git a/docs/doxygen/overviews/eventhandling.h b/docs/doxygen/overviews/eventhandling.h index d71bfb90c4..bcafcadddc 100644 --- a/docs/doxygen/overviews/eventhandling.h +++ b/docs/doxygen/overviews/eventhandling.h @@ -32,21 +32,21 @@ Classes: wxEvtHandler, wxWindow, wxEvent 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 -and their handlers only statically, i.e. during program compilation. The other +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 +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 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 +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 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 +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_eventhandling_connect for the discussion of Connect(). @section overview_eventhandling_eventtables Event Handling with Event Tables @@ -59,9 +59,9 @@ 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 event handlers. 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 +First define one or more event handlers. They +are just simple (non-virtual) 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 @@ -69,9 +69,9 @@ You also need to insert a macro 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 +somewhere in the class declaration. It doesn't matter where it appears but +it's customary to put it at the end because the macro changes the access +type internally so it's safest if nothing follows it. The full class declaration might look like this: @code @@ -86,23 +86,23 @@ 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 + // Notice that as the event handlers normally are not called from outside + // the class, they normally are private. In particular they don't need + // 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: + // obligation to do that; 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 +Next the event table must be defined and, as with any definition, it must be +placed in an implementation file. The event table tells wxWidgets how to map events to member functions and in our example it could look like this: @code @@ -115,11 +115,11 @@ END_EVENT_TABLE() @endcode 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. +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, so events not processed by MyFrame will, by default, be handled by 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 @@ -131,10 +131,10 @@ 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 -(but only command events, so you can't catch mouse move events in a child +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 +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. @@ -142,16 +142,16 @@ 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 +(such as button presses), wxCommandEvent is used. 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. In the simplest possible case an event handler may not use the @c event -parameter at all, e.g. +parameter at all. For example, @code -void MyFrame::OnExit(wxCommandEvent&) +void MyFrame::OnExit(wxCommandEvent& WXUNUSED(event)) { // when the user selects "Exit" from the menu we should close Close(true); @@ -177,19 +177,17 @@ events. @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 +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 this way of handling events in this way are rather -different. - +and 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 -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: +need not use @c DECLARE_EVENT_TABLE() nor @c 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: @code MyFrame::MyFrame(...) @@ -200,24 +198,24 @@ MyFrame::MyFrame(...) @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. +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. Now let us describe the semantic differences: