Add support for thread-specific log targets.

[wxWidgets.git] / include / wx / app.h

diff --git a/include/wx/app.h b/include/wx/app.h
index 9113fbd6e10fff018e7756d37bd936928fc57cd0..f754a7b117f5b524c47362e8e01f836c11dfef11 100644 (file)
--- a/include/wx/app.h
+++ b/include/wx/app.h
@@ -83,17 +83,25 @@ public:
     // class OnInit() to do it.
     virtual bool OnInit();
 
     // class OnInit() to do it.
     virtual bool OnInit();
 

-    // this is here only temporary hopefully (FIXME)
-    virtual bool OnInitGui() { return true; }
-

     // This is the replacement for the normal main(): all program work should
     // be done here. When OnRun() returns, the programs starts shutting down.
     virtual int OnRun();
 
     // This is the replacement for the normal main(): all program work should
     // 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 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!
     // 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!


@@ -209,6 +217,15 @@ public:
     // for it
     static wxAppTraits *GetTraitsIfExists();
 
     // 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
     // --------------------------
 
     // event processing functions
     // --------------------------
 


@@ -221,6 +238,10 @@ public:
     // had been already processed or won't be processed at all, respectively
     virtual int FilterEvent(wxEvent& event);
 
     // had been already processed or won't be processed at all, respectively
     virtual int FilterEvent(wxEvent& event);
 

+    // return true if we're running event loop, i.e. if the events can
+    // (already) be dispatched
+    static bool IsMainLoopRunning();
+

 #if wxUSE_EXCEPTIONS
     // execute the functor to handle the given event
     //
 #if wxUSE_EXCEPTIONS
     // execute the functor to handle the given event
     //


@@ -246,23 +267,26 @@ public:
     // exit, if you need to really handle the exceptions you need to override
     // OnExceptionInMainLoop()
     virtual void OnUnhandledException();
     // exit, if you need to really handle the exceptions you need to override
     // OnExceptionInMainLoop()
     virtual void OnUnhandledException();

-#endif // wxUSE_EXCEPTIONS

 
 

-    // event processing functions
-    // --------------------------
+    // Function called if an uncaught exception is caught inside the main
+    // event loop: it may return true to continue running the event loop or
+    // false to stop it (in the latter case it may rethrow the exception as
+    // well)
+    virtual bool OnExceptionInMainLoop();

 
 

-    // return true if we're running event loop, i.e. if the events can
-    // (already) be dispatched
-    static bool IsMainLoopRunning();
+#endif // wxUSE_EXCEPTIONS

 
 

-    // temporary suspends processing of the pending events
-    virtual void SuspendProcessingOfPendingEvents();

 
 

-    // resume processing of the pending events previously stopped because of a
-    // call to SuspendProcessingOfPendingEvents()
-    virtual void ResumeProcessingOfPendingEvents();
+    // pending events
+    // --------------
+
+    // IMPORTANT: all these methods conceptually belong to wxEventLoopBase
+    //            but for many reasons we need to allow queuing of events
+    //            even when there's no event loop (e.g. in wxApp::OnInit);
+    //            this feature is used e.g. to queue events on secondary threads
+    //            or in wxPython to use wx.CallAfter before the GUI is initialized

 
 

-    // process all events in the wxHandlersWithPendingEvents list -- it is necessary
+    // process all events in the m_handlersWithPendingEvents list -- it is necessary

     // to call this function to process posted events. This happens during each
     // event loop iteration in GUI mode but if there is no main loop, it may be
     // also called directly.
     // to call this function to process posted events. This happens during each
     // event loop iteration in GUI mode but if there is no main loop, it may be
     // also called directly.


@@ -271,68 +295,46 @@ public:
     // check if there are pending events on global pending event list
     bool HasPendingEvents() const;
 
     // check if there are pending events on global pending event list
     bool HasPendingEvents() const;
 

-    // make sure that idle events are sent again
-    virtual void WakeUpIdle();
+    // temporary suspends processing of the pending events
+    void SuspendProcessingOfPendingEvents();

 
 

