+@section overview_events_custom Custom Event Summary\r
+\r
+@subsection overview_events_custom_general General approach\r
+\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
+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 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
+// this is typically in a header: it just declares MY_EVENT event type\r
+wxDECLARE_EVENT(MY_EVENT, wxCommandEvent);\r
+\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, MY_EVENT, MyFrame::OnMyEvent)\r
+END_EVENT_TABLE()\r
+\r
+void MyFrame::OnMyEvent(wxCommandEvent& event)\r
+{\r
+ // do something\r
+ wxString text = event.GetText();\r
+}\r
+\r
+// example of code handling the event with Connect():\r
+MyFrame::MyFrame()\r
+{\r
+ Connect(ID_MY_WINDOW, MY_EVENT, &MyFrame::OnMyEvent);\r
+}\r
+\r
+// example of code generating the event\r
+void MyWindow::SendEvent()\r
+{\r
+ wxCommandEvent event(MY_EVENT, GetId());\r
+ event.SetEventObject(this);\r
+\r
+ // Give it some contents\r
+ event.SetText("Hello");\r
+\r
+ // Do send it\r
+ ProcessWindowEvent(event);\r
+}\r
+@endcode\r
+\r
+\r
+@subsection overview_events_custom_ownclass Defining Your Own Event Class\r
+\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
+Here is an example:\r
+\r
+@code\r
+// define a new event class\r
+class MyPlotEvent: public wxEvent\r
+{\r
+public:\r
+ MyPlotEvent(wxEventType eventType, int winid, const wxPoint& pos)\r
+ : wxEvent(winid, eventType),\r
+ m_pos(pos)\r
+ {\r
+ }\r
+\r
+ // accessors\r
+ wxPoint GetPoint() const { return m_pos; }\r
+\r
+ // implement the base class pure virtual\r
+ virtual wxEvent *Clone() const { return new MyPlotEvent(*this); }\r
+\r
+private:\r
+ const wxPoint m_pos;\r
+};\r
+\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
+\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
+// if your code is only built sing reasonably modern compilers, you could just\r
+// do this instead:\r
+#define MyPlotEventHandler(func) (&func)\r
+\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
+\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
+END_EVENT_TABLE()\r
+\r
+MyFrame::MyFrame()\r
+{\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
+\r
+// example of code generating the event:\r
+void MyWindow::SendEvent()\r
+{\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
projects / wxWidgets.git / blobdiff