X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/8cc208e39f61bca01cc23c339843891f099d47c5..b5fe7ca67bf3121959a0b5a59afd00c1708f2f03:/interface/wx/event.h

diff --git a/interface/wx/event.h b/interface/wx/event.h
index 0be6ec0a8e..548ceffb06 100644
--- a/interface/wx/event.h
+++ b/interface/wx/event.h
@@ -333,7 +333,7 @@ public:
     @library{wxbase}
     @category{events}
 
-    @see @ref overview_events_processing
+    @see @ref overview_events_processing, wxEventBlocker, wxEventLoopBase
 */
 class wxEvtHandler : public wxObject
 {
@@ -533,7 +533,32 @@ public:
         @see wxWindow::HandleWindowEvent
     */
     bool SafelyProcessEvent(wxEvent& event);
+    
+    /**
+        Processes the pending events previously queued using QueueEvent() or 
+        AddPendingEvent(); you must call this function only if you are sure
+        there are pending events for this handler, otherwise a @c wxCHECK
+        will fail.
+        
+        The real processing still happens in ProcessEvent() which is called by this
+        function.
+        
+        Note that this function needs a valid application object (see 
+        wxAppConsole::GetInstance()) because wxApp holds the list of the event
+        handlers with pending events and this function manipulates that list.
+    */
+    void ProcessPendingEvents();
 
+    /**
+        Deletes all events queued on this event handler using QueueEvent() or
+        AddPendingEvent().
+        
+        Use with care because the events which are deleted are (obviously) not
+        processed and this may have unwanted consequences (e.g. user actions events
+        will be lost).
+    */
+    void DeletePendingEvents();
+    
     /**
         Searches the event table, executing an event handler function if an appropriate
         one is found.
@@ -555,6 +580,9 @@ public:
 
                  If a suitable function is called but calls wxEvent::Skip, this
                  function will fail, and searching will continue.
+                 
+         @todo this function in the header is listed as an "implementation only" function;
+               are we sure we want to document it?
 
         @see ProcessEvent()
     */
@@ -3683,9 +3711,8 @@ wxEventType wxNewEventType();
  */
 #define wxEVENT_HANDLER_CAST(functype, func) (&func)
 
-//@{
 /**
-    These macros are used to define event table macros for handling custom
+    This macro is used to define event table macros for handling custom
     events.
 
     Example of use:
@@ -3713,20 +3740,28 @@ wxEventType wxNewEventType();
         The event type to handle.
     @param id
         The identifier of events to handle.
-    @param id1
-        The first identifier of the range.
-    @param id2
-        The second identifier of the range.
     @param fn
         The event handler method.
  */
-#define wx__DECLARE_EVT2(evt, id1, id2, fn) \
-    DECLARE_EVENT_TABLE_ENTRY(evt, id1, id2, fn, NULL),
 #define wx__DECLARE_EVT1(evt, id, fn) \
     wx__DECLARE_EVT2(evt, id, wxID_ANY, fn)
+
+/**
+    Generalized version of the wx__DECLARE_EVT1() macro taking a range of
+    IDs instead of a single one.
+    Argument @a id1 is the first identifier of the range, @a id2 is the
+    second identifier of the range.
+*/
+#define wx__DECLARE_EVT2(evt, id1, id2, fn) \
+    DECLARE_EVENT_TABLE_ENTRY(evt, id1, id2, fn, NULL),
+
+/**
+    Simplified version of the wx__DECLARE_EVT1() macro, to be used when the
+    event type must be handled regardless of the ID associated with the
+    specific event instances.
+*/
 #define wx__DECLARE_EVT0(evt, fn) \
     wx__DECLARE_EVT1(evt, wxID_ANY, fn)
-//@}
 
 
 /**