synchronize GTK2 minimum version in docs

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

diff --git a/interface/wx/app.h b/interface/wx/app.h
index 7bc9844834e2b60b3936e2ffe3701efc7038355d..3261fd74aabf8543ae269b2ecb127337df23171c 100644 (file)
--- a/interface/wx/app.h
+++ b/interface/wx/app.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxApp
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxApp
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 
 /////////////////////////////////////////////////////////////////////////////
 
 


@@ -24,11 +24,11 @@
         objects in the application (see wxAppConsole::FilterEvent)
     @li implement Apple-specific event handlers (see wxAppConsole::MacXXX functions)
 
         objects in the application (see wxAppConsole::FilterEvent)
     @li implement Apple-specific event handlers (see wxAppConsole::MacXXX functions)
 

-    You should use the macro IMPLEMENT_APP(appClass) in your application
+    You should use the macro wxIMPLEMENT_APP(appClass) in your application

     implementation file to tell wxWidgets how to create an instance of your
     application class.
 
     implementation file to tell wxWidgets how to create an instance of your
     application class.
 

-    Use DECLARE_APP(appClass) in a header file if you want the ::wxGetApp() function
+    Use wxDECLARE_APP(appClass) in a header file if you want the ::wxGetApp() function

     (which returns a reference to your application object) to be visible to other
     files.
 
     (which returns a reference to your application object) to be visible to other
     files.
 


@@ -37,7 +37,8 @@
 
     @see @ref overview_app, wxApp, wxAppTraits, wxEventLoopBase
 */
 
     @see @ref overview_app, wxApp, wxAppTraits, wxEventLoopBase
 */

-class wxAppConsole : public wxEvtHandler
+class wxAppConsole : public wxEvtHandler,
+                     public wxEventFilter

 {
 protected:
     /**
 {
 protected:
     /**


@@ -81,13 +82,14 @@ public:
     virtual void ExitMainLoop();
 
     /**
     virtual void ExitMainLoop();
 
     /**

+        Overridden wxEventFilter method.
+

         This function is called before processing any event and allows the application
         This function is called before processing any event and allows the application

-        to preempt the processing of some events.
+        to preempt the processing of some events, see wxEventFilter
+        documentation for more information.

 
 

-        If this method returns -1 the event is processed normally, otherwise either
-        @true or @false should be returned and the event processing stops immediately
-        considering that the event had been already processed (for the former return
-        value) or that it is not going to be processed at all (for the latter one).
+        wxApp implementation of this method always return -1 indicating that
+        the event should be processed normally.

     */
     virtual int FilterEvent(wxEvent& event);
 
     */
     virtual int FilterEvent(wxEvent& event);
 


@@ -111,6 +113,20 @@ public:
                              wxEventFunction func,
                              wxEvent& event) const;
 
                              wxEventFunction func,
                              wxEvent& event) const;
 

+    /**
+        Returns @true if the application is using an event loop.
+
+        This function always returns @true for the GUI applications which
+        must use an event loop but by default only returns @true for the
+        console programs if an event loop is already running as it can't know
+        whether one will be created in the future.
+
+        Thus, it only makes sense to override it in console applications which
+        do use an event loop, to return @true instead of checking if there is a
+        currently active event loop.
+     */
+    virtual bool UsesEventLoop() const;
+

     //@}
 
 
     //@}
 
 


@@ -129,19 +145,19 @@ public:
 
         This happens during each event loop iteration (see wxEventLoopBase) in GUI mode but
         it may be also called directly.
 
         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.
         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.
     */
     virtual void ProcessPendingEvents();
         This function will immediately return and do nothing if SuspendProcessingOfPendingEvents()
         was called.
     */
     virtual void ProcessPendingEvents();

-    
+

     /**
         Deletes the pending events of all wxEvtHandlers of this application.
     /**
         Deletes the pending events of all wxEvtHandlers of this application.

-        
+

         See wxEvtHandler::DeletePendingEvents() for warnings about deleting the pending
         events.
     */
         See wxEvtHandler::DeletePendingEvents() for warnings about deleting the pending
         events.
     */


@@ -149,9 +165,9 @@ public:
 
     /**
         Returns @true if there are pending events on the internal pending event list.
 
     /**
         Returns @true if there are pending events on the internal pending event list.

-        
+

         Whenever wxEvtHandler::QueueEvent or wxEvtHandler::AddPendingEvent() are
         Whenever wxEvtHandler::QueueEvent or wxEvtHandler::AddPendingEvent() are

-        called (not only for wxApp itself, but for any event handler of the application!), 
+        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.
     */
         the internal wxApp's list of handlers with pending events is updated and this
         function will return true.
     */


