add wxAppConsoleBase::DeletePendingEvents and wxEvtHandler::DeletePendingEvents.

Fix wxAppConsoleBase::Suspend/ResumeProcessingOfPendingEvents: locking the mutex does not prevent wxAppConsoleBase::ProcessPendingEvents from running if the mutex was locked from the main thread!

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@59433 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/wx/app.h

@@ -125,15 +125,35 @@ public:
 
     /**
         Process all pending events; it is necessary to call this function to
-        process posted events.
+        process events posted with wxEvtHandler::QueueEvent or wxEvtHandler::AddPendingEvent.
 
-        This happens during each event loop iteration in GUI mode but
+        This happens during each event loop iteration (see wxEventLoopBase) in GUI mode but
         it may be also called directly.
+        
+        Note that this function does not only process the pending events for the wxApp object
+        itself (which derives from wxEvtHandler) but also the pending events for @e any
+        event handler of this application.
+        
+        This function will immediately return and do nothing if SuspendProcessingOfPendingEvents()
+        was called.
     */
     virtual void ProcessPendingEvents();
+    
+    /**
+        Deletes the pending events of all wxEvtHandlers of this application.
+        
+        See wxEvtHandler::DeletePendingEvents() for warnings about deleting the pending
+        events.
+    */
+    void DeletePendingEvents();
 
     /**
         Returns @true if there are pending events on the internal pending event list.
+        
+        Whenever wxEvtHandler::QueueEvent or wxEvtHandler::AddPendingEvent() are
+        called (not only for wxApp itself, but for any event handler of the application!), 
+        the internal wxApp's list of handlers with pending events is updated and this
+        function will return true.
     */
     bool HasPendingEvents() const;
 

interface/wx/event.h

@@ -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()
     */