add wxAppConsoleBase::OnEventLoopEnter/Exit callbacks; add wxEventLoopBase::IsMain() and wxAppConsoleBase::GetMainLoop() helpers

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

include/wx/app.h

@@ -87,10 +87,21 @@ public:
     // be done here. When OnRun() returns, the programs starts shutting down.
     virtual int OnRun();
 
+    // This is called by wxEventLoopBase::SetActive(): you should put the code
+    // which needs an active event loop here.
+    // Note that this function is called whenever an event loop is activated;
+    // you may want to use wxEventLoopBase::IsMain() to perform initialization
+    // specific for the app's main event loop.
+    virtual void OnEventLoopEnter(wxEventLoopBase* WXUNUSED(loop)) {}
+
     // This is only called if OnInit() returned true so it's a good place to do
     // any cleanup matching the initializations done there.
     virtual int OnExit();
 
+    // This is called by wxEventLoopBase::OnExit() for each event loop which
+    // is exited.
+    virtual void OnEventLoopExit(wxEventLoopBase* WXUNUSED(loop)) {}
+
     // This is the very last function called on wxApp object before it is
     // destroyed. If you override it (instead of overriding OnExit() as usual)
     // do not forget to call the base class version!
@@ -206,6 +217,15 @@ public:
     // for it
     static wxAppTraits *GetTraitsIfExists();
 
+    // returns the main event loop instance, i.e. the event loop which is started
+    // by OnRun() and which dispatches all events sent from the native toolkit
+    // to the application (except when new event loops are temporarily set-up).
+    // The returned value maybe NULL. Put initialization code which needs a
+    // non-NULL main event loop into OnEventLoopEnter().
+    wxEventLoopBase* GetMainLoop() const
+        { return m_mainLoop; }
+
+
     // event processing functions
     // --------------------------
 

include/wx/evtloop.h

@@ -61,6 +61,9 @@ public:
     // using it
     virtual bool IsOk() const { return true; }
 
+    // returns true if this is the main loop
+    bool IsMain() const;
+
 
     // dispatch&processing
     // -------------------
@@ -173,14 +176,14 @@ public:
     static wxEventLoopBase *GetActive() { return ms_activeLoop; }
 
     // set currently active (running) event loop
-    static void SetActive(wxEventLoopBase* loop) { ms_activeLoop = loop; }
+    static void SetActive(wxEventLoopBase* loop);
 
 
 protected:
     // this function should be called before the event loop terminates, whether
     // this happens normally (because of Exit() call) or abnormally (because of
     // an exception thrown from inside the loop)
-    virtual void OnExit() { }
+    virtual void OnExit();
 
     // the pointer to currently active loop
     static wxEventLoopBase *ms_activeLoop;

interface/wx/app.h

@@ -91,6 +91,14 @@ public:
     */
     virtual int FilterEvent(wxEvent& event);
 
+    /**
+        Returns the main event loop instance, i.e. the event loop which is started
+        by OnRun() and which dispatches all events sent from the native toolkit
+        to the application (except when new event loops are temporarily set-up).
+        The returned value maybe @NULL. Put initialization code which needs a
+        non-@NULL main event loop into OnEventLoopEnter().
+    */
+    wxEventLoopBase* GetMainLoop() const;
 
     /**
         This function simply invokes the given method @a func of the specified
@@ -254,6 +262,22 @@ public:
     */
     virtual bool OnCmdLineParsed(wxCmdLineParser& parser);
 
+    /**
+        Called by wxEventLoopBase::SetActive(): you can override this function
+        and put here the code which needs an active event loop.
+
+        Note that this function is called whenever an event loop is activated;
+        you may want to use wxEventLoopBase::IsMain() to perform initialization
+        specific for the app's main event loop.
+    */
+    virtual void OnEventLoopEnter(wxEventLoopBase* loop);
+
+    /**
+        Called by wxEventLoopBase::OnExit() for each event loop which
+        is exited.
+    */
+    virtual void OnEventLoopExit(wxEventLoopBase* loop);
+
     /**
         This function is called if an unhandled exception occurs inside the main
         application event loop. It can return @true to ignore the exception and to

interface/wx/evtloop.h

@@ -12,9 +12,16 @@
 
     Base class for all event loop implementations.
 
+    An event loop is a class which queries the queue of native events sent
+    to the wxWidgets application and dispatches them to the appropriate
+    wxEvtHandlers.
+
     An object of this class is created by wxAppTraits::CreateEventLoop() and
     used by wxApp to run the main application event loop.
 
+    You can create your own event loop if you need, provided that you restore
+    the main event loop once yours is destroyed (see wxEventLoopActivator).
+
     @library{wxbase}
     @category{appmanagement}
 
@@ -37,9 +44,16 @@ public:
         Called by wxEventLoopActivator, use an instance of this class instead
         of calling this method directly to ensure that the previously active
         event loop is restored.
+
+        Results in a call to wxAppConsole::OnEventLoopEnter.
      */
     static void SetActive(wxEventLoopBase* loop);
 
+    /**
+        Returns @true if this is the main loop executed by wxApp::OnRun().
+    */
+    bool IsMain() const;
+
 
     /**
         @name Dispatch and processing
@@ -193,7 +207,7 @@ public:
     //@{
 
     /**
-        Returns @true if called from inside Yield().
+        Returns @true if called from inside Yield() or from inside YieldFor().
     */
     virtual bool IsYielding() const;
 
@@ -261,7 +275,7 @@ protected:
         happens normally (because of Exit() call) or abnormally (because of an
         exception thrown from inside the loop).
 
-        Default version does nothing.
+        The default implementation calls wxAppConsole::OnEventLoopExit.
      */
     virtual void OnExit();
 };

src/common/evtloopcmn.cpp

@@ -34,6 +34,28 @@ wxEventLoopBase::wxEventLoopBase()
     m_eventsToProcessInsideYield = wxEVT_CATEGORY_ALL;
 }
 
+bool wxEventLoopBase::IsMain() const
+{
+    if (wxTheApp)
+        return wxTheApp->GetMainLoop() == this;
+    return false;
+}
+
+/* static */
+void wxEventLoopBase::SetActive(wxEventLoopBase* loop)
+{
+    ms_activeLoop = loop;
+
+    if (wxTheApp)
+        wxTheApp->OnEventLoopEnter(loop);
+}
+
+void wxEventLoopBase::OnExit()
+{
+    if (wxTheApp)
+        wxTheApp->OnEventLoopExit(this);
+}
+
 void wxEventLoopBase::DelayPendingEventHandler(wxEvtHandler* toDelay)
 {
     wxENTER_CRIT_SECT(m_handlersWithPendingEventsLocker);