@@ -172,6 +188,42 @@ public:
 
     //@}
 
 
     //@}
 

+    /**
+        Delayed objects destruction.
+
+        In applications using events it may be unsafe for an event handler to
+        delete the object which generated the event because more events may be
+        still pending for the same object. In this case the handler may call
+        ScheduleForDestruction() instead.
+     */
+    //@{
+
+    /**
+        Schedule the object for destruction in the near future.
+
+        Notice that if the application is not using an event loop, i.e. if
+        UsesEventLoop() returns @false, this method will simply delete the
+        object immediately.
+
+        Examples of using this function inside wxWidgets itself include
+        deleting the top level windows when they are closed and sockets when
+        they are disconnected.
+     */
+    void ScheduleForDestruction(wxObject *object);
+
+    /**
+        Check if the object had been scheduled for destruction with
+        ScheduleForDestruction().
+
+        This function may be useful as an optimization to avoid doing something
+        with an object which will be soon destroyed in any case.
+     */
+    bool IsScheduledForDestruction(wxObject *object) const;
+
+    //@}
+
+
+    bool Yield(bool onlyIfNeeded = false);

 
     /**
         Allows external code to modify global ::wxTheApp, but you should really
 
     /**
         Allows external code to modify global ::wxTheApp, but you should really


@@ -202,55 +254,6 @@ public:
     */
     static bool IsMainLoopRunning();
 
     */
     static bool IsMainLoopRunning();
 

-
-    /**
-        @name Mac-specific functions
-    */
-    //@{
-
-    /**
-        Called in response of an "open-application" Apple event.
-        Override this to create a new document in your app.
-
-        @onlyfor{wxmac}
-    */
-    virtual void MacNewFile();
-
-    /**
-        Called in response of an "open-document" Apple event.
-
-        You need to override this method in order to open a document file after the
-        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}
-    */
-    virtual void MacOpenFile(const wxString& fileName);
-
-    /**
-        Called in response of a "get-url" Apple event.
-
-        @onlyfor{wxmac}
-    */
-    virtual void MacOpenURL(const wxString& url);
-
-    /**
-        Called in response of a "print-document" Apple event.
-
-        @onlyfor{wxmac}
-    */
-    virtual void MacPrintFile(const wxString& fileName);
-
-    /**
-        Called in response of a "reopen-application" Apple event.
-
-        @onlyfor{wxmac}
-    */
-    virtual void MacReopenApp();
-
-    //@}
-
-

     /**
         @name Callbacks for application-wide "events"
     */
     /**
         @name Callbacks for application-wide "events"
     */


@@ -372,7 +375,7 @@ public:
 
     /**
         This function may be called if something fatal happens: an unhandled
 
     /**
         This function may be called if something fatal happens: an unhandled

-        exception under Win32 or a a fatal signal under Unix, for example. However,
+        exception under Win32 or a fatal signal under Unix, for example. However,

         this will not happen by default: you have to explicitly call
         wxHandleFatalExceptions() to enable this.
 
         this will not happen by default: you have to explicitly call
         wxHandleFatalExceptions() to enable this.
 


@@ -391,7 +394,7 @@ public:
         You may use OnExit() to clean up anything initialized here, provided
         that the function returns @true.
 
         You may use OnExit() to clean up anything initialized here, provided
         that the function returns @true.
 

-        Notice that if you want to to use the command line processing provided by
+        Notice that if you want to use the command line processing provided by

         wxWidgets you have to call the base class version in the derived class
         OnInit().
 
         wxWidgets you have to call the base class version in the derived class
         OnInit().
 


@@ -420,15 +423,21 @@ public:
     virtual int OnRun();
 
     /**
     virtual int OnRun();
 
     /**

-        This function is called when an unhandled C++ exception occurs inside
-        OnRun() (the exceptions which occur during the program startup and shutdown
-        might not be caught at all). Notice that by now the main event loop has been
-        terminated and the program will exit, if you want to prevent this from happening
-        (i.e. continue running after catching an exception) you need to override
-        OnExceptionInMainLoop().
+        This function is called when an unhandled C++ exception occurs in user
+        code called by wxWidgets.
+
+        Any unhandled exceptions thrown from (overridden versions of) OnInit()
+        and OnExit() methods as well as any exceptions thrown from inside the
+        main loop and re-thrown by OnUnhandledException() will result in a call
+        to this function.

 
 

-        The default implementation shows information about the exception in debug build
-        but does nothing in the release build.
+        By the time this function is called, the program is already about to
+        exit and the exception can't be handled nor ignored any more, override
+        OnUnhandledException() or use explicit @c try/catch blocks around
+        OnInit() body to be able to handle the exception earlier.
+
+        The default implementation dumps information about the exception using
+        wxMessageOutputBest.

     */
     virtual void OnUnhandledException();
 
     */
     virtual void OnUnhandledException();
 


