X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/afc31d8ad8cb0712fa538126711d73bb30305679..1ec4e9c2b72a01a7ba7da569e0f8d04a81aaba10:/interface/wx/app.h

diff --git a/interface/wx/app.h b/interface/wx/app.h
index 595fe78aab..72f31f4319 100644
--- a/interface/wx/app.h
+++ b/interface/wx/app.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxApp
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 
@@ -11,16 +11,34 @@
     @class wxAppConsole
 
     This class is essential for writing console-only or hybrid apps without
-    having to define wxUSE_GUI=0.
+    having to define @c wxUSE_GUI=0.
+
+    It is used to:
+    @li set and get application-wide properties (see wxAppConsole::CreateTraits
+        and wxAppConsole::SetXXX functions)
+    @li implement the windowing system message or event loop: events in fact are
+        supported even in console-mode applications (see wxAppConsole::HandleEvent
+        and wxAppConsole::ProcessPendingEvents);
+    @li initiate application processing via wxApp::OnInit;
+    @li allow default processing of events not handled by other
+        objects in the application (see wxAppConsole::FilterEvent)
+    @li implement Apple-specific event handlers (see wxAppConsole::MacXXX functions)
+
+    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.
 
-    @todo MORE INFO
+    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.
 
     @library{wxbase}
     @category{appmanagement}
 
-    @see @ref overview_app
+    @see @ref overview_app, wxApp, wxAppTraits, wxEventLoopBase
 */
-class wxAppConsole : public wxEvtHandler
+class wxAppConsole : public wxEvtHandler,
+                     public wxEventFilter
 {
 protected:
     /**
@@ -37,175 +55,209 @@ public:
     */
     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.
+
+        This function simply calls wxEvtLoopBase::Exit() on the active loop.
     */
     virtual void ExitMainLoop();
 
     /**
+        Overridden wxEventFilter method.
+
         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);
 
     /**
-        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().
+        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;
 
-        @since 2.9.0
+    /**
+        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.
     */
-    wxString GetAppDisplayName() const;
+    virtual void HandleEvent(wxEvtHandler* handler,
+                             wxEventFunction func,
+                             wxEvent& event) const;
 
     /**
-        Returns the application name.
+        Returns @true if the application is using an event loop.
 
-        @remarks wxWidgets sets this to a reasonable default before calling
-                 OnInit(), but the application can reset it at will.
+        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;
+
+    //@}
 
-        @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.
+        Process all pending events; it is necessary to call this function to
+        process events posted with wxEvtHandler::QueueEvent or wxEvtHandler::AddPendingEvent.
 
-        @see SetInstance()
+        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();
 
     /**
-        Returns a pointer to the wxAppTraits object for the application.
-        If you want to customize the wxAppTraits object, you must override the
-        CreateTraits() function.
+        Deletes the pending events of all wxEvtHandlers of this application.
+
+        See wxEvtHandler::DeletePendingEvents() for warnings about deleting the pending
+        events.
     */
-    wxAppTraits* GetTraits();
+    void DeletePendingEvents();
 
     /**
-        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.
+        Returns @true if there are pending events on the internal pending event list.
 
-        By default, returns the same string as GetVendorName().
-
-        @since 2.9.0
+        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.
     */
-    const wxString& GetVendorDisplayName() const;
+    bool HasPendingEvents() const;
 
     /**
-        Returns the application's vendor name.
+        Temporary suspends processing of the pending events.
+
+        @see ResumeProcessingOfPendingEvents()
     */
-    const wxString& GetVendorName() const;
+    void SuspendProcessingOfPendingEvents();
 
     /**
-        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.
+        Resume processing of the pending events previously stopped because of a
+        call to SuspendProcessingOfPendingEvents().
     */
-    virtual void HandleEvent(wxEvtHandler* handler,
-                             wxEventFunction func,
-                             wxEvent& event) const;
+    void ResumeProcessingOfPendingEvents();
+
+    //@}
 
     /**
-        Returns @true if the main event loop is currently running, i.e. if the
-        application is inside OnRun().
+        Delayed objects destruction.
 
-        This can be useful to test whether events can be dispatched. For example,
-        if this function returns @false, non-blocking sockets cannot be used because
-        the events from them would never be processed.
-    */
-    static bool IsMainLoopRunning();
+        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.
+     */
+    //@{
 
     /**
-        Called in response of an "open-application" Apple event.
-        Override this to create a new document in your app.
+        Schedule the object for destruction in the near future.
 
-        @onlyfor{wxmac}
-    */
-    virtual void MacNewFile();
+        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);
 
     /**
-        Called in response of an "open-document" Apple event.
+        Check if the object had been scheduled for destruction with
+        ScheduleForDestruction().
 
-        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.
+        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;
+
+    //@}
 
-        @onlyfor{wxmac}
-    */
-    virtual void MacOpenFile(const wxString& fileName);
+
+    bool Yield(bool onlyIfNeeded = false);
 
     /**
-        Called in response of a "get-url" Apple event.
+        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.
 
-        @onlyfor{wxmac}
+        @see GetInstance()
     */
