X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ec38d07d0343b3fc5af03becd17ce798b96e05db..36a0190ebd5bd9a7302f60f6dcd608b80574e21c:/interface/wx/evtloop.h

diff --git a/interface/wx/evtloop.h b/interface/wx/evtloop.h
index 41e4316355..817f8111ce 100644
--- a/interface/wx/evtloop.h
+++ b/interface/wx/evtloop.h
@@ -3,8 +3,7 @@
 // Purpose:     wxEventLoop and related classes
 // Author:      Vadim Zeitlin
 // Copyright:   (C) 2008 Vadim Zeitlin
-// RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 /**
@@ -18,10 +17,24 @@
 
     An object of this class is created by wxAppTraits::CreateEventLoop() and
     used by wxApp to run the main application event loop.
+    Temporary event loops are usually created by wxDialog::ShowModal().
 
     You can create your own event loop if you need, provided that you restore
     the main event loop once yours is destroyed (see wxEventLoopActivator).
 
+    Notice that there can be more than one event loop at any given moment, e.g.
+    an event handler called from the main loop can show a modal dialog, which
+    starts its own loop resulting in two nested loops, with the modal dialog
+    being the active one (its IsRunning() returns @true). And a handler for a
+    button inside the modal dialog can, of course, create another modal dialog
+    with its own event loop and so on. So in general event loops form a stack
+    and only the event loop at the top of the stack is considered to be active.
+    It is also the only loop that can be directly asked to terminate by calling
+    Exit() (which is done by wxDialog::EndModal()), an outer event loop can't
+    be stopped while an inner one is still running. It is however possible to
+    ask an outer event loop to terminate as soon as all its nested loops exit
+    and the control returns back to it by using ScheduleExit().
+
     @library{wxbase}
     @category{appmanagement}
 
@@ -89,9 +102,32 @@ public:
     virtual bool IsOk() const;
 
     /**
-        Exit from the loop with the given exit code.
+        Exit the currently running loop with the given exit code.
+
+        The loop will exit, i.e. its Run() method will return, during the next
+        event loop iteration.
+
+        Notice that this method can only be used if this event loop is the
+        currently running one, i.e. its IsRunning() returns @true. If this is
+        not the case, an assert failure is triggered and nothing is done as
+        outer event loops can't be exited from immediately. Use ScheduleExit()
+        if you'd like to exit this loop even if it doesn't run currently.
      */
-    virtual void Exit(int rc = 0) = 0;
+    virtual void Exit(int rc = 0);
+
+    /**
+        Schedule an exit from the loop with the given exit code.
+
+        This method is similar to Exit() but can be called even if this event
+        loop is not the currently running one -- and if it is the active loop,
+        then it works in exactly the same way as Exit().
+
+        The loop will exit as soon as the control flow returns to it, i.e.
+        after any nested loops terminate.
+
+        @since 2.9.5
+     */
+    virtual void ScheduleExit(int rc = 0) = 0;
 
     /**
         Return true if any events are available.
@@ -145,41 +181,6 @@ public:
     //@}
 
 
-    /**
-        @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
     */
@@ -320,3 +321,20 @@ public:
      */
     ~wxEventLoopActivator();
 };
+
+/**
+    @class wxGUIEventLoop
+
+    A generic implementation of the GUI event loop.
+    
+    @library{wxbase}
+    @category{appmanagement}
+*/
+class wxGUIEventLoop : public wxEventLoopBase
+{
+public:
+    wxGUIEventLoop();
+    virtual ~wxGUIEventLoop();
+};
+
+