@@ -447,8 +456,13 @@ public:
         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
         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().
+        configuration file keys.
+
+        If the application name for display had been previously set by
+        SetAppDisplayName(), it will be returned by this function. Otherwise,
+        if SetAppName() had been called its value will be returned; also as is.
+        Finally if none was called, this function returns the program name
+        capitalized using wxString::Capitalize().

 
         @since 2.9.0
     */
 
         @since 2.9.0
     */


@@ -457,8 +471,9 @@ public:
     /**
         Returns the application name.
 
     /**
         Returns the application name.
 

-        @remarks wxWidgets sets this to a reasonable default before calling
-                 OnInit(), but the application can reset it at will.
+        If SetAppName() had been called, returns the string passed to it.
+        Otherwise returns the program name, i.e. the value of @c argv[0] passed
+        to the @c main() function.

 
         @see GetAppDisplayName()
     */
 
         @see GetAppDisplayName()
     */


@@ -557,7 +572,7 @@ public:
 
         Under Windows and Linux/Unix, you should parse the command line
         arguments and check for files to be opened when starting your
 
         Under Windows and Linux/Unix, you should parse the command line
         arguments and check for files to be opened when starting your

-        application. Under OS X, you need to override MacOpenFile()
+        application. Under OS X, you need to override MacOpenFiles()

         since command line arguments are used differently there.
 
         You may use the wxCmdLineParser to parse command line arguments.
         since command line arguments are used differently there.
 
         You may use the wxCmdLineParser to parse command line arguments.


@@ -620,7 +635,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

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

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


@@ -710,22 +725,9 @@ public:
     */
     bool ProcessMessage(WXMSG* msg);
 
     */
     bool ProcessMessage(WXMSG* msg);
 

-    /**
-        Sends idle events to a window and its children.
-        Please note that this function is internal to wxWidgets and shouldn't be used
-        by user code.
-
-        @remarks These functions poll the top-level windows, and their children,
-                 for idle event processing. If @true is returned, more OnIdle
-                 processing is requested by one or more window.
-
-        @see wxIdleEvent
-    */
-    virtual bool SendIdleEvents(wxWindow* win, wxIdleEvent& event);
-

     /**
         Set display mode to use. This is only used in framebuffer wxWidgets
     /**
         Set display mode to use. This is only used in framebuffer wxWidgets

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

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


@@ -788,6 +790,72 @@ public:
             visual and abort the app if none is found.
     */
     void SetUseBestVisual(bool flag, bool forceTrueColour = false);
             visual and abort the app if none is found.
     */
     void SetUseBestVisual(bool flag, bool forceTrueColour = false);

+
+
+    /**
+        @name Mac-specific functions
+    */
+    //@{
+
+    /**
+        Called in response of an "open-application" Apple event.
+        Override this to create a new document in your app.
+
+        @onlyfor{wxosx}
+    */
+    virtual void MacNewFile();
+
+    /**
+        Called in response of an openFiles message with Cocoa, or an
+        "open-document" Apple event with Carbon.
+
+        You need to override this method in order to open one or more document
+        files after the user double clicked on it or if the files and/or
+        folders were dropped on either the application in the dock or the
+        application icon in Finder.
+
+        By default this method calls MacOpenFile for each file/folder.
+
+        @onlyfor{wxosx}
+
+        @since 2.9.3
+    */
+    virtual void MacOpenFiles(const wxArrayString& fileNames);
+
+    /**
+        Called in response of an "open-document" Apple event.
+
+        @deprecated
+        This function is kept mostly for backwards compatibility. Please
+        override wxApp::MacOpenFiles method instead in any new code.
+
+        @onlyfor{wxosx}
+    */
+    virtual void MacOpenFile(const wxString& fileName);
+
+    /**
+        Called in response of a "get-url" Apple event.
+
+        @onlyfor{wxosx}
+    */
+    virtual void MacOpenURL(const wxString& url);
+
+    /**
+        Called in response of a "print-document" Apple event.
+
+        @onlyfor{wxosx}
+    */
+    virtual void MacPrintFile(const wxString& fileName);
+
+    /**
+        Called in response of a "reopen-application" Apple event.
+
+        @onlyfor{wxosx}
+    */
+    virtual void MacReopenApp();
+
+    //@}
+

 };
 
 
 };
 
 