-    virtual void MacOpenURL(const wxString& url);
+    static void SetInstance(wxAppConsole* app);
 
     /**
-        Called in response of a "print-document" Apple event.
+        Returns the one and only global application object.
+        Usually ::wxTheApp is used instead.
 
-        @onlyfor{wxmac}
+        @see SetInstance()
     */
-    virtual void MacPrintFile(const wxString& fileName);
+    static wxAppConsole* GetInstance();
 
     /**
-        Called in response of a "reopen-application" Apple event.
+        Returns @true if the main event loop is currently running, i.e. if the
+        application is inside OnRun().
 
-        @onlyfor{wxmac}
+        This can be useful to test whether events can be dispatched. For example,
+        if this function returns @false, non-blocking sockets cannot be used because
+        the events from them would never be processed.
     */
-    virtual void MacReopenApp();
+    static bool IsMainLoopRunning();
 
     /**
-        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
@@ -272,6 +324,26 @@ 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.
+
+        @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
@@ -303,7 +375,7 @@ public:
 
     /**
         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.
 
@@ -322,7 +394,7 @@ public:
         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().
 
@@ -351,24 +423,94 @@ public:
     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();
 
+    //@}
+
+
+    /**
+        @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.
+
+        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
+    */
+    wxString GetAppDisplayName() const;
+
+    /**
+        Returns the application name.
+
+        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()
+    */
+    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.
+
+        By default, returns the same string as GetVendorName().
 
-        @see Dispatch()
+        @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
@@ -402,17 +544,6 @@ public:
     */
     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
@@ -428,31 +559,35 @@ public:
     */
     void SetVendorName(const wxString& name);
 
