-/////////////////////////////////////////////////////////////////////////////
-// Name: eventhandling.h
-// Purpose: topic overview
-// Author: wxWidgets team
-// RCS-ID: $Id$
-// Licence: wxWindows license
-/////////////////////////////////////////////////////////////////////////////
-
-/**
-
-@page overview_eventhandling Event Handling
-
-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_prog
-@li @ref overview_eventhandling_pluggable
-@li @ref overview_eventhandling_winid
-@li @ref overview_eventhandling_custom
-@li @ref overview_eventhandling_macros
-
-
-<hr>
-
-
-@section overview_eventhandling_introduction Introduction
-
-There are two principal ways to handle events in wxWidgets. One of them uses
-<em>event table</em> macros and allows to define the connection between events
-and their handlers only statically, i.e. during program compilation. The other
-one uses wxEvtHandler::Connect() call and can be used to connect, and
-disconnect, the handlers dynamically, i.e. during run-time depending on some
-conditions. It also allows directly connecting the events of one object to a
-handler method in another object while the static event tables can only handle
-events in the object where they are defined so using Connect() is more flexible
-than using the event tables. On the other hand, event tables are more succinct
-and centralize all event handlers connection in one place. You can either
-choose a single approach which you find preferable or freely combine both
-methods in your program in different classes or even in one and the same class,
-although this is probably sufficiently confusing to be a bad idea.
-
-But before you make this choice, let us discuss these two ways in some more
-details: in the next section we provide a short introduction to handling the
-events using the event tables, please see @ref overview_eventhandling_connect
-for the discussion of Connect().
-
-@section overview_eventhandling_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 thing to do is to define one or more <em>event handlers</em>. They
-are just simple (non-virtual) methods of the class which take as a parameter a
-reference to an object of wxEvent-derived class and have no return value (any
-return information is passed via the argument, which is why it is non-const).
-You also need to insert a macro
-
-@code
-DECLARE_EVENT_TABLE()
-@endcode
-
-somewhere in the class declaration. It doesn't matter where does it occur but
-it's customary to put it at the end of it because the macro changes the access
-type internally and so it's safest if there is nothing that follows it. So the
-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 be private, in particular they don't need at
- // all to be public
- void OnExit(wxCommandEvent& event);
- void OnButton1(wxCommandEvent& event);
- void OnSize(wxSizeEvent& event);
-
- // it's common to call the event handlers OnSomething() but there is no
- // obligation to it, this one is an event handler too:
- void DoTest(wxCommandEvent& event);
-
- DECLARE_EVENT_TABLE()
-};
-@endcode
-
-Next the event table must be defined and, as any definition, it must be placed
-in an implementation file to tell. The event table tells wxWidgets how to map
-events to member functions and in our example it could look like this:
-
-@code
-BEGIN_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)
-END_EVENT_TABLE()
-@endcode
-
-Notice that you must mention a method you want to use for the event handling in
-the event table definition, just defining it in MyFrame class is @e not enough.
-
-Let us now look at the details of this definition: the first line means that we
-are defining the event table for MyFrame class and that its base class is
-wxFrame, so events not processed by MyFrame will, by default, be handled to
-wxFrame. The next four lines define connections of individual events to their
-handlers: the first two of them map menu commands from the items with the
-identifiers specified as the first macro parameter to two different member
-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 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. And when controls get more
-complicated, more specific wxCommandEvent-derived event classes providing
-additional control-specific information can be used, such as wxTreeEvent for
-events from wxTreeCtrl windows.
-
-In the simplest possible case an event handler may not use the @c event
-parameter at all, e.g.
-
-@code
-void MyFrame::OnExit(wxCommandEvent&)
-{
- // 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.
-
-
-@section overview_eventhandling_connect Dynamic Event Handling
-
-As with the event tables, you need to decide in which class do you intend to
-handle the events first and, also as before, this class must still derive from
-wxEvtHandler (usually indirectly via wxWindow), see the declaration of MyFrame
-in the previous section. However the similarities end here and both the syntax
-and the possibilities of this way of handling events in this way are rather
-different.
-
-Let us start by looking at the syntax: the first obvious difference is that you
-don't need to use neither @c DECLARE_EVENT_TABLE() nor @c BEGIN_EVENT_TABLE and
-associated macros any more. Instead, in any place in your code, but usually in
-the code of the class defining the handlers itself (and definitely not in the
-global scope as with the event tables), you should call its Connect() method
-like this:
-
-@code
-MyFrame::MyFrame(...)
-{
- Connect(wxID_EXIT, wxEVT_COMMAND_MENU_SELECTED,
- wxCommandEventHandler(MyFrame::OnExit));
-}
-@endcode
-
-This class should be self-explanatory except for wxCommandEventHandler part:
-this is a macro which ensures that the method is of correct type by using
-static_cast in the same way as event table macros do it inside them.
-
-Now let us describe the semantic differences:
-<ul>
- <li>
- Event handlers can be connected at any moment, e.g. it's possible to do
- some initialization first and only connect 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 Connect() they
- simply won't be called at all if it wasn't.
- </li>
-
- <li>
- As a slight extension of the above, the handlers can also be
- Disconnect()-ed at any time. And maybe later reconnected again. Of
- course, it's also possible to emulate this behaviour with the classic
- static (i.e. connected 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 connected handlers requires
- less code and is also usually more clear.
- </li>
-
- <li>
- Also notice that you must derive a class inherited from, say,
- wxTextCtrl even if you don't want to modify the control behaviour at
- all but just want to handle some of its events. This is especially
- inconvenient when the control is loaded from the XRC. Connecting the
- event handler dynamically bypasses the need for this unwanted
- sub-classing.
- </li>
-
- <li>
- Last but very, very far from least is the possibility to connect an
- event of some object to a method of another object. This is impossible
- to do with event tables because there is no possibility to specify the
- object to dispatch the event to so it necessarily needs to be sent to
- the same object which generated the event. Not so with Connect() which
- has an optional @c eventSink parameter which can be used to specify the
- object which will handle the event. Of course, in this case the method
- being connected must belong to the class which is the type of the
- @c eventSink object! To give a quick example, people often want to catch
- 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 upwards 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
- which 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->Connect(wxID_ANY, wxEVT_LEAVE_WINDOW,
- wxMouseEventHandler(MyFrame::OnMouseLeave),
- NULL, // unused extra data parameter
- this); // this indicates the object to connect to
- }
- @endcode
- will work exactly as expected. Note that you can get the object which
- generated the event -- and which is not the same as the frame -- via
- wxEvent::GetEventObject() method of @c event argument passed to the
- event handler.
- <li>
-</ul>
-
-To summarize, using Connect() 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_eventhandling_processing How Events are Processed
-
-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.
-
-It may be noted that wxWidgets' event processing system implements something
-very close to virtual methods in normal C++, i.e. it is possible to alter
-the behaviour of a class by overriding its event handling functions. In
-many cases this works even for changing the behaviour of native controls.
-
-For example it is possible to filter out a number of key events sent by the
-system to a native text control by overriding wxTextCtrl and defining a
-handler for key events using EVT_KEY_DOWN. This would indeed prevent
-any key events from being sent to the native control - which might not be
-what is desired. In this case the event handler function has to call Skip()
-so as to indicate that the search for the event handler should continue.
-
-To summarize, instead of explicitly calling the base class version as you
-would have done with C++ virtual functions (i.e. @e wxTextCtrl::OnChar()),
-you should instead call wxEvent::Skip.
-
-In practice, this would look like this if the derived text control only
-accepts 'a' to 'z' and 'A' to 'Z':
-
-@code
-void MyTextCtrl::OnChar(wxKeyEvent& event)
-{
- if ( isalpha( event.KeyCode() ) )
- {
- // key code is within legal range. we call event.Skip() so the
- // event can be processed either in the base wxWidgets class
- // or the native control.
-
- event.Skip();
- }
- else
- {
- // illegal key hit. we don't call event.Skip() so the
- // event is not processed anywhere else.
-
- wxBell();
- }
-}
-@endcode
-
-The normal order of event table searching by ProcessEvent is as follows:
-
-@li If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled)
- the function skips to step (6).
-@li If the object is a wxWindow, @b ProcessEvent is recursively called on the window's
- wxValidator. If this returns @true, the function exits.
-@li @b SearchEventTable is called for this event handler. If this fails, the base
- class table is tried, and so on until no more tables exist or an appropriate
- function was found, in which case the function exits.
-@li The search is applied down the entire chain of event handlers (usually the chain has
- a length of one). If this succeeds, the function exits.
-@li If the object is a wxWindow and the event is set to set to propagate (in the library only
- wxCommandEvent based events are set to propagate), @b ProcessEvent is recursively applied
- to the parent window's event handler. If this returns @true, the function exits.
-@li Finally, @b ProcessEvent is called on the wxApp object.
-
-<b>Pay close attention to Step 5</b>. People often overlook or get
-confused by this powerful feature of the wxWidgets event processing
-system. To put it a different way, events set to propagate
-(see wxEvent::ShouldPropagate)
-(most likely derived either directly or indirectly from wxCommandEvent)
-will travel up the containment hierarchy from child to parent until the
-maximal propagation level is reached or an event handler is found that
-doesn't call @c event.Skip().
-
-Finally, there is another additional complication (which, in fact, simplifies
-life of wxWidgets programmers significantly): when propagating the command
-events upwards to the parent window, the event propagation stops when it
-reaches the parent dialog, if any. This means that you don't risk to get
-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 very difficult, if not impossible, to track down all the dialogs which
-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 wxWindow::SetExtraStyle(wxWS_EX_BLOCK_EVENTS)
-explicitly to prevent the events from being propagated beyond the given window
-or unset this flag for the dialogs which 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 and/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.
-
-Note that your application may wish to override ProcessEvent to redirect processing of
-events. This is done in the document/view framework, for example, to allow event handlers
-to be defined in the document or view. To test for command events (which will probably
-be the only events you wish to redirect), you may use wxEvent::IsCommandEvent for efficiency,
-instead of using the slower run-time type system.
-
-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 which will 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
-
-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.
-
-
-@section overview_eventhandling_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.
-
-
-
-@section overview_eventhandling_pluggable Pluggable Event Handlers
-
-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.
-
-
-
-@section overview_eventhandling_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 just so long as they are unique within a
-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 so
-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 at all 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::Connect 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 availabel.
-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 to.
-If you use wxNewId() consistently in your application, you can be sure that
-the 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 ID which
-is given to the event type @e at runtime which 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 @b const wxEventType.
-
-In order to define a new event type, there are principally two choices.
-One is to define a entirely new event class (typically deriving from
-wxEvent or wxCommandEvent.
-
-The other is to use the existing event classes and give them an new event
-type. You'll have to define and declare a new event type using either way,
-and this is done using the following macros:
-
-@code
-// in the header of the source file
-BEGIN_DECLARE_EVENT_TYPES()
-DECLARE_EVENT_TYPE(name, value)
-END_DECLARE_EVENT_TYPES()
-
-// in the implementation
-DEFINE_EVENT_TYPE(name)
-@endcode
-
-You can ignore the @e value parameter of the DECLARE_EVENT_TYPE macro
-since it is used only for backwards compatibility with wxWidgets 2.0.x based
-applications where you have to give the event type ID an explicit value.
-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, you can then use one of the generic event table macros
-listed below, without having to define a new macro yourself. This also
-has the advantage that you won't have to define a new wxEvent::Clone()
-method for posting events between threads etc. This could look like this
-in your code:
-
-@code
-DECLARE_EVENT_TYPE(wxEVT_MY_EVENT, -1)
-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 )
-{
- // 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
-
-@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_eventhandling_custom_ownclass Defining Your Own Event Class
-
-Under certain circumstances, it will be required to 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;
-};
-
-DECLARE_EVENT_TYPE( wxEVT_PLOT_ACTION, -1 )
-
-typedef void (wxEvtHandler::*wxPlotEventFunction)(wxPlotEvent&);
-
-#define EVT_PLOT(id, fn) \
- DECLARE_EVENT_TABLE_ENTRY( wxEVT_PLOT_ACTION, id, -1, \
- (wxObjectEventFunction) (wxEventFunction) (wxCommandEventFunction) (wxNotifyEventFunction) \
- wxStaticCastEvent( wxPlotEventFunction, &fn ), (wxObject *) NULL ),
-
-
-// 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
-
-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 vs programmatically generated events' paragraph
- of the 'Event handling overview' with the list of the functions which break
- that rule).
-
-*/
-
+/////////////////////////////////////////////////////////////////////////////\r
+// Name: eventhandling.h\r
+// Purpose: topic overview\r
+// Author: wxWidgets team\r
+// RCS-ID: $Id$\r
+// Licence: wxWindows license\r
+/////////////////////////////////////////////////////////////////////////////\r
+\r
+/**\r
+\r
+@page overview_eventhandling Event Handling\r
+\r
+Classes: wxEvtHandler, wxWindow, wxEvent\r
+\r
+@li @ref overview_eventhandling_introduction\r
+@li @ref overview_eventhandling_eventtables\r
+@li @ref overview_eventhandling_connect\r
+@li @ref overview_eventhandling_processing\r
+@li @ref overview_eventhandling_prog\r
+@li @ref overview_eventhandling_pluggable\r
+@li @ref overview_eventhandling_winid\r
+@li @ref overview_eventhandling_custom\r
+@li @ref overview_eventhandling_macros\r
+\r
+\r
+<hr>\r
+\r
+\r
+@section overview_eventhandling_introduction Introduction\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 directly connecting the events of one object to a\r
+handler method in another object while 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 which 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 some more\r
+details: in the next section we provide a short introduction to handling the\r
+events using the event tables, please see @ref overview_eventhandling_connect\r
+for the discussion of Connect().\r
+\r
+@section overview_eventhandling_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 thing to do is to define one or more <em>event handlers</em>. They\r
+are just simple (non-virtual) methods of the class which take as a parameter a\r
+reference to an object of 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 does it occur but\r
+it's customary to put it at the end of it because the macro changes the access\r
+type internally and so it's safest if there is nothing that follows it. So 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 be private, in particular they don't need at\r
+ // all 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 it, 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 any definition, it must be placed\r
+in an implementation file to tell. 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 to\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 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. And 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, e.g.\r
+\r
+@code\r
+void MyFrame::OnExit(wxCommandEvent&)\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
+@section overview_eventhandling_connect Dynamic Event Handling\r
+\r
+As with the event tables, you need to decide in which class do you intend to\r
+handle the events first and, also as before, this class must still 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 this way of handling events in this way are rather\r
+different.\r
+\r
+Let us start by looking at the syntax: the first obvious difference is that you\r
+don't need to use neither @c DECLARE_EVENT_TABLE() nor @c BEGIN_EVENT_TABLE and \r
+associated macros any more. Instead, in any place in your code, but usually in\r
+the code of the class defining the handlers itself (and definitely not in the\r
+global scope as with the event tables), you should call its Connect() method\r
+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 which ensures that the method is of correct type by using\r
+static_cast in the same way as event table macros do it inside them.\r
+\r
+Now let us describe the semantic differences:\r
+<ul>\r
+ <li>\r
+ Event handlers can be connected at any moment, e.g. it's possible to do\r
+ some initialization first and only connect the handlers if and when it\r
+ 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 at all if it wasn't.\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 again. Of\r
+ course, 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 there is no possibility 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 which 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 which 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 upwards 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
+ which 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 which\r
+ generated the event -- and which 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_eventhandling_processing How Events are Processed\r
+\r
+When an event is received from the windowing system, wxWidgets calls\r
+wxEvtHandler::ProcessEvent on the first\r
+event handler object belonging to the window generating the event.\r
+\r
+It may be noted that wxWidgets' event processing system implements something\r
+very close to virtual methods in normal C++, i.e. it is possible to alter\r
+the behaviour of a class by overriding its event handling functions. In\r
+many cases this works even for changing the behaviour of native controls.\r
+\r
+For example it is possible to filter out a number of key events sent by the\r
+system to a native text control by overriding wxTextCtrl and defining a\r
+handler for key events using EVT_KEY_DOWN. This would indeed prevent\r
+any key events from being sent to the native control - which might not be\r
+what is desired. In this case the event handler function has to call Skip()\r
+so as to indicate that the search for the event handler should continue.\r
+\r
+To summarize, instead of explicitly calling the base class version as you\r
+would have done with C++ virtual functions (i.e. @e wxTextCtrl::OnChar()),\r
+you should instead call wxEvent::Skip.\r
+\r
+In practice, this would look like this if the derived text control only\r
+accepts 'a' to 'z' and 'A' to 'Z':\r
+\r
+@code\r
+void MyTextCtrl::OnChar(wxKeyEvent& event)\r
+{\r
+ if ( isalpha( event.KeyCode() ) )\r
+ {\r
+ // key code is within legal range. we call event.Skip() so the\r
+ // event can be processed either in the base wxWidgets class\r
+ // or the native control.\r
+\r
+ event.Skip();\r
+ }\r
+ else\r
+ {\r
+ // illegal key hit. we don't call event.Skip() so the\r
+ // event is not processed anywhere else.\r
+\r
+ wxBell();\r
+ }\r
+}\r
+@endcode\r
+\r
+The normal order of event table searching by ProcessEvent is as follows:\r
+<ol>\r
+<li> If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled)\r
+ the function skips to step (6).\r
+<li> If the object is a wxWindow, @b ProcessEvent is recursively called on the window's\r
+ wxValidator. If this returns @true, the function exits.\r
+<li> @b SearchEventTable is called for this event handler. If this fails, the base\r
+ class table is tried, and so on until no more tables exist or an appropriate\r
+ function was found, in which case the function exits.\r
+<li> The search is applied down the entire chain of event handlers (usually the chain has\r
+ a length of one). If this succeeds, the function exits.\r
+<li> If the object is a wxWindow and the event is set to set to propagate (in the library only\r
+ wxCommandEvent based events are set to propagate), @b ProcessEvent is recursively applied\r
+ to the parent window's event handler. If this returns @true, the function exits.\r
+<li> Finally, @b ProcessEvent is called on the wxApp object.\r
+</ol>\r
+<b>Pay close attention to Step 5</b>. People often overlook or get\r
+confused by this powerful feature of the wxWidgets event processing\r
+system. To put it a different way, events set to propagate\r
+(see wxEvent::ShouldPropagate)\r
+(most likely derived either directly or indirectly from wxCommandEvent)\r
+will travel up the containment hierarchy from child to parent until the\r
+maximal propagation level is reached or an event handler is found that\r
+doesn't call @c event.Skip().\r
+\r
+Finally, there is another additional complication (which, in fact, simplifies\r
+life of wxWidgets programmers significantly): when propagating the command\r
+events upwards to the parent window, the event propagation stops when it\r
+reaches the parent dialog, if any. This means that you don't risk to get\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 very difficult, if not impossible, to track down all the dialogs which\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 which 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 and/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
+Note that your application may wish to override ProcessEvent to redirect processing of\r
+events. This is done in the document/view framework, for example, to allow event handlers\r
+to be defined in the document or view. To test for command events (which will probably\r
+be the only events you wish to redirect), you may use wxEvent::IsCommandEvent for efficiency,\r
+instead of using the slower run-time type system.\r
+\r
+As mentioned above, only command events are recursively applied to the parents event\r
+handler in the library itself. As this quite often causes confusion for users,\r
+here is a list of system events which will NOT get sent to the 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_eventhandling_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
+@section overview_eventhandling_pluggable Pluggable Event Handlers\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
+@section overview_eventhandling_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 just so long as they are unique within a\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 so\r
+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 at all 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 to.\r
+If you use wxNewId() consistently in your application, you can be sure that\r
+the your identifiers don't conflict accidentally.\r
+\r
+\r
+@section overview_eventhandling_custom Custom Event Summary\r
+\r
+@subsection overview_eventhandling_custom_general General approach\r
+\r
+Since version 2.2.x of wxWidgets, each event type is identified by ID which\r
+is given to the event type @e at runtime which 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). This\r
+event type ID is stored in a struct of type @b const wxEventType.\r
+\r
+In order to define a new event type, there are principally two choices.\r
+One is to define a 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 an new event\r
+type. You'll have to define and declare a new event type using either way,\r
+and this is done using the following macros:\r
+\r
+@code\r
+// in the header of the source file\r
+BEGIN_DECLARE_EVENT_TYPES()\r
+DECLARE_EVENT_TYPE(name, value)\r
+END_DECLARE_EVENT_TYPES()\r
+\r
+// in the implementation\r
+DEFINE_EVENT_TYPE(name)\r
+@endcode\r
+\r
+You can ignore the @e value parameter of the DECLARE_EVENT_TYPE macro\r
+since it is used only for backwards compatibility with wxWidgets 2.0.x based\r
+applications where you have to give the event type ID an explicit value.\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_eventhandling_custom_existing Using Existing Event Classes\r
+\r
+If you just want to use a wxCommandEvent with\r
+a new event type, you can then use one of the generic event table macros\r
+listed below, without having to define a new macro yourself. This also\r
+has the advantage that you won't have to define a new wxEvent::Clone()\r
+method for posting events between threads etc. This could look like this\r
+in your code:\r
+\r
+@code\r
+DECLARE_EVENT_TYPE(wxEVT_MY_EVENT, -1)\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 )\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
+ // Give it some contents\r
+ event.SetText( wxT("Hallo") );\r
+ // Send it\r
+ GetEventHandler()->ProcessEvent( event );\r
+}\r
+@endcode\r
+\r
+\r
+@subsection overview_eventhandling_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_eventhandling_custom_ownclass Defining Your Own Event Class\r
+\r
+Under certain circumstances, it will be required to 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
+DECLARE_EVENT_TYPE( wxEVT_PLOT_ACTION, -1 )\r
+\r
+typedef void (wxEvtHandler::*wxPlotEventFunction)(wxPlotEvent&);\r
+\r
+#define EVT_PLOT(id, fn) \\r
+ DECLARE_EVENT_TABLE_ENTRY( wxEVT_PLOT_ACTION, id, -1, \\r
+ (wxObjectEventFunction) (wxEventFunction) (wxCommandEventFunction) (wxNotifyEventFunction) \\r
+ wxStaticCastEvent( wxPlotEventFunction, &fn ), (wxObject *) NULL ),\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
+// 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_eventhandling_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
+@todo for all controls state clearly when calling a member function results in an \r
+ event being generated and when it doesn't (possibly updating also the \r
+ 'Events generated by the user vs programmatically generated events' paragraph \r
+ of the 'Event handling overview' with the list of the functions which break \r
+ that rule).\r
+\r
+*/\r
+\r
projects / wxWidgets.git / blobdiff