@@ -802,35 +870,37 @@ public:
 
 /**
     This is used in headers to create a forward declaration of the ::wxGetApp()
 
 /**
     This is used in headers to create a forward declaration of the ::wxGetApp()

-    function implemented by IMPLEMENT_APP().
+    function implemented by wxIMPLEMENT_APP().

 
 

-    It creates the declaration <tt>className& wxGetApp()</tt>.
+    It creates the declaration <tt>className& wxGetApp()</tt>
+    (requires a final semicolon).

 
     @header{wx/app.h}
 
     Example:
 
     @code
 
     @header{wx/app.h}
 
     Example:
 
     @code

-    DECLARE_APP(MyApp)
+    wxDECLARE_APP(MyApp);

     @endcode
 */
     @endcode
 */

-#define DECLARE_APP( className )
+#define wxDECLARE_APP( className )

 
 /**
     This is used in the application class implementation file to make the
     application class known to wxWidgets for dynamic construction.
 
 /**
     This is used in the application class implementation file to make the
     application class known to wxWidgets for dynamic construction.

+    Note that this macro requires a final semicolon.

 
     @header{wx/app.h}
 
     Example:
 
     @code
 
     @header{wx/app.h}
 
     Example:
 
     @code

-    IMPLEMENT_APP(MyApp)
+    wxIMPLEMENT_APP(MyApp);

     @endcode
 
     @endcode
 

-    @see DECLARE_APP().
+    @see wxDECLARE_APP()

 */
 */

-#define IMPLEMENT_APP( className )
+#define wxIMPLEMENT_APP( className )

 
 //@}
 
 
 //@}
 


@@ -850,10 +920,10 @@ wxApp *wxTheApp;
 
 /**
     This function doesn't exist in wxWidgets but it is created by using the
 
 /**
     This function doesn't exist in wxWidgets but it is created by using the

-    IMPLEMENT_APP() macro.
+    wxIMPLEMENT_APP() macro.

 
     Thus, before using it anywhere but in the same module where this macro is
 
     Thus, before using it anywhere but in the same module where this macro is

-    used, you must make it available using DECLARE_APP().
+    used, you must make it available using wxDECLARE_APP().

 
     The advantage of using this function compared to directly using the global
     ::wxTheApp pointer is that the latter is of type wxApp* and so wouldn't
 
     The advantage of using this function compared to directly using the global
     ::wxTheApp pointer is that the latter is of type wxApp* and so wouldn't


@@ -999,3 +1069,37 @@ void wxExit();
 
 //@}
 
 
 //@}
 

+/** @addtogroup group_funcmacro_debug */
+//@{
+
+/**
+    @def wxDISABLE_DEBUG_SUPPORT()
+
+    Use this macro to disable all debugging code in release build when not
+    using wxIMPLEMENT_APP().
+
+    Currently this macro disables assert checking and debug and trace level
+    logging messages in release build (i.e. when @c NDEBUG is defined). It is
+    used by wxIMPLEMENT_APP() macro so you only need to use it explicitly if you
+    don't use this macro but initialize wxWidgets directly (e.g. calls
+    wxEntry() or wxEntryStart() itself).
+
+    If you do not want to disable debugging code even in release build of your
+    application, you can use wxSetDefaultAssertHandler() and
+    wxLog::SetLogLevel() with @c wxLOG_Max parameter to enable assertions and
+    debug logging respectively.
+
+    @see wxDISABLE_ASSERTS_IN_RELEASE_BUILD(),
+         wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD(),
+         @ref overview_debugging
+
+    @since 2.9.1
+
+    @header{wx/app.h}
+ */
+#define wxDISABLE_DEBUG_SUPPORT() \
+    wxDISABLE_ASSERTS_IN_RELEASE_BUILD(); \
+    wxDISABLE_DEBUG_LOGGING_IN_RELEASE_BUILD()
+
+//@}
+