second part of #10320: move wxApp event handling functions to wxEventLoopBase (in particular move Yield() functions); add backward compatible redirections to wxApp; update docs; remove global lists wxPendingEvents and wxPendingEventsLocker

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

interface/wx/evtloop.h

@@ -18,7 +18,7 @@
     @library{wxbase}
     @category{appmanagement}
 
-    @see wxApp
+    @see wxApp, wxEventLoopActivator
 */
 class wxEventLoopBase
 {
@@ -42,10 +42,9 @@ public:
 
 
     /**
-        Use this to check whether the event loop was successfully created
-        before using it
-     */
-    virtual bool IsOk() const;
+        @name Dispatch and processing
+    */
+    //@{
 
     /**
         Start the event loop, return the exit code when it is finished.
@@ -60,6 +59,21 @@ public:
      */
     virtual int Run() = 0;
 
+    /**
+        Return true if this event loop is currently running.
+
+        Notice that even if this event loop hasn't terminated yet but has just
+        spawned a nested (e.g. modal) event loop, this method would return
+        @false.
+     */
+    bool IsRunning() const;
+
+    /**
+        Use this to check whether the event loop was successfully created
+        before using it
+     */
+    virtual bool IsOk() const;
+
     /**
         Exit from the loop with the given exit code.
      */
@@ -73,13 +87,21 @@ public:
     virtual bool Pending() const = 0;
 
     /**
-        Dispatch a single event.
+        Dispatches the next event in the windowing system event queue.
+        Blocks until an event appears if there are none currently
+        (use Pending() if this is not wanted).
 
-        If there are currently no events in the queue, blocks until an event
-        becomes available.
+        This can be used for programming event loops, e.g.
 
-        @return @false only if the event loop should terminate.
-     */
+        @code
+        while (evtloop->Pending())
+            evtloop->Dispatch();
+        @endcode
+
+        @return @false if the event loop should stop and @true otherwise.
+
+        @see Pending(), wxEventLoopBase
+    */
     virtual bool Dispatch() = 0;
 
     /**
@@ -100,21 +122,139 @@ public:
      */
     virtual int DispatchTimeout(unsigned long timeout) = 0;
 
-    /**
-        Return true if this event loop is currently running.
-
-        Notice that even if this event loop hasn't terminated yet but has just
-        spawned a nested (e.g. modal) event loop, this method would return
-        @false.
-     */
-    bool IsRunning() const;
-
     /**
         Called by wxWidgets to wake up the event loop even if it is currently
         blocked inside Dispatch().
      */
     virtual void WakeUp() = 0;
 
+    //@}
+
+
+    /**
+        @name Pending events
+    */
+    //@{
+
+    /**
+        Process all pending events; it is necessary to call this function to
+        process posted events.
+
+        This happens during each event loop iteration in GUI mode but
+        it may be also called directly.
+    */
+    virtual void ProcessPendingEvents();
+
+    /**
+        Returns @true if there are pending events on the internal pending event list.
+    */
+    bool HasPendingEvents() const;
+
+    /**
+        Temporary suspends processing of the pending events.
+
+        @see ResumeProcessingOfPendingEvents()
+    */
+    void SuspendProcessingOfPendingEvents();
+
+    /**
+        Resume processing of the pending events previously stopped because of a
+        call to SuspendProcessingOfPendingEvents().
+    */
+    void ResumeProcessingOfPendingEvents();
+
+    //@}
+
+
+    /**
+        @name Idle handling
+    */
+    //@{
+
+    /**
+        Makes sure that idle events are sent again.
+    */
+    virtual void WakeUpIdle();
+
+    /**
+        This virtual function is called  when the application becomes idle and
+        normally just sends wxIdleEvent to all interested parties.
+
+        It should return @true if more idle events are needed, @false if not.
+    */
+    virtual bool ProcessIdle();
+
+    //@}
+
+
+    /**
+        @name Yield-related hooks
+    */
+    //@{
+
+    /**
+        Returns @true if called from inside Yield().
+    */
+    virtual bool IsYielding() const;
+
+    /**
+        Yields control to pending messages in the windowing system.
+
+        This can be useful, for example, when a time-consuming process writes to a
+        text window. Without an occasional yield, the text window will not be updated
+        properly, and on systems with cooperative multitasking, such as Windows 3.1
+        other processes will not respond.
+
+        Caution should be exercised, however, since yielding may allow the
+        user to perform actions which are not compatible with the current task.
+        Disabling menu items or whole menus during processing can avoid unwanted
+        reentrance of code: see ::wxSafeYield for a better function.
+        You can avoid unwanted reentrancies also using IsYielding().
+
+        Note that Yield() will not flush the message logs. This is intentional as
+        calling Yield() is usually done to quickly update the screen and popping up
+        a message box dialog may be undesirable. If you do wish to flush the log
+        messages immediately (otherwise it will be done during the next idle loop
+        iteration), call wxLog::FlushActive.
+
+        Calling Yield() recursively is normally an error and an assert failure is
+        raised in debug build if such situation is detected. However if the
+        @a onlyIfNeeded parameter is @true, the method will just silently
+        return @false instead.
+    */
+    bool Yield(bool onlyIfNeeded = false);
+
+    /**
+        Works like Yield() with @e onlyIfNeeded == @true, except that it allows
+        the caller to specify a mask of the ::wxEventCategory values which
+        indicates which events should be processed and which should instead
+        be "delayed" (i.e. processed by the main loop later).
+
+        Note that this is a safer alternative to Yield() since it ensures that
+        only the events you're interested to will be processed; i.e. this method
+        helps to avoid unwanted reentrancies.
+
+        Note that currently only wxMSW and wxGTK do support selective yield of
+        native events coming from the underlying GUI toolkit.
+        wxWidgets events posted using wxEvtHandler::AddPendingEvent or
+        wxEvtHandler::QueueEvent are instead selectively processed by all ports.
+
+        @see wxEvent::GetEventCategory
+    */
+    bool YieldFor(long eventsToProcess);
+
+    /**
+        Returns @true if the given event category is allowed inside
+        a YieldFor() call (i.e. compares the given category against the
+        last mask passed to YieldFor()).
+
+        @see wxEvent::GetEventCategory
+    */
+    virtual bool IsEventAllowedInsideYield(wxEventCategory cat) const;
+
+    //@}
+
+
 protected:
     /**
         This function is called before the event loop terminates, whether this