/////////////////////////////////////////////////////////////////////////////\r
\r
/**\r
- @page overview_events Events and Event Handling\r
\r
- Related classes: wxEvtHandler, wxWindow, wxEvent\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
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
+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
+More precisely, as said above, all event classes @b not deriving from wxCommandEvent\r
+(see the wxEvent inheritance map) do @b not propagate upward.\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
\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
+As each event is uniquely defined by its event type, defining a custom event\r
+starts with defining a new event type for it. This is done using\r
+wxDEFINE_EVENT() macro. As an event type is a variable, it can also be\r
+declared using wxDECLARE_EVENT() if necessary.\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
+The next thing to do is to decide whether you need to define a custom event\r
+class for events of this type or if you can reuse an existing class, typically\r
+either wxEvent (which doesn't provide any extra information) or wxCommandEvent\r
+(which contains several extra fields and also propagates upwards by default).\r
+Both strategies are described in details below. See also the @ref\r
+page_samples_event for a complete example of code defining and working with the\r
+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
+If you just want to use a wxCommandEvent with a new event type, use one of the\r
+generic event table macros listed below, without having to define a new event\r
+class yourself.\r
\r
Example:\r
\r
@code\r
-extern const wxEventType wxEVT_MY_EVENT;\r
-DEFINE_EVENT_TYPE(wxEVT_MY_EVENT)\r
+// this is typically in a header: it just declares MY_EVENT event type\r
+wxDECLARE_EVENT(MY_EVENT, wxCommandEvent);\r
\r
-// user code intercepting the event\r
+// this is a definition so can't be in a header\r
+wxDEFINE_EVENT(MY_EVENT, wxCommandEvent);\r
\r
+// example of code handling the event with event tables\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
+ EVT_MENU (wxID_EXIT, MyFrame::OnExit)\r
+ ...\r
+ EVT_COMMAND (ID_MY_WINDOW, MY_EVENT, MyFrame::OnMyEvent)\r
END_EVENT_TABLE()\r
\r
-void MyFrame::OnMyEvent( wxCommandEvent& event )\r
+void MyFrame::OnMyEvent(wxCommandEvent& event)\r
{\r
// do something\r
wxString text = event.GetText();\r
}\r
\r
+// example of code handling the event with Connect():\r
+MyFrame::MyFrame()\r
+{\r
+ Connect(ID_MY_WINDOW, MY_EVENT, &MyFrame::OnMyEvent);\r
+}\r
\r
-// user code sending the event\r
-\r
+// example of code generating the event\r
void MyWindow::SendEvent()\r
{\r
- wxCommandEvent event( wxEVT_MY_EVENT, GetId() );\r
- event.SetEventObject( this );\r
+ wxCommandEvent event(MY_EVENT, GetId());\r
+ event.SetEventObject(this);\r
\r
// Give it some contents\r
- event.SetText( wxT("Hallo") );\r
+ event.SetText("Hello");\r
\r
- // Send it\r
- GetEventHandler()->ProcessEvent( event );\r
+ // Do send it\r
+ ProcessWindowEvent(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
+Under certain circumstances, you must define your own event class e.g., for\r
+sending more complex data from one place to another. Apart from defining your\r
+event class, you also need to define your own event table macro if you want to\r
+use event tables for handling events of this type.\r
\r
-@code\r
-// code defining event\r
+Here is an example:\r
\r
-class wxPlotEvent: public wxNotifyEvent\r
+@code\r
+// define a new event class\r
+class MyPlotEvent: public wxEvent\r
{\r
public:\r
- wxPlotEvent( wxEventType commandType = wxEVT_NULL, int id = 0 );\r
+ MyPlotEvent(wxEventType eventType, int winid, const wxPoint& pos)\r
+ : wxEvent(winid, eventType),\r
+ m_pos(pos)\r
+ {\r
+ }\r
\r
// accessors\r
- wxPlotCurve *GetCurve()\r
- { return m_curve; }\r
+ wxPoint GetPoint() const { return m_pos; }\r
\r
- // required for sending with wxPostEvent()\r
- virtual wxEvent *Clone() const;\r
+ // implement the base class pure virtual\r
+ virtual wxEvent *Clone() const { return new MyPlotEvent(*this); }\r
\r
private:\r
- wxPlotCurve *m_curve;\r
+ const wxPoint m_pos;\r
};\r
\r
-extern const wxEventType wxEVT_PLOT_ACTION;\r
-typedef void (wxEvtHandler::*wxPlotEventFunction)(wxPlotEvent&);\r
+// we define a single MY_PLOT_CLICKED event type associated with the class\r
+// above but typically you are going to have more than one event type, e.g. you\r
+// could also have MY_PLOT_ZOOMED or MY_PLOT_PANNED &c -- in which case you\r
+// would just add more similar lines here\r
+wxDEFINE_EVENT(MY_PLOT_CLICKED, MyPlotEvent);\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
+// if you want to support old compilers you need to use some ugly macros:\r
+typedef void (wxEvtHandler::*MyPlotEventFunction)(MyPlotEvent&);\r
+#define MyPlotEventHandler(func) wxEVENT_HANDLER_CAST(MyPlotEventFunction, func)\r
\r
-// code implementing the event type and the event class\r
+// if your code is only built sing reasonably modern compilers, you could just\r
+// do this instead:\r
+#define MyPlotEventHandler(func) (&func)\r
\r
-DEFINE_EVENT_TYPE( wxEVT_PLOT_ACTION )\r
+// finally define a macro for creating the event table entries for the new\r
+// event type\r
+//\r
+// remember that you don't need this at all if you only use Connect() and that\r
+// you can replace MyPlotEventHandler(func) with just &func unless you use a\r
+// really old compiler\r
+#define MY_EVT_PLOT_CLICK(id, func) \\r
+ wx__DECLARE_EVT1(MY_PLOT_CLICKED, id, MyPlotEventHandler(func))\r
\r
-wxPlotEvent::wxPlotEvent( ... )\r
-{\r
- ...\r
-}\r
-\r
-\r
-// user code intercepting the event\r
\r
+// example of code handling the event (you will use one of these methods, not\r
+// both, of course):\r
BEGIN_EVENT_TABLE(MyFrame, wxFrame)\r
-EVT_PLOT (ID_MY_WINDOW, MyFrame::OnPlot)\r
+ EVT_PLOT(ID_MY_WINDOW, MyFrame::OnPlot)\r
END_EVENT_TABLE()\r
\r
-void MyFrame::OnPlot( wxPlotEvent &event )\r
+MyFrame::MyFrame()\r
{\r
- wxPlotCurve *curve = event.GetCurve();\r
+ Connect(ID_MY_WINDOW, MY_PLOT_CLICKED, &MyFrame::OnPlot);\r
}\r
\r
+void MyFrame::OnPlot(MyPlotEvent& event)\r
+{\r
+ ... do something with event.GetPoint() ...\r
+}\r
\r
-// user code sending the event\r
\r
+// example of code generating the event:\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
+ MyPlotEvent event(MY_PLOT_CLICKED, GetId(), wxPoint(...));\r
+ event.SetEventObject(this);\r
+ ProcessWindowEvent(event);\r
}\r
@endcode\r
\r
\r
+\r
@section overview_events_misc Miscellaneous Notes\r
\r
@subsection overview_events_virtual Event Handlers vs Virtual Methods\r
your identifiers don't conflict accidentally.\r
\r
\r
-@subsection overview_events_macros Event Handling Summary\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
+\r
+@subsection overview_events_list List of wxWidgets events\r
\r
For the full list of event classes, please see the\r
@ref group_class_events "event classes group page".\r
projects / wxWidgets.git / blobdiff