Add component-level filtering to wxLog.

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

diff --git a/interface/wx/app.h b/interface/wx/app.h
index ab2d90b964590559aeba9baf059081f4b8e67465..4053532457888150a2b2543f194e800d3f3d7831 100644 (file)
--- a/interface/wx/app.h
+++ b/interface/wx/app.h
@@ -35,7 +35,7 @@
     @library{wxbase}
     @category{appmanagement}
 
     @library{wxbase}
     @category{appmanagement}
 

-    @see @ref overview_app, wxApp, wxAppTraits, wxEventLoop
+    @see @ref overview_app, wxApp, wxAppTraits, wxEventLoopBase

 */
 class wxAppConsole : public wxEvtHandler
 {
 */
 class wxAppConsole : public wxEvtHandler
 {


@@ -54,28 +54,29 @@ public:
     */
     virtual ~wxAppConsole();
 
     */
     virtual ~wxAppConsole();
 

-    /**
-        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).

 
 

-        This can be used for programming event loops, e.g.
+    /**
+        @name Event-handling

 
 

-        @code
-        while (app.Pending())
-            Dispatch();
-        @endcode
+        Note that you should look at wxEvtLoopBase for more event-processing
+        documentation.
+    */
+    //@{

 
 

-        @return @false if the event loop should stop and @true otherwise.
+    /**
+        Called by wxWidgets on creation of the application. Override this if you wish
+        to provide your own (environment-dependent) main loop.

 
 

-        @see Pending()
+        @return 0 under X, and the wParam of the WM_QUIT message under Windows.

     */
     */

-    virtual bool Dispatch();
+    virtual int MainLoop();

 
     /**
         Call this to explicitly exit the main message (event) loop.
         You should normally exit the main loop (and the application) by deleting
         the top window.
 
     /**
         Call this to explicitly exit the main message (event) loop.
         You should normally exit the main loop (and the application) by deleting
         the top window.

+
+        This function simply calls wxEvtLoopBase::Exit() on the active loop.

     */
     virtual void ExitMainLoop();
 
     */
     virtual void ExitMainLoop();
 


@@ -91,80 +92,105 @@ public:
     virtual int FilterEvent(wxEvent& event);
 
     /**
     virtual int FilterEvent(wxEvent& event);
 
     /**

-        Returns the user-readable application name.
-
-        The difference between this string and the one returned by GetAppName()
-        is that this one is meant to be shown to the user and so should be used
-        for the window titles, page headers and so on while the other one
-        should be only used internally, e.g. for the file names or
-        configuration file keys. By default, returns the application name as
-        returned by GetAppName() capitalized using wxString::Capitalize().
-
-        @since 2.9.0
+        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().

     */
     */

-    wxString GetAppDisplayName() const;
+    wxEventLoopBase* GetMainLoop() const;

 
     /**
 
     /**

-        Returns the application name.
+        This function simply invokes the given method @a func of the specified
+        event handler @a handler with the @a event as parameter. It exists solely
+        to allow to catch the C++ exceptions which could be thrown by all event
+        handlers in the application in one place: if you want to do this, override
+        this function in your wxApp-derived class and add try/catch clause(s) to it.
+    */
+    virtual void HandleEvent(wxEvtHandler* handler,
+                             wxEventFunction func,
+                             wxEvent& event) const;

 
 

-        @remarks wxWidgets sets this to a reasonable default before calling
-                 OnInit(), but the application can reset it at will.
+    //@}

 
 

-        @see GetAppDisplayName()
-    */
-    wxString GetAppName() const;

 
     /**
 
     /**

-        Gets the class name of the application. The class name may be used in a
-        platform specific manner to refer to the application.
+        @name Pending events

 
 

-        @see SetClassName()
+        Pending events are handled by wxAppConsole rather than wxEventLoopBase
+        to allow queuing of events even when there's no event loop
+        (e.g. in wxAppConsole::OnInit).

     */
     */

-    wxString GetClassName() const;
+    //@{

 
     /**
 
     /**

-        Returns the one and only global application object.
-        Usually wxTheApp is used instead.
-
-        @see SetInstance()
+        Process all pending events; it is necessary to call this function to
+        process events posted with wxEvtHandler::QueueEvent or wxEvtHandler::AddPendingEvent.
+
+        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.

     */
     */

-    static wxAppConsole* GetInstance();
+    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 a pointer to the wxAppTraits object for the application.
-        If you want to customize the wxAppTraits object, you must override the
-        CreateTraits() function.
+        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.

     */
     */

-    wxAppTraits* GetTraits();
+    bool HasPendingEvents() const;

 
     /**
 
     /**

-        Returns the user-readable vendor name. The difference between this string
-        and the one returned by GetVendorName() is that this one is meant to be shown
-        to the user and so should be used for the window titles, page headers and so on
-        while the other one should be only used internally, e.g. for the file names or
-        configuration file keys.
+        Temporary suspends processing of the pending events.

 
 

-        By default, returns the same string as GetVendorName().
+        @see ResumeProcessingOfPendingEvents()
+    */
+    void SuspendProcessingOfPendingEvents();

 
 

-        @since 2.9.0
+    /**
+        Resume processing of the pending events previously stopped because of a
+        call to SuspendProcessingOfPendingEvents().

     */
     */

-    const wxString& GetVendorDisplayName() const;
+    void ResumeProcessingOfPendingEvents();
+
+    //@}
+

 
     /**
 
     /**

-        Returns the application's vendor name.
+        Allows external code to modify global ::wxTheApp, but you should really
+        know what you're doing if you call it.
+
+        @param app
+            Replacement for the global application object.
+
+        @see GetInstance()

     */
     */

-    const wxString& GetVendorName() const;
+    static void SetInstance(wxAppConsole* app);

 
     /**
 
     /**

-        This function simply invokes the given method @a func of the specified
-        event handler @a handler with the @a event as parameter. It exists solely
-        to allow to catch the C++ exceptions which could be thrown by all event
-        handlers in the application in one place: if you want to do this, override
-        this function in your wxApp-derived class and add try/catch clause(s) to it.
+        Returns the one and only global application object.
+        Usually ::wxTheApp is used instead.
+
+        @see SetInstance()

     */
     */

-    virtual void HandleEvent(wxEvtHandler* handler,
-                             wxEventFunction func,
-                             wxEvent& event) const;
+    static wxAppConsole* GetInstance();

 
     /**
         Returns @true if the main event loop is currently running, i.e. if the
 
     /**
         Returns @true if the main event loop is currently running, i.e. if the


@@ -176,20 +202,17 @@ public:
     */
     static bool IsMainLoopRunning();
 
     */
     static bool IsMainLoopRunning();
 

-    /**
-        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 if there is
-        no main loop, it may be also called directly.
+    /**
+        @name Mac-specific functions

     */
     */

-    virtual void ProcessPendingEvents();
+    //@{

 
     /**
         Called in response of an "open-application" Apple event.
         Override this to create a new document in your app.
 
 
     /**
         Called in response of an "open-application" Apple event.
         Override this to create a new document in your app.
 

-        @onlyfor{wxmac}
+        @onlyfor{wxosx}

     */
     virtual void MacNewFile();
 
     */
     virtual void MacNewFile();
 


@@ -200,38 +223,38 @@ public:
         user double clicked on it or if the document file was dropped on either the
         running application or the application icon in Finder.
 
         user double clicked on it or if the document file was dropped on either the
         running application or the application icon in Finder.
 

-        @onlyfor{wxmac}
+        @onlyfor{wxosx}

     */
     virtual void MacOpenFile(const wxString& fileName);
 
     /**
         Called in response of a "get-url" Apple event.
 
     */
     virtual void MacOpenFile(const wxString& fileName);
 
     /**
         Called in response of a "get-url" Apple event.
 

-        @onlyfor{wxmac}
+        @onlyfor{wxosx}

     */
     virtual void MacOpenURL(const wxString& url);
 
     /**
         Called in response of a "print-document" Apple event.
 
     */
     virtual void MacOpenURL(const wxString& url);
 
     /**
         Called in response of a "print-document" Apple event.
 

-        @onlyfor{wxmac}
+        @onlyfor{wxosx}

     */
     virtual void MacPrintFile(const wxString& fileName);
 
     /**
         Called in response of a "reopen-application" Apple event.
 
     */
     virtual void MacPrintFile(const wxString& fileName);
 
     /**
         Called in response of a "reopen-application" Apple event.
 

-        @onlyfor{wxmac}
+        @onlyfor{wxosx}

     */
     virtual void MacReopenApp();
 
     */
     virtual void MacReopenApp();
 

-    /**
-        Called by wxWidgets on creation of the application. Override this if you wish
-        to provide your own (environment-dependent) main loop.
+    //@}

 
 

-        @return 0 under X, and the wParam of the WM_QUIT message under Windows.
+
+    /**
+        @name Callbacks for application-wide "events"

     */
     */

-    virtual int MainLoop();
+    //@{

 
     /**
         This function is called when an assert failure occurs, i.e. the condition
 
     /**
         This function is called when an assert failure occurs, i.e. the condition


@@ -298,6 +321,26 @@ public:
     */
     virtual bool OnCmdLineParsed(wxCmdLineParser& parser);
 
     */
     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.
+
+        @see OnEventLoopExit()
+    */
+    virtual void OnEventLoopEnter(wxEventLoopBase* loop);
+
+    /**
+        Called by wxEventLoopBase::OnExit() for each event loop which
+        is exited.
+
+        @see OnEventLoopEnter()
+    */
+    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
     /**
         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


@@ -389,12 +432,70 @@ public:
     */
     virtual void OnUnhandledException();
 
     */
     virtual void OnUnhandledException();
 

+    //@}
+
+
+    /**
+        @name Application informations
+    */
+    //@{
+
+    /**
+        Returns the user-readable application name.
+
+        The difference between this string and the one returned by GetAppName()
+        is that this one is meant to be shown to the user and so should be used
+        for the window titles, page headers and so on while the other one
+        should be only used internally, e.g. for the file names or
+        configuration file keys. By default, returns the application name as
+        returned by GetAppName() capitalized using wxString::Capitalize().
+
+        @since 2.9.0
+    */
+    wxString GetAppDisplayName() const;
+
+    /**
+        Returns the application name.
+
+        @remarks wxWidgets sets this to a reasonable default before calling
+                 OnInit(), but the application can reset it at will.
+
+        @see GetAppDisplayName()
+    */
+    wxString GetAppName() const;
+
+    /**
+        Gets the class name of the application. The class name may be used in a
+        platform specific manner to refer to the application.
+
+        @see SetClassName()
+    */
+    wxString GetClassName() const;
+
+    /**
+        Returns a pointer to the wxAppTraits object for the application.
+        If you want to customize the wxAppTraits object, you must override the
+        CreateTraits() function.
+    */
+    wxAppTraits* GetTraits();
+

     /**
     /**

-        Returns @true if unprocessed events are in the window system event queue.
+        Returns the user-readable vendor name. The difference between this string
+        and the one returned by GetVendorName() is that this one is meant to be shown
+        to the user and so should be used for the window titles, page headers and so on
+        while the other one should be only used internally, e.g. for the file names or
+        configuration file keys.

 
 

-        @see Dispatch()
+        By default, returns the same string as GetVendorName().
+
+        @since 2.9.0

     */
     */

-    virtual bool Pending();
+    const wxString& GetVendorDisplayName() const;
+
+    /**
+        Returns the application's vendor name.
+    */
+    const wxString& GetVendorName() const;

 
     /**
         Set the application name to be used in the user-visible places such as
 
     /**
         Set the application name to be used in the user-visible places such as


@@ -428,17 +529,6 @@ public:
     */
     void SetClassName(const wxString& name);
 
     */
     void SetClassName(const wxString& name);
 

-    /**
-        Allows external code to modify global ::wxTheApp, but you should really
-        know what you're doing if you call it.
-
-        @param app
-            Replacement for the global application object.
-
-        @see GetInstance()
-    */
-    static void SetInstance(wxAppConsole* app);
-

     /**
         Set the vendor name to be used in the user-visible places.
         See GetVendorDisplayName() for more about the differences between the
     /**
         Set the vendor name to be used in the user-visible places.
         See GetVendorDisplayName() for more about the differences between the


@@ -454,31 +544,8 @@ public:
     */
     void SetVendorName(const wxString& name);
 
     */
     void SetVendorName(const wxString& name);
 

-    /**
-        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.
+    //@}

 
 

-        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.
-    */
-    virtual bool Yield(bool onlyIfNeeded = false);

 
     /**
         Number of command line arguments (after environment-specific processing).
 
     /**
         Number of command line arguments (after environment-specific processing).


@@ -511,12 +578,31 @@ public:
     video modes (see SetVideoMode()).
 
     In general, application-wide settings for GUI-only apps are accessible
     video modes (see SetVideoMode()).
 
     In general, application-wide settings for GUI-only apps are accessible

-    from wxApp (or from wxSystemSettings).
+    from wxApp (or from wxSystemSettings or wxSystemOptions classes).
+
+    @beginEventEmissionTable
+    @event{EVT_QUERY_END_SESSION(func)}
+        Process a query end session event, supplying the member function.
+        See wxCloseEvent.
+    @event{EVT_END_SESSION(func)}
+        Process an end session event, supplying the member function.
+        See wxCloseEvent.
+    @event{EVT_ACTIVATE_APP(func)}
+        Process a @c wxEVT_ACTIVATE_APP event. See wxActivateEvent.
+    @event{EVT_HIBERNATE(func)}
+        Process a hibernate event. See wxActivateEvent.
+    @event{EVT_DIALUP_CONNECTED(func)}
+        A connection with the network was established. See wxDialUpEvent.
+    @event{EVT_DIALUP_DISCONNECTED(func)}
+        The connection with the network was lost. See wxDialUpEvent.
+    @event{EVT_IDLE(func)}
+        Process a @c wxEVT_IDLE event. See wxIdleEvent.
+    @endEventTable

 
     @library{wxbase}
     @category{appmanagement}
 
 
     @library{wxbase}
     @category{appmanagement}
 

-    @see @ref overview_app, wxAppTraits, wxEventLoop, wxSystemSettings
+    @see @ref overview_app, wxAppTraits, wxEventLoopBase, wxSystemSettings

 */
 class wxApp : public wxAppConsole
 {
 */
 class wxApp : public wxAppConsole
 {


@@ -534,7 +620,7 @@ public:
 
     /**
         Get display mode that is used use. This is only used in framebuffer
 
     /**
         Get display mode that is used use. This is only used in framebuffer

-        wxWin ports (such as wxMGL or wxDFB).
+        wxWidgets ports (such as wxMGL or wxDFB).

     */
     virtual wxVideoMode GetDisplayMode() const;
 
     */
     virtual wxVideoMode GetDisplayMode() const;
 


@@ -580,6 +666,25 @@ public:
     */
     virtual bool IsActive() const;
 
     */
     virtual bool IsActive() const;
 

+    /**
+        This function is similar to wxYield(), except that it disables the user
+        input to all program windows before calling wxAppConsole::Yield and re-enables it
+        again afterwards. If @a win is not @NULL, this window will remain enabled,
+        allowing the implementation of some limited user interaction.
+        Returns the result of the call to wxAppConsole::Yield.
+
+        @see wxSafeYield
+    */
+    virtual bool SafeYield(wxWindow *win, bool onlyIfNeeded);
+
+    /**
+        Works like SafeYield() with @e onlyIfNeeded == @true except that
+        it allows the caller to specify a mask of events to be processed.
+
+        See wxAppConsole::YieldFor for more info.
+    */
+    virtual bool SafeYieldFor(wxWindow *win, long eventsToProcess);
+

     /**
         Windows-only function for processing a message. This function is called
         from the main message loop, checking for windows that may wish to process it.
     /**
         Windows-only function for processing a message. This function is called
         from the main message loop, checking for windows that may wish to process it.


@@ -619,9 +724,8 @@ public:
     virtual bool SendIdleEvents(wxWindow* win, wxIdleEvent& event);
 
     /**
     virtual bool SendIdleEvents(wxWindow* win, wxIdleEvent& event);
 
     /**

-        Set display mode to use. This is only used in framebuffer wxWin
-        ports (such as wxMGL or wxDFB). This method should be called from
-        wxApp::OnInitGui.
+        Set display mode to use. This is only used in framebuffer wxWidgets
+        ports (such as wxMGL or wxDFB).

     */
     virtual bool SetDisplayMode(const wxVideoMode& info);
 
     */
     virtual bool SetDisplayMode(const wxVideoMode& info);
 


@@ -637,17 +741,6 @@ public:
     */
     void SetExitOnFrameDelete(bool flag);
 
     */
     void SetExitOnFrameDelete(bool flag);
 

-    /**
-        Allows external code to modify global ::wxTheApp, but you should really
-        know what you're doing if you call it.
-
-        @param app
-            Replacement for the global application object.
-
-        @see GetInstance()
-    */
-    static void SetInstance(wxAppConsole* app);
-

     /**
         Allows runtime switching of the UI environment theme.
 
     /**
         Allows runtime switching of the UI environment theme.
 


@@ -704,7 +797,7 @@ public:
 // ============================================================================
 
 
 // ============================================================================
 
 

-/** @ingroup group_funcmacro_rtti */
+/** @addtogroup group_funcmacro_rtti */

 //@{
 
 /**
 //@{
 
 /**


@@ -752,7 +845,7 @@ wxApp *wxTheApp;
 
 
 
 
 
 

-/** @ingroup group_funcmacro_appinitterm */
+/** @addtogroup group_funcmacro_appinitterm */

 //@{
 
 /**
 //@{
 
 /**


@@ -827,22 +920,18 @@ void wxUninitialize();
 void wxWakeUpIdle();
 
 /**
 void wxWakeUpIdle();
 
 /**

-    Calls wxApp::Yield.
+    Calls wxAppConsole::Yield.

 
     @deprecated
     This function is kept only for backwards compatibility. Please use
 
     @deprecated
     This function is kept only for backwards compatibility. Please use

-    the wxApp::Yield method instead in any new code.
+    the wxAppConsole::Yield method instead in any new code.

 
     @header{wx/app.h}
 */
 bool wxYield();
 
 /**
 
     @header{wx/app.h}
 */
 bool wxYield();
 
 /**

-    This function is similar to wxYield(), except that it disables the user
-    input to all program windows before calling wxYield() and re-enables it
-    again afterwards. If @a win is not @NULL, this window will remain enabled,
-    allowing the implementation of some limited user interaction.
-    Returns the result of the call to ::wxYield.
+    Calls wxApp::SafeYield.

 
     @header{wx/app.h}
 */
 
     @header{wx/app.h}
 */


@@ -894,7 +983,7 @@ int wxEntry(HINSTANCE hInstance,
 
 
 
 
 
 

-/** @ingroup group_funcmacro_procctrl */
+/** @addtogroup group_funcmacro_procctrl */

 //@{
 
 /**
 //@{
 
 /**