-        // execute the main GUI loop, the function returns when the loop ends
-    virtual int MainLoop();
+    // resume processing of the pending events previously stopped because of a
+    // call to SuspendProcessingOfPendingEvents()
+    void ResumeProcessingOfPendingEvents();

 
 

-        // exit the main GUI loop during the next iteration (i.e. it does not
-        // stop the program immediately!)
-    virtual void ExitMainLoop();
+    // called by ~wxEvtHandler to (eventually) remove the handler from the list of
+    // the handlers with pending events
+    void RemovePendingEventHandler(wxEvtHandler* toRemove);

 
 

-        // returns true if there are unprocessed events in the event queue
-    virtual bool Pending();
+    // adds an event handler to the list of the handlers with pending events
+    void AppendPendingEventHandler(wxEvtHandler* toAppend);

 
 

-        // process the first event in the event queue (blocks until an event
-        // appears if there are none currently, use Pending() if this is not
-        // wanted), returns false if the event loop should stop and true
-        // otherwise
-    virtual bool Dispatch();
+    // moves the event handler from the list of the handlers with pending events
+    //to the list of the handlers with _delayed_ pending events
+    void DelayPendingEventHandler(wxEvtHandler* toDelay);

 
 

-        // 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();
+    // deletes the current pending events
+    void DeletePendingEvents();

 
 

-#if wxUSE_EXCEPTIONS
-    // Function called if an uncaught exception is caught inside the main
-    // event loop: it may return true to continue running the event loop or
-    // false to stop it (in the latter case it may rethrow the exception as
-    // well)
-    virtual bool OnExceptionInMainLoop();
-#endif // wxUSE_EXCEPTIONS

 
 

-    // Yield-related hooks
-    // -------------------
+    // wxEventLoop redirections
+    // ------------------------

 
 

-        // process all currently pending events right now
-        //
-        // it is an error to call Yield() recursively unless the value of
-        // onlyIfNeeded is true
-        //
-        // WARNING: this function is dangerous as it can lead to unexpected
-        //          reentrancies (i.e. when called from an event handler it
-        //          may result in calling the same event handler again), use
-        //          with _extreme_ care or, better, don't use at all!
-        // NOTE: in wxConsoleBase it doesn't do anything, just a hook for GUI wxApp
-    bool Yield(bool onlyIfNeeded = false)
-        { return DoYield(onlyIfNeeded, wxEVT_CATEGORY_ALL); }
-    bool YieldFor(long eventsToProcess)
-        { return DoYield(true, eventsToProcess); }
-    virtual bool IsYielding() const
-        { return false; }
-    virtual bool IsEventAllowedInsideYield(wxEventCategory WXUNUSED(cat)) const
-        { return true; }
-    // no SafeYield hooks since it uses wxWindow which is not available when wxUSE_GUI=0
+    virtual bool Pending();
+    virtual bool Dispatch();
+
+    virtual int MainLoop();
+    virtual void ExitMainLoop();
+
+    bool Yield(bool onlyIfNeeded = false);
+
+    virtual void WakeUpIdle();
+    virtual bool ProcessIdle();

 
 
     // debugging support
     // -----------------
 
 
 
     // debugging support
     // -----------------
 

-#ifdef __WXDEBUG__

     // this function is called when an assert failure occurs, the base class
     // version does the normal processing (i.e. shows the usual assert failure
     // dialog box)
     // this function is called when an assert failure occurs, the base class
     // version does the normal processing (i.e. shows the usual assert failure
     // dialog box)


@@ -352,7 +354,6 @@ public:
                           int line,
                           const wxChar *cond,
                           const wxChar *msg);
                           int line,
                           const wxChar *cond,
                           const wxChar *msg);

-#endif // __WXDEBUG__

 
     // check that the wxBuildOptions object (constructed in the application
     // itself, usually the one from IMPLEMENT_APP() macro) matches the build
 
     // check that the wxBuildOptions object (constructed in the application
     // itself, usually the one from IMPLEMENT_APP() macro) matches the build


@@ -395,10 +396,6 @@ protected:
     // for the first time
     virtual wxAppTraits *CreateTraits();
 
     // for the first time
     virtual wxAppTraits *CreateTraits();
 