+    //@}
+
     /**
-        Yields control to pending messages in the windowing system.
+        Sets the C locale to the default locale for the current environment.
 
-        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.
+        It is advised to call this to ensure that the underlying toolkit uses
+        the locale in which the numbers and monetary amounts are shown in the
+        format expected by user and so on.
 
-        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.
+        Calling this function is roughly equivalent to calling
+        @code
+            setlocale(LC_ALL, "");
+        @endcode
+        but performs additional toolkit-specific tasks under some platforms and
+        so should be used instead of @c setlocale() itself. Alternatively, you
+        can use wxLocale to change the locale with more control.
 
-        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.
+        Notice that this does @em not change the global C++ locale, you need to
+        do it explicitly if you want, e.g.
+        @code
+            std::locale::global(std::locale(""));
+        @endcode
+        but be warned that locale support in C++ standard library can be poor
+        or worse under some platforms, e.g. the above line results in an
+        immediate crash under OS X up to the version 10.8.2.
 
-        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);
+        @since 2.9.5
+     */
+    void SetCLocale();
 
     /**
         Number of command line arguments (after environment-specific processing).
@@ -464,7 +599,7 @@ public:
 
         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.
@@ -478,26 +613,38 @@ public:
 /**
     @class wxApp
 
-    The wxApp class represents the application itself. It is used to:
-
-    @li set and get application-wide properties;
-    @li implement the windowing system message or event loop;
-    @li initiate application processing via wxApp::OnInit;
-    @li allow default processing of events not handled by other
-        objects in the application.
-
-    You should use the macro IMPLEMENT_APP(appClass) in your application
-    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
-    (which returns a reference to your application object) to be visible to other
-    files.
+    The wxApp class represents the application itself when @c wxUSE_GUI=1.
+
+    In addition to the features provided by wxAppConsole it keeps track of
+    the <em>top window</em> (see SetTopWindow()) and adds support for
+    video modes (see SetVideoMode()).
+
+    In general, application-wide settings for GUI-only apps are accessible
+    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}
 
-    @see @ref overview_app
+    @see @ref overview_app, wxAppTraits, wxEventLoopBase, wxSystemSettings
 */
 class wxApp : public wxAppConsole
 {
@@ -513,6 +660,12 @@ public:
     */
     virtual ~wxApp();
 
+    /**
+        Get display mode that is used use. This is only used in framebuffer
+        wxWidgets ports such as wxDFB.
+    */
+    virtual wxVideoMode GetDisplayMode() const;
+
     /**
         Returns @true if the application will exit when the top-level frame is deleted.
 
@@ -520,6 +673,12 @@ public:
     */
     bool GetExitOnFrameDelete() const;
 
+    /**
+        Return the layout direction for the current locale or @c wxLayout_Default
+        if it's unknown.
+    */
+    virtual wxLayoutDirection GetLayoutDirection() const;
+
     /**
         Returns @true if the application will use the best visual on systems that support
         different visuals, @false otherwise.
@@ -549,6 +708,25 @@ public:
     */
     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.
@@ -575,17 +753,10 @@ public:
     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
+        Set display mode to use. This is only used in framebuffer wxWidgets
+        ports such as wxDFB.
     */
-    virtual bool SendIdleEvents(wxWindow* win, wxIdleEvent& event);
+    virtual bool SetDisplayMode(const wxVideoMode& info);
 
     /**
         Allows the programmer to specify whether the application will exit when the
@@ -599,17 +770,6 @@ public:
     */
     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.
 
@@ -657,6 +817,72 @@ public:
             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();
+
+    //@}
+
 };
 
 
@@ -666,40 +892,42 @@ public:
 // ============================================================================
 
 
-/** @ingroup group_funcmacro_rtti */
+/** @addtogroup group_funcmacro_rtti */
 //@{
 
 /**
-    This is used in headers to create a forward declaration of the wxGetApp()
-    function implemented by IMPLEMENT_APP().
+    This is used in headers to create a forward declaration of the ::wxGetApp()
+    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
-    DECLARE_APP(MyApp)
+    wxDECLARE_APP(MyApp);
     @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.
+    Note that this macro requires a final semicolon.
 
     @header{wx/app.h}
 
     Example:
 
     @code
-    IMPLEMENT_APP(MyApp)
+    wxIMPLEMENT_APP(MyApp);
     @endcode
 
-    @see DECLARE_APP().
+    @see wxDECLARE_APP()
 */
-#define IMPLEMENT_APP( className )
+#define wxIMPLEMENT_APP( className )
 
 //@}
 
@@ -714,15 +942,15 @@ wxApp *wxTheApp;
 
 
 
-/** @ingroup group_funcmacro_appinitterm */
+/** @addtogroup group_funcmacro_appinitterm */
 //@{
 
 /**
     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
-    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
@@ -789,22 +1017,18 @@ void wxUninitialize();
 void wxWakeUpIdle();
 
 /**
-    Calls wxApp::Yield.
+    Calls wxAppConsole::Yield.
 
     @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();
 
 /**
-    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}
 */
@@ -856,7 +1080,7 @@ int wxEntry(HINSTANCE hInstance,
 
 
 
-/** @ingroup group_funcmacro_procctrl */
+/** @addtogroup group_funcmacro_procctrl */
 //@{
 
 /**
@@ -872,3 +1096,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()
+
+//@}
+