]> git.saurik.com Git - wxWidgets.git/blobdiff - docs/doxygen/overviews/eventhandling.h
Implement hatched/stippled pens/brushes in wxGraphicsContext for Cairo.
[wxWidgets.git] / docs / doxygen / overviews / eventhandling.h
index f4ecda8f888844fe009e989b4515dbb0b9e07446..10a1c6543ac21bea1a86572412156fe4916063a9 100644 (file)
-/////////////////////////////////////////////////////////////////////////////\r
-// Name:        eventhandling.h\r
-// Purpose:     topic overview\r
-// Author:      wxWidgets team\r
-// RCS-ID:      $Id$\r
-// Licence:     wxWindows license\r
-/////////////////////////////////////////////////////////////////////////////\r
-\r
-/**\r
-    @page overview_events Events and Event Handling\r
-\r
-    Related classes: wxEvtHandler, wxWindow, wxEvent\r
-\r
-@li @ref overview_events_introduction\r
-@li @ref overview_events_eventhandling\r
-@li @ref overview_events_processing\r
-@li @ref overview_events_custom\r
-@li @ref overview_events_misc\r
-\r
-\r
-<hr>\r
-\r
-\r
-@section overview_events_introduction Introduction to Events\r
-\r
-Like with all the other GUI frameworks, the control of flow in wxWidgets\r
-applications is event-based: the program normally performs most of its actions\r
-in response to the events generated by the user. These events can be triggered\r
-by using the input devices (such as keyboard, mouse, joystick) directly or,\r
-more commonly, by a standard control which synthesizes such input events into\r
-higher level events: for example, a wxButton can generate a click event when\r
-the user presses the left mouse button on it and then releases it without\r
-pressing @c Esc in the meanwhile. There are also events which don't directly\r
-correspond to the user actions, such as wxTimerEvent or wxSocketEvent.\r
-\r
-But in all cases wxWidgets represents these events in a uniform way and allows\r
-you to handle them in the same way wherever they originate from. And while the\r
-events are normally generated by wxWidgets itself, you can also do this, which\r
-is especially useful when using custom events (see @ref overview_events_custom).\r
-\r
-To be more precise, each event is described by:\r
- - <em>Event type</em>: this is simply a value of type wxEventType which\r
- uniquely identifies the type of the event. For example, clicking on a button,\r
- selecting an item from a list box and pressing a key on the keyboard all\r
- generate events with different event types.\r
- - <em>Event class</em> carried by the event: each event has some information\r
- associated with it and this data is represented by an object of a class\r
- derived from wxEvent. Events of different types can use the same event class,\r
- for example both button click and listbox selection events use wxCommandEvent\r
- class (as do all the other simple control events), but the key press event\r
- uses wxKeyEvent as the information associated with it is different.\r
- - <em>Event source</em>: wxEvent stores the object which generated the event\r
- and, for windows, its identifier (see @ref overview_events_winid). As it is\r
- common to have more than one object generating events of the same type (e.g. a\r
- typical window contains several buttons, all generating the same button click\r
- event), checking the event source object or its id allows to distinguish\r
- between them.\r
-\r
-\r
-@section overview_events_eventhandling Event Handling\r
-\r
-There are two principal ways to handle events in wxWidgets. One of them uses\r
-<em>event table</em> macros and allows you to define the connection between events\r
-and their handlers only statically, i.e., during program compilation. The other\r
-one uses wxEvtHandler::Connect() call and can be used to connect, and\r
-disconnect, the handlers dynamically, i.e., during run-time depending on some\r
-conditions. It also allows the direct connection of the events of one object to a\r
-handler method in another object. The static event tables can only handle\r
-events in the object where they are defined so using Connect() is more flexible\r
-than using the event tables. On the other hand, event tables are more succinct\r
-and centralize all event handlers connection in one place. You can either\r
-choose a single approach that you find preferable or freely combine both\r
-methods in your program in different classes or even in one and the same class,\r
-although this is probably sufficiently confusing to be a bad idea.\r
-\r
-But before you make this choice, let us discuss these two ways in more\r
-detail. In the next section we provide a short introduction to handling the\r
-events using the event tables. Please see @ref overview_events_connect\r
-for the discussion of Connect().\r
-\r
-@subsection overview_events_eventtables Event Handling with Event Tables\r
-\r
-To use an <em>event table</em> you must first decide in which class you wish to\r
-handle the events. The only requirement imposed by wxWidgets is that this class\r
-must derive from wxEvtHandler and so, considering that wxWindow derives from\r
-it, any classes representing windows can handle events. Simple events such as\r
-menu commands are usually processed at the level of a top-level window\r
-containing the menu, so let's suppose that you need to handle some events in @c\r
-MyFrame class deriving from wxFrame.\r
-\r
-First define one or more <em>event handlers</em>. They\r
-are just simple (non-virtual) methods of the class that take as a parameter a\r
-reference to an object of a wxEvent-derived class and have no return value (any\r
-return information is passed via the argument, which is why it is non-const).\r
-You also need to insert a macro\r
-\r
-@code\r
-DECLARE_EVENT_TABLE()\r
-@endcode\r
-\r
-somewhere in the class declaration. It doesn't matter where it appears but\r
-it's customary to put it at the end because the macro changes the access\r
-type internally so it's safest if nothing follows it. The\r
-full class declaration might look like this:\r
-\r
-@code\r
-class MyFrame : public wxFrame\r
-{\r
-public:\r
-    MyFrame(...) : wxFrame(...) { }\r
-\r
-    ...\r
-\r
-protected:\r
-    int m_whatever;\r
-\r
-private:\r
-    // Notice that as the event handlers normally are not called from outside\r
-    // the class, they normally are private. In particular they don't need\r
-    // to be public.\r
-    void OnExit(wxCommandEvent& event);\r
-    void OnButton1(wxCommandEvent& event);\r
-    void OnSize(wxSizeEvent& event);\r
-\r
-    // it's common to call the event handlers OnSomething() but there is no\r
-    // obligation to do that; this one is an event handler too:\r
-    void DoTest(wxCommandEvent& event);\r
-\r
-    DECLARE_EVENT_TABLE()\r
-};\r
-@endcode\r
-\r
-Next the event table must be defined and, as with any definition, it must be\r
-placed in an implementation file. The event table tells wxWidgets how to map\r
-events to member functions and in our example it could look like this:\r
-\r
-@code\r
-BEGIN_EVENT_TABLE(MyFrame, wxFrame)\r
-    EVT_MENU(wxID_EXIT, MyFrame::OnExit)\r
-    EVT_MENU(DO_TEST, MyFrame::DoTest)\r
-    EVT_SIZE(MyFrame::OnSize)\r
-    EVT_BUTTON(BUTTON1, MyFrame::OnButton1)\r
-END_EVENT_TABLE()\r
-@endcode\r
-\r
-Notice that you must mention a method you want to use for the event handling in\r
-the event table definition; just defining it in MyFrame class is @e not enough.\r
-\r
-Let us now look at the details of this definition: the first line means that we\r
-are defining the event table for MyFrame class and that its base class is\r
-wxFrame, so events not processed by MyFrame will, by default, be handled by\r
-wxFrame. The next four lines define connections of individual events to their\r
-handlers: the first two of them map menu commands from the items with the\r
-identifiers specified as the first macro parameter to two different member\r
-functions. In the next one, @c EVT_SIZE means that any changes in the size of\r
-the frame will result in calling OnSize() method. Note that this macro doesn't\r
-need a window identifier, since normally you are only interested in the current\r
-window's size events.\r
-\r
-The @c EVT_BUTTON macro demonstrates that the originating event does not have to\r
-come from the window class implementing the event table -- if the event source\r
-is a button within a panel within a frame, this will still work, because event\r
-tables are searched up through the hierarchy of windows for the command events.\r
-(But only command events, so you can't catch mouse move events in a child\r
-control in the parent window in the same way because wxMouseEvent doesn't\r
-derive from wxCommandEvent. See below for how you can do it.) In this case, the\r
-button's event table will be searched, then the parent panel's, then the\r
-frame's.\r
-\r
-Finally, you need to implement the event handlers. As mentioned before, all\r
-event handlers take a wxEvent-derived argument whose exact class differs\r
-according to the type of event and the class of the originating window. For\r
-size events, wxSizeEvent is used. For menu commands and most control commands\r
-(such as button presses), wxCommandEvent is used. When controls get more\r
-complicated, more specific wxCommandEvent-derived event classes providing\r
-additional control-specific information can be used, such as wxTreeEvent for\r
-events from wxTreeCtrl windows.\r
-\r
-In the simplest possible case an event handler may not use the @c event\r
-parameter at all. For example,\r
-\r
-@code\r
-void MyFrame::OnExit(wxCommandEvent& WXUNUSED(event))\r
-{\r
-    // when the user selects "Exit" from the menu we should close\r
-    Close(true);\r
-}\r
-@endcode\r
-\r
-In other cases you may need some information carried by the @c event argument,\r
-as in:\r
-\r
-@code\r
-void MyFrame::OnSize(wxSizeEvent& event)\r
-{\r
-    wxSize size = event.GetSize();\r
-\r
-    ... update the frame using the new size ...\r
-}\r
-@endcode\r
-\r
-You will find the details about the event table macros and the corresponding\r
-wxEvent-derived classes in the discussion of each control generating these\r
-events.\r
-\r
-\r
-@subsection overview_events_connect Dynamic Event Handling\r
-\r
-As with the event tables, decide in which class you intend to\r
-handle the events first and, as before, this class must derive from\r
-wxEvtHandler (usually indirectly via wxWindow). See the declaration of MyFrame\r
-in the previous section. However the similarities end here and both the syntax\r
-and the possibilities of handling events in this way are rather different.\r
-\r
-Let us start by looking at the syntax: the first obvious difference is that you\r
-need not use DECLARE_EVENT_TABLE() nor BEGIN_EVENT_TABLE() and the\r
-associated macros. Instead, in any place in your code, but usually in\r
-the code of the class defining the handler itself (and definitely not in the\r
-global scope as with the event tables), call its Connect() method like this:\r
-\r
-@code\r
-MyFrame::MyFrame(...)\r
-{\r
-      Connect(wxID_EXIT, wxEVT_COMMAND_MENU_SELECTED,\r
-                wxCommandEventHandler(MyFrame::OnExit));\r
-}\r
-@endcode\r
-\r
-This class should be self-explanatory except for wxCommandEventHandler part:\r
-this is a macro that ensures that the method is of the correct type by using\r
-static_cast in the same way as the event table macros.\r
-\r
-Now let us describe the semantic differences:\r
-<ul>\r
-    <li>\r
-        Event handlers can be connected at any moment. For example, it's possible\r
-        to do some initialization first and only connect the handlers if and when\r
-        it succeeds. This can avoid the need to test that the object was properly\r
-        initialized in the event handlers themselves. With Connect() they\r
-        simply won't be called if it wasn't correctly initialized.\r
-    </li>\r
-\r
-    <li>\r
-        As a slight extension of the above, the handlers can also be\r
-        Disconnect()-ed at any time and maybe later reconnected. Of course,\r
-        it's also possible to emulate this behaviour with the classic\r
-        static (i.e., connected via event tables) handlers by using an internal\r
-        flag indicating whether the handler is currently enabled and returning\r
-        from it if it isn't, but using dynamically connected handlers requires\r
-        less code and is also usually more clear.\r
-    </li>\r
-\r
-    <li>\r
-        Also notice that you must derive a class inherited from, say,\r
-        wxTextCtrl even if you don't want to modify the control behaviour at\r
-        all but just want to handle some of its events. This is especially\r
-        inconvenient when the control is loaded from the XRC. Connecting the\r
-        event handler dynamically bypasses the need for this unwanted\r
-        sub-classing.\r
-    </li>\r
-\r
-    <li>\r
-        Last but very, very far from least is the possibility to connect an\r
-        event of some object to a method of another object. This is impossible\r
-        to do with event tables because it is not possible to specify the\r
-        object to dispatch the event to so it necessarily needs to be sent to\r
-        the same object which generated the event. Not so with Connect() which\r
-        has an optional @c eventSink parameter that can be used to specify the\r
-        object which will handle the event. Of course, in this case the method\r
-        being connected must belong to the class that is the type of the\r
-        @c eventSink object! To give a quick example, people often want to catch\r
-        mouse movement events happening when the mouse is in one of the frame\r
-        children in the frame itself. Doing it in a naive way doesn't work:\r
-        <ul>\r
-            <li>\r
-                A @c EVT_LEAVE_WINDOW(MyFrame::OnMouseLeave) line in the frame\r
-                event table has no effect as mouse move (including entering and\r
-                leaving) events are not propagated up to the parent window\r
-                (at least not by default).\r
-            </li>\r
-\r
-            <li>\r
-                Putting the same line in a child event table will crash during\r
-                run-time because the MyFrame method will be called on a wrong\r
-                object -- it's easy to convince oneself that the only object\r
-                that can be used here is the pointer to the child, as\r
-                wxWidgets has nothing else. But calling a frame method with the\r
-                child window pointer instead of the pointer to the frame is, of\r
-                course, disastrous.\r
-            </li>\r
-        </ul>\r
-\r
-        However writing\r
-        @code\r
-            MyFrame::MyFrame(...)\r
-            {\r
-              m_child->Connect(wxID_ANY, wxEVT_LEAVE_WINDOW,\r
-                               wxMouseEventHandler(MyFrame::OnMouseLeave),\r
-                               NULL,  // unused extra data parameter\r
-                               this); // this indicates the object to connect to\r
-            }\r
-        @endcode\r
-        will work exactly as expected. Note that you can get the object that\r
-        generated the event -- and that 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
-</ul>\r
-\r
-To summarize, using Connect() requires slightly more typing but is much more\r
-flexible than using static event tables so don't hesitate to use it when you\r
-need this extra power. On the other hand, event tables are still perfectly fine\r
-in simple situations where this extra flexibility is not needed.\r
-\r
-\r
-@section overview_events_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 wxWidgets finds the handler to call for the\r
-given event. This section describes the algorithm used in detail.\r
-\r
-When an event is received from the windowing system, wxWidgets calls\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
-    <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
-    <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
-    <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
-    <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
-    <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():\r
-        @image html overview_events_chain.png\r
-    (referring to the image, if @c A->ProcessEvent is called and it doesn't handle\r
-     the event, @c B->ProcessEvent will be called and so on...).\r
-    In the case of wxWindow you can build a stack (implemented using wxEvtHandler\r
-    double-linked list) using wxWindow::PushEventHandler():\r
-        @image html overview_events_winstack.png\r
-    (referring to the image, if @c W->ProcessEvent is called, it immediately calls\r
-     @c A->ProcessEvent; if nor @c A nor @c B handle the event, then the wxWindow\r
-     itself is used - i.e. the dynamically connected event handlers and static\r
-     event table entries of wxWindow are looked as the last possibility, after\r
-     all pushed event handlers were tested).\r
-    Note however that usually there are no wxEvtHandler chains nor wxWindows stacks\r
-    so this step will usually do anything.\r
-    </li>\r
-\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
-    (which derives from wxEvtHandler) gets a last chance to process it.\r
-    </li>\r
-</ol>\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 up 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 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 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, and not in the\r
-document or document manager classes\r
-\r
-\r
-@subsection overview_events_propagation How Events Propagate Upwards\r
-\r
-As mentioned above, the events of the classes deriving from wxCommandEvent are\r
-propagated by default to the parent window if they are not processed in this\r
-window itself. But although by default only the command events are propagated\r
-like this, other events can be propagated as well because the event handling\r
-code uses wxEvent::ShouldPropagate() to check whether an event should be\r
-propagated. It is also possible to propagate the event only a limited number of\r
-times and not until it is processed (or a top level parent 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
-events up to the parent window, the event propagation stops when it\r
-reaches the parent dialog, if any. This means that you don't risk getting\r
-unexpected events from the dialog controls (which might be left unprocessed by\r
-the dialog itself because it doesn't care about them) when a modal dialog is\r
-popped up. The events do propagate beyond the frames, however. The rationale\r
-for this choice is that there are only a few frames in a typical application\r
-and their parent-child relation are well understood by the programmer while it\r
-may be difficult, if not impossible, to track down all the dialogs that\r
-may be popped up in a complex program (remember that some are created\r
-automatically by wxWidgets). If you need to specify a different behaviour for\r
-some reason, you can use wxWindow::SetExtraStyle(wxWS_EX_BLOCK_EVENTS)\r
-explicitly to prevent the events from being propagated beyond the given window\r
-or unset this flag for the dialogs that have it on by default.\r
-\r
-Typically events that deal with a window as a window (size, motion,\r
-paint, mouse, keyboard, etc.) are sent only to the window.  Events\r
-that have a higher level of meaning or are generated by the window\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
-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 that 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
-@li wxCloseEvent: A close window or end session event\r
-@li wxEraseEvent: An erase background event\r
-@li wxFocusEvent: A window focus event\r
-@li wxKeyEvent: A keypress event\r
-@li wxIdleEvent: An idle event\r
-@li wxInitDialogEvent: A dialog initialisation event\r
-@li wxJoystickEvent: A joystick event\r
-@li wxMenuEvent: A menu event\r
-@li wxMouseEvent: A mouse event\r
-@li wxMoveEvent: A move event\r
-@li wxPaintEvent: A paint event\r
-@li wxQueryLayoutInfoEvent: Used to query layout information\r
-@li wxSetCursorEvent: Used for special cursor processing based on current mouse position\r
-@li wxSizeEvent: A size event\r
-@li wxScrollWinEvent: A scroll event sent by a scrolled window (not a scroll bar)\r
-@li wxSysColourChangedEvent: A system colour change event\r
-\r
-In some cases, it might be desired by the programmer to get a certain number\r
-of system events in a parent window, for example all key events sent to, but not\r
-used by, the native controls in a dialog. In this case, a special event handler\r
-will have to be written that will override ProcessEvent() in order to pass\r
-all events (or any selection of them) to the parent window.\r
-\r
-\r
-@section overview_events_custom Custom Event Summary\r
-\r
-@subsection overview_events_custom_general General approach\r
-\r
-Since version 2.2.x of wxWidgets, each event type is identified by an ID\r
-given to the event type @e at runtime that 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).\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 an entirely new event class (typically deriving from\r
-wxEvent or wxCommandEvent).\r
-\r
-The other is to use the existing event classes and give them a new event\r
-type. You'll have to define and declare a new event type either way\r
-using the following macros:\r
-\r
-@code\r
-// in the header of the source file\r
-extern const wxEventType wxEVT_YOUR_EVENT_NAME;\r
-\r
-// in the implementation\r
-DEFINE_EVENT_TYPE(wxEVT_YOUR_EVENT_NAME)\r
-@endcode\r
-\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_events_custom_existing Using Existing Event Classes\r
-\r
-If you just want to use a wxCommandEvent with a new event type, 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
-extern const wxEventType wxEVT_MY_EVENT;\r
-DEFINE_EVENT_TYPE(wxEVT_MY_EVENT)\r
-\r
-// user code intercepting the event\r
-\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
-END_EVENT_TABLE()\r
-\r
-void MyFrame::OnMyEvent( wxCommandEvent& event )\r
-{\r
-    // do something\r
-    wxString text = event.GetText();\r
-}\r
-\r
-\r
-// user code sending the event\r
-\r
-void MyWindow::SendEvent()\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
-@endcode\r
-\r
-\r
-@subsection overview_events_custom_generic Generic Event Table Macros\r
-\r
-@beginTable\r
-@row2col{EVT_CUSTOM(event\, id\, func),\r
-        Allows you to add a custom event table\r
-        entry by specifying the event identifier (such as wxEVT_SIZE),\r
-        the window identifier, and a member function to call.}\r
-@row2col{EVT_CUSTOM_RANGE(event\, id1\, id2\, func),\r
-        The same as EVT_CUSTOM, but responds to a range of window identifiers.}\r
-@row2col{EVT_COMMAND(id\, event\, func),\r
-        The same as EVT_CUSTOM, but expects a member function with a\r
-        wxCommandEvent argument.}\r
-@row2col{EVT_COMMAND_RANGE(id1\, id2\, event\, func),\r
-        The same as EVT_CUSTOM_RANGE, but\r
-        expects a member function with a wxCommandEvent argument.}\r
-@row2col{EVT_NOTIFY(event\, id\, func),\r
-        The same as EVT_CUSTOM, but\r
-        expects a member function with a wxNotifyEvent argument.}\r
-@row2col{EVT_NOTIFY_RANGE(event\, id1\, id2\, func),\r
-        The same as EVT_CUSTOM_RANGE, but\r
-        expects a member function with a wxNotifyEvent argument.}\r
-@endTable\r
-\r
-\r
-@subsection overview_events_custom_ownclass Defining Your Own Event Class\r
-\r
-Under certain circumstances, you must define your own event\r
-class e.g., for sending more complex data from one place to another. Apart\r
-from defining your event class, you will also need to define your own\r
-event table macro (which is quite long). Watch out to put in enough\r
-casts to the inherited event function. Here is an example:\r
-\r
-@code\r
-// code defining event\r
-\r
-class wxPlotEvent: public wxNotifyEvent\r
-{\r
-public:\r
-    wxPlotEvent( wxEventType commandType = wxEVT_NULL, int id = 0 );\r
-\r
-    // accessors\r
-    wxPlotCurve *GetCurve()\r
-        { return m_curve; }\r
-\r
-    // required for sending with wxPostEvent()\r
-    virtual wxEvent *Clone() const;\r
-\r
-private:\r
-    wxPlotCurve   *m_curve;\r
-};\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
-    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
-{\r
-    ...\r
-}\r
-\r
-\r
-// user code intercepting the event\r
-\r
-BEGIN_EVENT_TABLE(MyFrame, wxFrame)\r
-EVT_PLOT  (ID_MY_WINDOW, MyFrame::OnPlot)\r
-END_EVENT_TABLE()\r
-\r
-void MyFrame::OnPlot( wxPlotEvent &event )\r
-{\r
-    wxPlotCurve *curve = event.GetCurve();\r
-}\r
-\r
-\r
-// user code sending the event\r
-\r
-void MyWindow::SendEvent()\r
-{\r
-    wxPlotEvent event( wxEVT_PLOT_ACTION, GetId() );\r
-    event.SetEventObject( this );\r
-    event.SetCurve( m_curve );\r
-    GetEventHandler()->ProcessEvent( event );\r
-}\r
-@endcode\r
-\r
-\r
-@section overview_events_misc Miscellaneous Notes\r
-\r
-@subsection overview_events_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 you 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\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 handlers 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
-@subsection overview_events_prog User Generated Events vs Programmatically Generated Events\r
-\r
-While generically wxEvents can be generated both by user\r
-actions (e.g., resize of a wxWindow) and by calls to functions\r
-(e.g., wxWindow::SetSize), wxWidgets controls normally send wxCommandEvent-derived\r
-events only for the user-generated events. The only @b exceptions to this rule are:\r
-\r
-@li wxNotebook::AddPage: No event-free alternatives\r
-@li wxNotebook::AdvanceSelection: No event-free alternatives\r
-@li wxNotebook::DeletePage: No event-free alternatives\r
-@li wxNotebook::SetSelection: Use wxNotebook::ChangeSelection instead, as\r
-    wxNotebook::SetSelection is deprecated\r
-@li wxTreeCtrl::Delete: No event-free alternatives\r
-@li wxTreeCtrl::DeleteAllItems: No event-free alternatives\r
-@li wxTreeCtrl::EditLabel: No event-free alternatives\r
-@li All wxTextCtrl methods\r
-\r
-wxTextCtrl::ChangeValue can be used instead of wxTextCtrl::SetValue but the other\r
-functions, such as wxTextCtrl::Replace or wxTextCtrl::WriteText don't have event-free\r
-equivalents.\r
-\r
-\r
-\r
-@subsection overview_events_pluggable Pluggable Event Handlers\r
-\r
-<em>TODO: Probably deprecated, Connect() provides a better way to do this</em>\r
-\r
-In fact, you don't have to derive a new class from a window class\r
-if you don't want to. You can derive a new class from wxEvtHandler instead,\r
-defining the appropriate event table, and then call wxWindow::SetEventHandler\r
-(or, preferably, wxWindow::PushEventHandler) to make this\r
-event handler the object that responds to events. This way, you can avoid\r
-a lot of class derivation, and use instances of the same event handler class (but different\r
-objects as the same event handler object shouldn't be used more than once) to\r
-handle events from instances of different widget classes.\r
-\r
-If you ever have to call a window's event handler\r
-manually, use the GetEventHandler function to retrieve the window's event handler and use that\r
-to call the member function. By default, GetEventHandler returns a pointer to the window itself\r
-unless an application has redirected event handling using SetEventHandler or PushEventHandler.\r
-\r
-One use of PushEventHandler is to temporarily or permanently change the\r
-behaviour of the GUI. For example, you might want to invoke a dialog editor\r
-in your application that changes aspects of dialog boxes. You can\r
-grab all the input for an existing dialog box, and edit it 'in situ',\r
-before restoring its behaviour to normal. So even if the application\r
-has derived new classes to customize behaviour, your utility can indulge\r
-in a spot of body-snatching. It could be a useful technique for on-line\r
-tutorials, too, where you take a user through a serious of steps and\r
-don't want them to diverge from the lesson. Here, you can examine the events\r
-coming from buttons and windows, and if acceptable, pass them through to\r
-the original event handler. Use PushEventHandler/PopEventHandler\r
-to form a chain of event handlers, where each handler processes a different\r
-range of events independently from the other handlers.\r
-\r
-\r
-\r
-@subsection overview_events_winid Window Identifiers\r
-\r
-Window identifiers are integers, and are used to\r
-uniquely determine window identity in the event system (though you can use it\r
-for other purposes). In fact, identifiers do not need to be unique\r
-across your entire application as long they are unique within the\r
-particular context you're interested in, such as a frame and its children. You\r
-may use the @c wxID_OK identifier, for example, on any number of dialogs\r
-as long as you don't have several within the same dialog.\r
-\r
-If you pass @c wxID_ANY to a window constructor, an identifier will be\r
-generated for you automatically by wxWidgets. This is useful when you don't\r
-care about the exact identifier either because you're not going to process the\r
-events from the control being created or because you process the events\r
-from all controls in one place (in which case you should specify @c wxID_ANY\r
-in the event table or wxEvtHandler::Connect call\r
-as well). The automatically generated identifiers are always negative and so\r
-will never conflict with the user-specified identifiers which must be always\r
-positive.\r
-\r
-See @ref page_stdevtid for the list of standard identifiers available.\r
-You can use wxID_HIGHEST to determine the number above which it is safe to\r
-define your own identifiers. Or, you can use identifiers below wxID_LOWEST.\r
-Finally, you can allocate identifiers dynamically using wxNewId() function too.\r
-If you use wxNewId() consistently in your application, you can be sure that\r
-your identifiers don't conflict accidentally.\r
-\r
-\r
-@subsection overview_events_macros Event Handling Summary\r
-\r
-For the full list of event classes, please see the\r
-@ref group_class_events "event classes group page".\r
-\r
-\r
-*/\r
-\r
+/////////////////////////////////////////////////////////////////////////////
+// Name:        eventhandling.h
+// Purpose:     topic overview
+// Author:      wxWidgets team
+// RCS-ID:      $Id$
+// Licence:     wxWindows licence
+/////////////////////////////////////////////////////////////////////////////
+
+/**
+
+@page overview_events Events and Event Handling
+
+Related classes: wxEvtHandler, wxWindow, wxEvent
+
+@li @ref overview_events_introduction
+@li @ref overview_events_eventhandling
+@li @ref overview_events_processing
+@li @ref overview_events_custom
+@li @ref overview_events_misc
+
+
+<hr>
+
+
+@section overview_events_introduction Introduction to Events
+
+Like with all the other GUI frameworks, the control of flow in wxWidgets
+applications is event-based: the program normally performs most of its actions
+in response to the events generated by the user. These events can be triggered
+by using the input devices (such as keyboard, mouse, joystick) directly or,
+more commonly, by a standard control which synthesizes such input events into
+higher level events: for example, a wxButton can generate a click event when
+the user presses the left mouse button on it and then releases it without
+pressing @c Esc in the meanwhile. There are also events which don't directly
+correspond to the user actions, such as wxTimerEvent or wxSocketEvent.
+
+But in all cases wxWidgets represents these events in a uniform way and allows
+you to handle them in the same way wherever they originate from. And while the
+events are normally generated by wxWidgets itself, you can also do this, which
+is especially useful when using custom events (see @ref overview_events_custom).
+
+To be more precise, each event is described by:
+ - <em>Event type</em>: this is simply a value of type wxEventType which
+ uniquely identifies the type of the event. For example, clicking on a button,
+ selecting an item from a list box and pressing a key on the keyboard all
+ generate events with different event types.
+ - <em>Event class</em> carried by the event: each event has some information
+ associated with it and this data is represented by an object of a class
+ derived from wxEvent. Events of different types can use the same event class,
+ for example both button click and listbox selection events use wxCommandEvent
+ class (as do all the other simple control events), but the key press event
+ uses wxKeyEvent as the information associated with it is different.
+ - <em>Event source</em>: wxEvent stores the object which generated the event
+ and, for windows, its identifier (see @ref overview_events_winid). As it is
+ common to have more than one object generating events of the same type (e.g. a
+ typical window contains several buttons, all generating the same button click
+ event), checking the event source object or its id allows to distinguish
+ between them.
+
+
+@section overview_events_eventhandling Event Handling
+
+There are two principal ways to handle events in wxWidgets. One of them uses
+<em>event table</em> 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::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 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
+
+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 define one or more <em>event handlers</em>. They
+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
+
+@code
+wxDECLARE_EVENT_TABLE()
+@endcode
+
+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
+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 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 do that; this one is an event handler too:
+    void DoTest(wxCommandEvent& event);
+
+    wxDECLARE_EVENT_TABLE()
+};
+@endcode
+
+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
+wxBEGIN_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)
+wxEND_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.
+
+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 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
+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 @c 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
+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. 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. For example,
+
+@code
+void MyFrame::OnExit(wxCommandEvent& WXUNUSED(event))
+{
+    // when the user selects "Exit" from the menu we should close
+    Close(true);
+}
+@endcode
+
+In other cases you may need some information carried by the @c event argument,
+as in:
+
+@code
+void MyFrame::OnSize(wxSizeEvent& event)
+{
+    wxSize size = event.GetSize();
+
+    ... update the frame using the new size ...
+}
+@endcode
+
+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.
+
+
+@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 wxDECLARE_EVENT_TABLE() nor wxBEGIN_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 Bind<>() method like this:
+
+@code
+MyFrame::MyFrame(...)
+{
+      Bind(wxEVT_COMMAND_MENU_SELECTED, &MyFrame::OnExit, this, wxID_EXIT);
+}
+@endcode
+
+Note that @c this pointer must be specified here.
+
+Now let us describe the semantic differences:
+<ul>
+    <li>
+        Event handlers can be bound at any moment. For example, it's possible
+        to do some initialization first and only bind 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 Bind<>() they
+        simply won't be called if it wasn't correctly initialized.
+    </li>
+
+    <li>
+        As a slight extension of the above, the handlers can also be unbound at
+        any time with Unbind<>() (and maybe rebound later). Of course,
+        it's also possible to emulate this behaviour with the classic
+        static (i.e., bound 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 bind handlers requires
+        less code and is also usually more clear.
+    </li>
+
+    <li>
+        Almost last but very, very far from least is the increased flexibility
+        which allows to bind an event to:
+        @li A method in another object.
+        @li An ordinary function like a static method or a global function.
+        @li An arbitrary functor like boost::function<>.
+
+        This is impossible to do with the event tables because it is not
+        possible to specify these handlers to dispatch the event to, so it
+        necessarily needs to be sent to the same object which generated the
+        event. Not so with Bind<>() which can be used to specify these handlers
+        which will handle the event. To give a quick example, a common question
+        is how to receive the 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 up 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
+                that 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->Bind(wxEVT_LEAVE_WINDOW, &MyFrame::OnMouseLeave, this);
+            }
+        @endcode
+        will work exactly as expected. Note that you can get the object that
+        generated the event -- and that is not the same as the frame -- via
+        wxEvent::GetEventObject() method of @c event argument passed to the
+        event handler.
+    </li>
+
+    <li>
+        Really last point is the consequence of the previous one: because of
+        increased flexibility of Bind(), it is also safer as it is impossible
+        to accidentally use a method of another class. Instead of run-time
+        crashes you will get compilation errors in this case when using Bind().
+    </li>
+</ul>
+
+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):
+
+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 & )
+{
+    // Do something useful.
+}
+
+MyFrameHandler myFrameHandler;
+
+MyFrame::MyFrame()
+{
+      Bind( wxEVT_COMMAND_MENU_SELECTED, &MyFrameHandler::OnFrameExit,
+              &myFrameHandler, wxID_EXIT );
+}
+@endcode
+
+Note that @c MyFrameHandler doesn't need to derive from wxEvtHandler. But
+keep in mind that then the lifetime of @c myFrameHandler must be greater than
+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:
+
+@code
+void HandleExit( wxCommandEvent & )
+{
+    // Do something useful
+}
+
+MyFrame::MyFrame()
+{
+    Bind( wxEVT_COMMAND_MENU_SELECTED, &HandleExit, wxID_EXIT );
+}
+@endcode
+
+And finally you can bind to an arbitrary functor and use it as an event
+handler:
+
+@code
+
+struct MyFunctor
+{
+    void operator()( wxCommandEvent & )
+    {
+        // Do something useful
+    }
+};
+
+MyFunctor myFunctor;
+
+MyFrame::MyFrame()
+{
+    Bind( wxEVT_COMMAND_MENU_SELECTED, &myFunctor, wxID_EXIT );
+}
+@endcode
+
+A common example of a functor is boost::function<>:
+
+@code
+using namespace boost;
+
+void MyHandler::OnExit( wxCommandEvent & )
+{
+    // Do something useful
+}
+
+MyHandler myHandler;
+
+MyFrame::MyFrame()
+{
+    function< void ( wxCommandEvent & ) > exitHandler( bind( &MyHandler::OnExit, &myHandler, _1 ));
+
+    Bind( wxEVT_COMMAND_MENU_SELECTED, exitHandler, wxID_EXIT );
+}
+@endcode
+
+
+With the aid of boost::bind<>() you can even use methods or functions which
+don't quite have the correct signature:
+
+@code
+void MyHandler::OnExit( int exitCode, wxCommandEvent &, wxString goodByeMessage )
+{
+    // Do something useful
+}
+
+MyHandler myHandler;
+
+MyFrame::MyFrame()
+{
+    function< void ( wxCommandEvent & ) > exitHandler(
+            bind( &MyHandler::OnExit, &myHandler, EXIT_FAILURE, _1, "Bye" ));
+
+    Bind( wxEVT_COMMAND_MENU_SELECTED, exitHandler, wxID_EXIT );
+}
+@endcode
+
+
+To summarize, using Bind<>() 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_events_processing How Events are Processed
+
+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. 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
+window generating the event. The normal order of event table searching by
+ProcessEvent() is as follows, with the event processing stopping as soon as a
+handler is found (unless the handler calls wxEvent::Skip() in which case it
+doesn't count as having handled the event and the search continues):
+<ol>
+    <li value="0">
+    Before anything else happens, wxApp::FilterEvent() is called. If it returns
+    anything but -1 (default), the event handling stops immediately.
+    </li>
+
+    <li value="1">
+    If this event handler is disabled via a call to
+    wxEvtHandler::SetEvtHandlerEnabled() the next three steps are skipped and
+    the event handler resumes at step (5).
+    </li>
+
+    <li value="2">
+    If the object is a wxWindow and has an associated validator, wxValidator
+    gets a chance to process the event.
+    </li>
+
+    <li value="3">
+    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 unless wxEvent::Skip() is called in the dynamic one.
+    </li>
+
+    <li value="4">
+    The event table containing all the handlers defined using the event table
+    macros in this class and its base classes is examined. Notice that this
+    means that any event handler defined in a base class will be executed at
+    this step.
+    </li>
+
+    <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. 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">
+    If the object is a wxWindow and the event is set to propagate (by default
+    only wxCommandEvent-derived events are set to propagate), then the
+    processing restarts from the step (1) (and excluding the step (7)) for the
+    parent window. If this object is not a window but the next handler exists,
+    the event is passed to its parent if it is a window. This ensures that in a
+    common case of (possibly several) non-window event handlers pushed on top
+    of a window, the event eventually reaches the window parent.
+    </li>
+
+    <li value="7">
+    Finally, i.e., if the event is still not processed, the wxApp object itself
+    (which derives from wxEvtHandler) gets a last chance to process it.
+    </li>
+</ol>
+
+<em>Please pay close attention to step 6!</em> People often overlook or get
+confused by this powerful feature of the wxWidgets event processing system. The
+details of event propagation up the window hierarchy are described in the
+next section.
+
+Also please notice that there are additional steps in the event handling for
+the windows-making part of wxWidgets document-view framework, i.e.,
+wxDocParentFrame, wxDocChildFrame and their MDI equivalents wxDocMDIParentFrame
+and wxDocMDIChildFrame. The parent frame classes modify step (2) above to
+send the events received by them to wxDocManager object first. This object, in
+turn, sends the event to the current view and the view itself lets its
+associated document process the event first. The child frame classes send
+the event directly to the associated view which still forwards it to its
+document object. Notice that to avoid remembering the exact order in which the
+events are processed in the document-view frame, the simplest, and recommended,
+solution is to only handle the events at the view classes level, and not in the
+document or document manager classes
+
+
+@subsection overview_events_propagation How Events Propagate Upwards
+
+As mentioned above, the events of the classes deriving from wxCommandEvent are
+propagated by default to the parent window if they are not processed in this
+window itself. But although by default only the command events are propagated
+like this, other events can be propagated as well because the event handling
+code uses wxEvent::ShouldPropagate() to check whether an event should be
+propagated. It is also possible to propagate the event only a limited number of
+times and not until it is processed (or a top level parent window is reached).
+
+Finally, there is another additional complication (which, in fact, simplifies
+life of wxWidgets programmers significantly): when propagating the command
+events up to the parent window, the event propagation stops when it
+reaches the parent dialog, if any. This means that you don't risk getting
+unexpected events from the dialog controls (which might be left unprocessed by
+the dialog itself because it doesn't care about them) when a modal dialog is
+popped up. The events do propagate beyond the frames, however. The rationale
+for this choice is that there are only a few frames in a typical application
+and their parent-child relation are well understood by the programmer while it
+may be difficult, if not impossible, to track down all the dialogs that
+may be popped up in a complex program (remember that some are created
+automatically by wxWidgets). If you need to specify a different behaviour for
+some reason, you can use <tt>wxWindow::SetExtraStyle(wxWS_EX_BLOCK_EVENTS)</tt>
+explicitly to prevent the events from being propagated beyond the given window
+or unset this flag for the dialogs that have it on by default.
+
+Typically events that deal with a window as a window (size, motion,
+paint, mouse, keyboard, etc.) are sent only to the window.  Events
+that have a higher level of meaning or are generated by the window
+itself (button click, menu select, tree expand, etc.) are command
+events and are sent up to the parent to see if it is interested in the event.
+More precisely, as said above, all event classes @b not deriving from wxCommandEvent
+(see the wxEvent inheritance map) do @b not propagate upward.
+
+In some cases, it might be desired by the programmer to get a certain number
+of system events in a parent window, for example all key events sent to, but not
+used by, the native controls in a dialog. In this case, a special event handler
+will have to be written that will override ProcessEvent() in order to pass
+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
+
+As each event is uniquely defined by its event type, defining a custom event
+starts with defining a new event type for it. This is done using
+wxDEFINE_EVENT() macro. As an event type is a variable, it can also be
+declared using wxDECLARE_EVENT() if necessary.
+
+The next thing to do is to decide whether you need to define a custom event
+class for events of this type or if you can reuse an existing class, typically
+either wxEvent (which doesn't provide any extra information) or wxCommandEvent
+(which contains several extra fields and also propagates upwards by default).
+Both strategies are described in details below. See also the @ref
+page_samples_event for a complete example of code defining and working with the
+custom event types.
+
+Finally, you will need to generate and post your custom events.
+Generation is as simple as instancing your custom event class and initializing
+its internal fields.
+For posting events to a certain event handler there are two possibilities: 
+using wxEvtHandler::AddPendingEvent or using wxEvtHandler::QueueEvent.
+Basically you will need to use the latter when doing inter-thread communication;
+when you use only the main thread you can also safely use the former.
+Last, note that there are also two simple global wrapper functions associated
+to the two wxEvtHandler mentioned functions: wxPostEvent() and wxQueueEvent().
+
+
+@subsection overview_events_custom_existing Using Existing Event Classes
+
+If you just want to use a wxCommandEvent with a new event type, use one of the
+generic event table macros listed below, without having to define a new event
+class yourself.
+
+Example:
+
+@code
+// this is typically in a header: it just declares MY_EVENT event type
+wxDECLARE_EVENT(MY_EVENT, wxCommandEvent);
+
+// this is a definition so can't be in a header
+wxDEFINE_EVENT(MY_EVENT, wxCommandEvent);
+
+// example of code handling the event with event tables
+wxBEGIN_EVENT_TABLE(MyFrame, wxFrame)
+    EVT_MENU    (wxID_EXIT, MyFrame::OnExit)
+    ...
+    EVT_COMMAND (ID_MY_WINDOW, MY_EVENT, MyFrame::OnMyEvent)
+wxEND_EVENT_TABLE()
+
+void MyFrame::OnMyEvent(wxCommandEvent& event)
+{
+    // do something
+    wxString text = event.GetString();
+}
+
+// example of code handling the event with Bind<>():
+MyFrame::MyFrame()
+{
+    Bind(MY_EVENT, &MyFrame::OnMyEvent, this, ID_MY_WINDOW);
+}
+
+// example of code generating the event
+void MyWindow::SendEvent()
+{
+    wxCommandEvent event(MY_EVENT, GetId());
+    event.SetEventObject(this);
+
+    // Give it some contents
+    event.SetString("Hello");
+
+    // Do send it
+    ProcessWindowEvent(event);
+}
+@endcode
+
+
+@subsection overview_events_custom_ownclass Defining Your Own Event Class
+
+Under certain circumstances, you must define your own event class e.g., for
+sending more complex data from one place to another. Apart from defining your
+event class, you also need to define your own event table macro if you want to
+use event tables for handling events of this type.
+
+Here is an example:
+
+@code
+// define a new event class
+class MyPlotEvent: public wxEvent
+{
+public:
+    MyPlotEvent(wxEventType eventType, int winid, const wxPoint& pos)
+        : wxEvent(winid, eventType),
+          m_pos(pos)
+    {
+    }
+
+    // accessors
+    wxPoint GetPoint() const { return m_pos; }
+
+    // implement the base class pure virtual
+    virtual wxEvent *Clone() const { return new MyPlotEvent(*this); }
+
+private:
+    const wxPoint m_pos;
+};
+
+// we define a single MY_PLOT_CLICKED event type associated with the class
+// above but typically you are going to have more than one event type, e.g. you
+// could also have MY_PLOT_ZOOMED or MY_PLOT_PANNED &c -- in which case you
+// would just add more similar lines here
+wxDEFINE_EVENT(MY_PLOT_CLICKED, MyPlotEvent);
+
+
+// if you want to support old compilers you need to use some ugly macros:
+typedef void (wxEvtHandler::*MyPlotEventFunction)(MyPlotEvent&);
+#define MyPlotEventHandler(func) wxEVENT_HANDLER_CAST(MyPlotEventFunction, func)
+
+// if your code is only built using reasonably modern compilers, you could just
+// do this instead:
+#define MyPlotEventHandler(func) (&func)
+
+// finally define a macro for creating the event table entries for the new
+// event type
+//
+// remember that you don't need this at all if you only use Bind<>() and that
+// you can replace MyPlotEventHandler(func) with just &func unless you use a
+// really old compiler
+#define MY_EVT_PLOT_CLICK(id, func) \
+    wx__DECLARE_EVT1(MY_PLOT_CLICKED, id, MyPlotEventHandler(func))
+
+
+// example of code handling the event (you will use one of these methods, not
+// both, of course):
+wxBEGIN_EVENT_TABLE(MyFrame, wxFrame)
+    EVT_PLOT(ID_MY_WINDOW, MyFrame::OnPlot)
+wxEND_EVENT_TABLE()
+
+MyFrame::MyFrame()
+{
+    Bind(MY_PLOT_CLICKED, &MyFrame::OnPlot, this, ID_MY_WINDOW);
+}
+
+void MyFrame::OnPlot(MyPlotEvent& event)
+{
+    ... do something with event.GetPoint() ...
+}
+
+
+// example of code generating the event:
+void MyWindow::SendEvent()
+{
+    MyPlotEvent event(MY_PLOT_CLICKED, GetId(), wxPoint(...));
+    event.SetEventObject(this);
+    ProcessWindowEvent(event);
+}
+@endcode
+
+
+
+@section overview_events_misc Miscellaneous Notes
+
+@subsection overview_events_virtual Event Handlers vs Virtual Methods
+
+It may be noted that wxWidgets' event processing system implements something
+close to virtual methods in normal C++ in spirit: both of these mechanisms
+allow you to alter the behaviour of the base class by defining the event handling
+functions in the derived classes.
+
+There is however an important difference between the two mechanisms when you
+want to invoke the default behaviour, as implemented by the base class, from a
+derived class handler. With the virtual functions, you need to call the base
+class function directly and you can do it either in the beginning of the
+derived class handler function (to post-process the event) or at its end (to
+pre-process the event). With the event handlers, you only have the option of
+pre-processing the events and in order to still let the default behaviour
+happen you must call wxEvent::Skip() and @em not call the base class event
+handler directly. In fact, the event handler probably doesn't even exist in the
+base class as the default behaviour is often implemented in platform-specific
+code by the underlying toolkit or OS itself. But even if it does exist at
+wxWidgets level, it should never be called directly as the event handlers are
+not part of wxWidgets API and should never be called directly.
+
+
+
+@subsection overview_events_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
+(e.g., wxWindow::SetSize), wxWidgets controls normally send wxCommandEvent-derived
+events only for the user-generated events. The only @b exceptions to this rule are:
+
+@li wxNotebook::AddPage: No event-free alternatives
+@li wxNotebook::AdvanceSelection: No event-free alternatives
+@li wxNotebook::DeletePage: No event-free alternatives
+@li wxNotebook::SetSelection: Use wxNotebook::ChangeSelection instead, as
+    wxNotebook::SetSelection is deprecated
+@li wxTreeCtrl::Delete: No event-free alternatives
+@li wxTreeCtrl::DeleteAllItems: No event-free alternatives
+@li wxTreeCtrl::EditLabel: No event-free alternatives
+@li All wxTextCtrl methods
+
+wxTextCtrl::ChangeValue can be used instead of wxTextCtrl::SetValue but the other
+functions, such as wxTextCtrl::Replace or wxTextCtrl::WriteText don't have event-free
+equivalents.
+
+
+
+@subsection overview_events_pluggable Pluggable Event Handlers
+
+<em>TODO: Probably deprecated, Bind() provides a better way to do this</em>
+
+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,
+defining the appropriate event table, and then call wxWindow::SetEventHandler
+(or, preferably, wxWindow::PushEventHandler) to make this
+event handler the object that responds to events. This way, you can avoid
+a lot of class derivation, and use instances of the same event handler class (but different
+objects as the same event handler object shouldn't be used more than once) to
+handle events from instances of different widget classes.
+
+If you ever have to call a window's event handler
+manually, use the GetEventHandler function to retrieve the window's event handler and use that
+to call the member function. By default, GetEventHandler returns a pointer to the window itself
+unless an application has redirected event handling using SetEventHandler or PushEventHandler.
+
+One use of PushEventHandler is to temporarily or permanently change the
+behaviour of the GUI. For example, you might want to invoke a dialog editor
+in your application that changes aspects of dialog boxes. You can
+grab all the input for an existing dialog box, and edit it 'in situ',
+before restoring its behaviour to normal. So even if the application
+has derived new classes to customize behaviour, your utility can indulge
+in a spot of body-snatching. It could be a useful technique for on-line
+tutorials, too, where you take a user through a serious of steps and
+don't want them to diverge from the lesson. Here, you can examine the events
+coming from buttons and windows, and if acceptable, pass them through to
+the original event handler. Use PushEventHandler/PopEventHandler
+to form a chain of event handlers, where each handler processes a different
+range of events independently from the other handlers.
+
+
+
+@subsection overview_events_winid Window Identifiers
+
+Window identifiers are integers, and are used to
+uniquely determine window identity in the event system (though you can use it
+for other purposes). In fact, identifiers do not need to be unique
+across your entire application as long they are unique within the
+particular context you're interested in, such as a frame and its children. You
+may use the @c wxID_OK identifier, for example, on any number of dialogs
+as long as you don't have several within the same dialog.
+
+If you pass @c wxID_ANY to a window constructor, an identifier will be
+generated for you automatically by wxWidgets. This is useful when you don't
+care about the exact identifier either because you're not going to process the
+events from the control being created or because you process the events
+from all controls in one place (in which case you should specify @c wxID_ANY
+in the event table or wxEvtHandler::Bind call
+as well). The automatically generated identifiers are always negative and so
+will never conflict with the user-specified identifiers which must be always
+positive.
+
+See @ref page_stdevtid for the list of standard identifiers available.
+You can use wxID_HIGHEST to determine the number above which it is safe to
+define your own identifiers. Or, you can use identifiers below wxID_LOWEST.
+Finally, you can allocate identifiers dynamically using wxNewId() function too.
+If you use wxNewId() consistently in your application, you can be sure that
+your identifiers don't conflict accidentally.
+
+
+@subsection overview_events_custom_generic Generic Event Table Macros
+
+@beginTable
+@row2col{EVT_CUSTOM(event\, id\, func),
+        Allows you to add a custom event table
+        entry by specifying the event identifier (such as wxEVT_SIZE),
+        the window identifier, and a member function to call.}
+@row2col{EVT_CUSTOM_RANGE(event\, id1\, id2\, func),
+        The same as EVT_CUSTOM, but responds to a range of window identifiers.}
+@row2col{EVT_COMMAND(id\, event\, func),
+        The same as EVT_CUSTOM, but expects a member function with a
+        wxCommandEvent argument.}
+@row2col{EVT_COMMAND_RANGE(id1\, id2\, event\, func),
+        The same as EVT_CUSTOM_RANGE, but
+        expects a member function with a wxCommandEvent argument.}
+@row2col{EVT_NOTIFY(event\, id\, func),
+        The same as EVT_CUSTOM, but
+        expects a member function with a wxNotifyEvent argument.}
+@row2col{EVT_NOTIFY_RANGE(event\, id1\, id2\, func),
+        The same as EVT_CUSTOM_RANGE, but
+        expects a member function with a wxNotifyEvent argument.}
+@endTable
+
+
+
+@subsection overview_events_list List of wxWidgets events
+
+For the full list of event classes, please see the
+@ref group_class_events "event classes group page".
+
+
+*/
+