From 6496345c33824373fdb8cf7de04a43197fa0341c Mon Sep 17 00:00:00 2001 From: Francesco Montorsi Date: Tue, 2 Dec 2008 16:34:09 +0000 Subject: [PATCH] document the main event table macros, wxEventType, wxNewEventType; create a new group_funcmacro_events group git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@57070 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/doxygen/groups/funcmacro_events.h | 17 +++++++ docs/doxygen/overviews/eventhandling.h | 2 +- interface/wx/event.h | 70 ++++++++++++++++++++++---- 3 files changed, 78 insertions(+), 11 deletions(-) create mode 100644 docs/doxygen/groups/funcmacro_events.h diff --git a/docs/doxygen/groups/funcmacro_events.h b/docs/doxygen/groups/funcmacro_events.h new file mode 100644 index 0000000000..e12be48f99 --- /dev/null +++ b/docs/doxygen/groups/funcmacro_events.h @@ -0,0 +1,17 @@ +///////////////////////////////////////////////////////////////////////////// +// Name: funcmacro_events.h +// Purpose: Event functions and macro group doc +// Author: wxWidgets team +// RCS-ID: $Id$ +// Licence: wxWindows license +///////////////////////////////////////////////////////////////////////////// + +/** + +@defgroup group_funcmacro_events Events +@ingroup group_funcmacro + +Below are a number of functions/macros used with wxWidgets event-handling system. + +*/ + diff --git a/docs/doxygen/overviews/eventhandling.h b/docs/doxygen/overviews/eventhandling.h index 1edf26142b..8c6511a0c0 100644 --- a/docs/doxygen/overviews/eventhandling.h +++ b/docs/doxygen/overviews/eventhandling.h @@ -128,7 +128,7 @@ 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 +The @c 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. diff --git a/interface/wx/event.h b/interface/wx/event.h index b10c6df976..5963edae10 100644 --- a/interface/wx/event.h +++ b/interface/wx/event.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: event.h -// Purpose: interface of wxEventHandler, wxEventBlocker and many +// Purpose: interface of wxEvtHandler, wxEventBlocker and many // wxEvent-derived classes // Author: wxWidgets team // RCS-ID: $Id$ @@ -8,7 +8,6 @@ ///////////////////////////////////////////////////////////////////////////// - /** @class wxEvent @@ -256,13 +255,13 @@ public: @class wxEvtHandler A class that can handle events from the windowing system. - wxWindow (and therefore all window classes) are derived from this class. + wxWindow is (and therefore all window classes are) derived from this class. When events are received, wxEvtHandler invokes the method listed in the event table using itself as the object. When using multiple inheritance - it is imperative that the wxEvtHandler(-derived) class be the first - class inherited such that the "this" pointer for the overall object - will be identical to the "this" pointer for the wxEvtHandler portion. + it is imperative that the wxEvtHandler(-derived) class is the first + class inherited such that the @c this pointer for the overall object + will be identical to the @c this pointer of the wxEvtHandler portion. @library{wxbase} @category{events} @@ -522,13 +521,13 @@ public: (such as a new control) where you define new event types, as opposed to allowing the user to override virtual functions. - An instance where you might actually override the ProcessEvent function is where + An instance where you might actually override the ProcessEvent() function is where you want to direct event processing to event handlers not normally noticed by wxWidgets. For example, in the document/view architecture, documents and views - are potential event handlers. When an event reaches a frame, ProcessEvent will + are potential event handlers. When an event reaches a frame, ProcessEvent() will need to be called on the associated document and view in case event handler functions are associated with these objects. The property classes library (wxProperty) also - overrides ProcessEvent for similar reasons. + overrides ProcessEvent() for similar reasons. The normal order of event table searching is as follows: -# If the object is disabled (via a call to wxEvtHandler::SetEvtHandlerEnabled) @@ -588,6 +587,7 @@ public: @li The event type matches, and @li the identifier or identifier range matches, or the event table entry's identifier is zero. + If a suitable function is called but calls wxEvent::Skip, this function will fail, and searching will continue. @@ -3268,9 +3268,59 @@ public: // Global functions/macros // ============================================================================ -/** @ingroup group_funcmacro_misc */ +/** @ingroup group_funcmacro_events */ //@{ +/** + Each wxEvent-derived class has an @e event-type associated. + See the macro DEFINE_EVENT_TYPE() for more info. + + @see @ref overview_eventhandling_custom +*/ +typedef int wxEventType; + +/** + Initializes a new event type using wxNewEventType(). +*/ +#define DEFINE_EVENT_TYPE(name) const wxEventType name = wxNewEventType(); + +/** + Generates a new unique event type. +*/ +wxEventType wxNewEventType(); + +/** + Use this macro inside a class declaration to declare a @e static event table + for that class. + + In the implementation file you'll need to use the BEGIN_EVENT_TABLE() + and the END_EVENT_TABLE() macros, plus some additional @c EVT_xxx macro + to capture events. + + @see @ref overview_eventhandling_eventtables +*/ +#define DECLARE_EVENT_TABLE() + +/** + Use this macro in a source file to start listing @e static event handlers + for a specific class. + + Use END_EVENT_TABLE() to terminate the event-declaration block. + + @see @ref overview_eventhandling_eventtables +*/ +#define BEGIN_EVENT_TABLE(theClass, baseClass) + +/** + Use this macro in a source file to end listing @e static event handlers + for a specific class. + + Use BEGIN_EVENT_TABLE() to start the event-declaration block. + + @see @ref overview_eventhandling_eventtables +*/ +#define END_EVENT_TABLE() + /** In a GUI application, this function posts @a event to the specified @e dest object using wxEvtHandler::AddPendingEvent(). -- 2.45.2