X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/6496345c33824373fdb8cf7de04a43197fa0341c..de8fe8ca3db62aa69a00f9547367c223ba59a23e:/docs/doxygen/overviews/eventhandling.h
diff --git a/docs/doxygen/overviews/eventhandling.h b/docs/doxygen/overviews/eventhandling.h
index 8c6511a0c0..de7ba61374 100644
--- a/docs/doxygen/overviews/eventhandling.h
+++ b/docs/doxygen/overviews/eventhandling.h
@@ -8,27 +8,57 @@
/**
-@page overview_eventhandling Event Handling
+@page overview_events Events and Event Handling
-Classes: wxEvtHandler, wxWindow, wxEvent
+Related classes: wxEvtHandler, wxWindow, wxEvent
-@li @ref overview_eventhandling_introduction
-@li @ref overview_eventhandling_eventtables
-@li @ref overview_eventhandling_connect
-@li @ref overview_eventhandling_processing
-@li @ref overview_eventhandling_propagation
-@li @ref overview_eventhandling_virtual
-@li @ref overview_eventhandling_prog
-@li @ref overview_eventhandling_pluggable
-@li @ref overview_eventhandling_winid
-@li @ref overview_eventhandling_custom
-@li @ref overview_eventhandling_macros
+@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
-@section overview_eventhandling_introduction Introduction
+@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:
+ - Event type: 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.
+ - Event class 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.
+ - Event source: 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
event table macros and allows you to define the connection between events
@@ -46,10 +76,10 @@ 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_eventhandling_connect
+events using the event tables. Please see @ref overview_events_connect
for the discussion of Connect().
-@section overview_eventhandling_eventtables Event Handling with Event Tables
+@subsection overview_events_eventtables Event Handling with Event Tables
To use an event table you must first decide in which class you wish to
handle the events. The only requirement imposed by wxWidgets is that this class
@@ -175,7 +205,7 @@ wxEvent-derived classes in the discussion of each control generating these
events.
-@section overview_eventhandling_connect Dynamic Event Handling
+@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
@@ -184,7 +214,7 @@ 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.
Let us start by looking at the syntax: the first obvious difference is that you
-need not use @c DECLARE_EVENT_TABLE() nor @c BEGIN_EVENT_TABLE and the
+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:
@@ -284,7 +314,7 @@ need this extra power. On the other hand, event tables are still perfectly fine
in simple situations where this extra flexibility is not needed.
-@section overview_eventhandling_processing How Events are Processed
+@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
@@ -331,10 +361,20 @@ doesn't count as having handled the event and the search continues):
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. This chain can be formed
- using wxEvtHandler::SetNextHandler() or wxWindow::PushEventHandler() but
- usually there is no next event handler and chaining event handlers using
- these functions is much less useful now that Connect() exists so this step
- will almost never do anything.
+ 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...).
+ 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 connected event handlers and static
+ event table entries of wxWindow are looked as the last possibility, after
+ all pushed event handlers were tested).
+ Note however that usually there are no wxEvtHandler chains nor wxWindows stacks
+ so this step will usually do anything.
@@ -349,7 +389,7 @@ doesn't count as having handled the event and the search continues):
Finally, i.e., if the event is still not processed, the wxApp object itself
- gets a last chance to process it.
+ (which derives from wxEvtHandler) gets a last chance to process it.
@@ -372,16 +412,15 @@ solution is to only handle the events at the view classes level, and not in the
document or document manager classes
-@section overview_eventhandling_propagation How Events Propagate Upwards
+@subsection overview_events_propagation How Events Propagate Upwards
-As mentioned in the previous section, 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).
+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
@@ -402,32 +441,10 @@ 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
+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.
-
-As mentioned above, only command events are recursively applied to the parents
-event handler in the library itself. As this quite often causes confusion for
-users, here is a list of system events that will @em not get sent to the
-parent's event handler:
-
-@li wxEvent: The event base class
-@li wxActivateEvent: A window or application activation event
-@li wxCloseEvent: A close window or end session event
-@li wxEraseEvent: An erase background event
-@li wxFocusEvent: A window focus event
-@li wxKeyEvent: A keypress event
-@li wxIdleEvent: An idle event
-@li wxInitDialogEvent: A dialog initialisation event
-@li wxJoystickEvent: A joystick event
-@li wxMenuEvent: A menu event
-@li wxMouseEvent: A mouse event
-@li wxMoveEvent: A move event
-@li wxPaintEvent: A paint event
-@li wxQueryLayoutInfoEvent: Used to query layout information
-@li wxSetCursorEvent: Used for special cursor processing based on current mouse position
-@li wxSizeEvent: A size event
-@li wxScrollWinEvent: A scroll event sent by a scrolled window (not a scroll bar)
-@li wxSysColourChangedEvent: A system colour change 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
@@ -436,7 +453,159 @@ will have to be written that will override ProcessEvent() in order to pass
all events (or any selection of them) to the parent window.
-@section overview_eventhandling_virtual Event Handlers vs Virtual Methods
+@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.
+
+
+@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
+BEGIN_EVENT_TABLE(MyFrame, wxFrame)
+ EVT_MENU (wxID_EXIT, MyFrame::OnExit)
+ ...
+ EVT_COMMAND (ID_MY_WINDOW, MY_EVENT, MyFrame::OnMyEvent)
+END_EVENT_TABLE()
+
+void MyFrame::OnMyEvent(wxCommandEvent& event)
+{
+ // do something
+ wxString text = event.GetText();
+}
+
+// example of code handling the event with Connect():
+MyFrame::MyFrame()
+{
+ Connect(ID_MY_WINDOW, MY_EVENT, &MyFrame::OnMyEvent);
+}
+
+// example of code generating the event
+void MyWindow::SendEvent()
+{
+ wxCommandEvent event(MY_EVENT, GetId());
+ event.SetEventObject(this);
+
+ // Give it some contents
+ event.SetText("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 sing 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 Connect() 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):
+BEGIN_EVENT_TABLE(MyFrame, wxFrame)
+ EVT_PLOT(ID_MY_WINDOW, MyFrame::OnPlot)
+END_EVENT_TABLE()
+
+MyFrame::MyFrame()
+{
+ Connect(ID_MY_WINDOW, MY_PLOT_CLICKED, &MyFrame::OnPlot);
+}
+
+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
@@ -462,7 +631,7 @@ They should always be non-virtual and usually private (as there is no need to
make them public) methods of a wxEvtHandler-derived class.
-@section overview_eventhandling_prog User Generated Events vs Programmatically Generated Events
+@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
@@ -485,7 +654,9 @@ equivalents.
-@section overview_eventhandling_pluggable Pluggable Event Handlers
+@subsection overview_events_pluggable Pluggable Event Handlers
+
+TODO: Probably deprecated, Connect() provides a better way to do this
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,
@@ -517,7 +688,7 @@ range of events independently from the other handlers.
-@section overview_eventhandling_winid Window Identifiers
+@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
@@ -545,81 +716,7 @@ If you use wxNewId() consistently in your application, you can be sure that
your identifiers don't conflict accidentally.
-@section overview_eventhandling_custom Custom Event Summary
-
-@subsection overview_eventhandling_custom_general General approach
-
-Since version 2.2.x of wxWidgets, each event type is identified by an ID
-given to the event type @e at runtime that makes it possible to add
-new event types to the library or application without risking ID clashes
-(two different event types mistakingly getting the same event ID).
-This event type ID is stored in a struct of type const wxEventType.
-
-In order to define a new event type, there are principally two choices.
-One is to define an entirely new event class (typically deriving from
-wxEvent or wxCommandEvent).
-
-The other is to use the existing event classes and give them a new event
-type. You'll have to define and declare a new event type either way
-using the following macros:
-
-@code
-// in the header of the source file
-extern const wxEventType wxEVT_YOUR_EVENT_NAME;
-
-// in the implementation
-DEFINE_EVENT_TYPE(wxEVT_YOUR_EVENT_NAME)
-@endcode
-
-See also the @ref page_samples_event for an example of code
-defining and working with the custom event types.
-
-
-@subsection overview_eventhandling_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. This also has the advantage that you won't have to define a
-new wxEvent::Clone() method for posting events between threads etc.
-
-Example:
-
-@code
-extern const wxEventType wxEVT_MY_EVENT;
-DEFINE_EVENT_TYPE(wxEVT_MY_EVENT)
-
-// user code intercepting the event
-
-BEGIN_EVENT_TABLE(MyFrame, wxFrame)
-EVT_MENU (wxID_EXIT, MyFrame::OnExit)
-// ....
-EVT_COMMAND (ID_MY_WINDOW, wxEVT_MY_EVENT, MyFrame::OnMyEvent)
-END_EVENT_TABLE()
-
-void MyFrame::OnMyEvent( wxCommandEvent& event )
-{
- // do something
- wxString text = event.GetText();
-}
-
-
-// user code sending the event
-
-void MyWindow::SendEvent()
-{
- wxCommandEvent event( wxEVT_MY_EVENT, GetId() );
- event.SetEventObject( this );
-
- // Give it some contents
- event.SetText( wxT("Hallo") );
-
- // Send it
- GetEventHandler()->ProcessEvent( event );
-}
-@endcode
-
-
-@subsection overview_eventhandling_custom_generic Generic Event Table Macros
+@subsection overview_events_custom_generic Generic Event Table Macros
@beginTable
@row2col{EVT_CUSTOM(event\, id\, func),
@@ -643,87 +740,12 @@ void MyWindow::SendEvent()
@endTable
-@subsection overview_eventhandling_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 will also need to define your own
-event table macro (which is quite long). Watch out to put in enough
-casts to the inherited event function. Here is an example:
-
-@code
-// code defining event
-
-class wxPlotEvent: public wxNotifyEvent
-{
-public:
- wxPlotEvent( wxEventType commandType = wxEVT_NULL, int id = 0 );
-
- // accessors
- wxPlotCurve *GetCurve()
- { return m_curve; }
-
- // required for sending with wxPostEvent()
- virtual wxEvent *Clone() const;
-
-private:
- wxPlotCurve *m_curve;
-};
-
-extern const wxEventType wxEVT_PLOT_ACTION;
-typedef void (wxEvtHandler::*wxPlotEventFunction)(wxPlotEvent&);
-
-#define wxPlotEventHandler(func) \
- (wxObjectEventFunction)(wxEventFunction)wxStaticCastEvent(wxPlotEventFunction, &func)
-#define EVT_PLOT(id, fn) \
- wx__DECLARE_EVT1(wxEVT_PLOT_ACTION, id, wxPlotEventHandler(fn))
-
-
-// code implementing the event type and the event class
-
-DEFINE_EVENT_TYPE( wxEVT_PLOT_ACTION )
-
-wxPlotEvent::wxPlotEvent( ... )
-{
- ...
-}
-
-
-// user code intercepting the event
-
-BEGIN_EVENT_TABLE(MyFrame, wxFrame)
-EVT_PLOT (ID_MY_WINDOW, MyFrame::OnPlot)
-END_EVENT_TABLE()
-
-void MyFrame::OnPlot( wxPlotEvent &event )
-{
- wxPlotCurve *curve = event.GetCurve();
-}
-
-
-// user code sending the event
-
-void MyWindow::SendEvent()
-{
- wxPlotEvent event( wxEVT_PLOT_ACTION, GetId() );
- event.SetEventObject( this );
- event.SetCurve( m_curve );
- GetEventHandler()->ProcessEvent( event );
-}
-@endcode
-
-
-@section overview_eventhandling_macros Event Handling Summary
+@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".
-@todo For all controls, state clearly when calling a member function results in
- an event being generated and when it doesn't (possibly updating also the
- 'Events generated by the user versus programmatically-generated events'
- paragraph of the 'Event Handling Overview' with the list of the functions
- that break the rule).
-
*/