-    // the real yield function hook:
-    virtual bool DoYield(bool WXUNUSED(onlyIfNeeded), long WXUNUSED(eventsToProcess))
-        { return true; }
-

     // function used for dynamic wxApp creation
     static wxAppInitializerFunction ms_appInitFn;
 
     // function used for dynamic wxApp creation
     static wxAppInitializerFunction ms_appInitFn;
 


@@ -424,18 +421,32 @@ protected:
     // been started yet or has already terminated)
     wxEventLoopBase *m_mainLoop;
 
     // been started yet or has already terminated)
     wxEventLoopBase *m_mainLoop;
 

+
+    // pending events management vars:
+

     // the array of the handlers with pending events which needs to be processed
     // inside ProcessPendingEvents()
     // the array of the handlers with pending events which needs to be processed
     // inside ProcessPendingEvents()

-    // wxEvtHandlerArray m_handlersWithPendingEvents;    FIXME: enable this and remove global lists
+    wxEvtHandlerArray m_handlersWithPendingEvents;
+
+    // helper array used by ProcessPendingEvents() to store the event handlers
+    // which have pending events but of these events none can be processed right now
+    // (because of a call to wxEventLoop::YieldFor() which asked to selectively process
+    // pending events)
+    wxEvtHandlerArray m_handlersWithPendingDelayedEvents;
+
+#if wxUSE_THREADS
+    // this critical section protects both the lists above
+    wxCriticalSection m_handlersWithPendingEventsLocker;
+#endif

 
 

-    // helper array used by ProcessPendingEvents()
-    // wxEvtHandlerArray m_handlersWithPendingDelayedEvents;    FIXME: enable this and remove global lists
+    // flag modified by Suspend/ResumeProcessingOfPendingEvents()
+    bool m_bDoPendingEventProcessing;

 
 

-    friend class WXDLLIMPEXP_BASE wxEvtHandler;
+    friend class WXDLLIMPEXP_FWD_BASE wxEvtHandler;

 
     // the application object is a singleton anyhow, there is no sense in
     // copying it
 
     // the application object is a singleton anyhow, there is no sense in
     // copying it

-    DECLARE_NO_COPY_CLASS(wxAppConsoleBase)
+    wxDECLARE_NO_COPY_CLASS(wxAppConsoleBase);

 };
 
 #if defined(__UNIX__)
 };
 
 #if defined(__UNIX__)


@@ -496,15 +507,6 @@ public:
     virtual bool SafeYield(wxWindow *win, bool onlyIfNeeded);
     virtual bool SafeYieldFor(wxWindow *win, long eventsToProcess);
 
     virtual bool SafeYield(wxWindow *win, bool onlyIfNeeded);
     virtual bool SafeYieldFor(wxWindow *win, long eventsToProcess);
 

-        // returns true if the main thread is inside a Yield() call
-    virtual bool IsYielding() const
-        { return m_isInsideYield; }
-
-        // returns true if events of the given event category should be immediately
-        // processed inside a wxApp::Yield() call or rather should be queued for
-        // later processing by the main event loop
-    virtual bool IsEventAllowedInsideYield(wxEventCategory cat) const;
-

         // this virtual function is called in the GUI mode when the application
         // becomes idle and normally just sends wxIdleEvent to all interested
         // parties
         // this virtual function is called in the GUI mode when the application
         // becomes idle and normally just sends wxIdleEvent to all interested
         // parties


@@ -627,11 +629,7 @@ protected:
     // does any of our windows have focus?
     bool m_isActive;
 
     // does any of our windows have focus?
     bool m_isActive;
 

-    // Yield() helpers:
-    bool m_isInsideYield;
-    long m_eventsToProcessInsideYield;
-
-    DECLARE_NO_COPY_CLASS(wxAppBase)
+    wxDECLARE_NO_COPY_CLASS(wxAppBase);

 };
 
 #if WXWIN_COMPATIBILITY_2_6
 };
 
 #if WXWIN_COMPATIBILITY_2_6