+@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
projects / wxWidgets.git / commitdiff
