adding a app-defined event seems to quit inner eventloops like eg the popup of the...

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

diff --git a/interface/wx/app.h b/interface/wx/app.h
index 4fea75c14b9555bcf9245d79e0ace7be1fcac068..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

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


@@ -11,16 +11,34 @@
     @class wxAppConsole
 
     This class is essential for writing console-only or hybrid apps without
     @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}
 
 
     @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:
     /**
 {
 protected:
     /**


@@ -37,175 +55,209 @@ 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();
 
     /**

+        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);
 
     /**

-        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
 
     /**
         This function is called when an assert failure occurs, i.e. the condition


@@ -272,6 +324,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


@@ -303,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.
 


@@ -322,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().
 


@@ -351,24 +423,94 @@ 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();
 

+    //@}
+
+
+    /**
+        @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
 
     /**
         Set the application name to be used in the user-visible places such as


@@ -402,17 +544,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


@@ -428,31 +559,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).


@@ -464,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.


@@ -478,26 +586,38 @@ public:
 /**
     @class wxApp
 
 /**
     @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}
 
 
     @library{wxbase}
     @category{appmanagement}
 

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

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


@@ -513,6 +633,12 @@ public:
     */
     virtual ~wxApp();
 
     */
     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.
 
     /**
         Returns @true if the application will exit when the top-level frame is deleted.
 


@@ -520,6 +646,12 @@ public:
     */
     bool GetExitOnFrameDelete() const;
 
     */
     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.
     /**
         Returns @true if the application will use the best visual on systems that support
         different visuals, @false otherwise.


@@ -531,9 +663,10 @@ public:
     /**
         Returns a pointer to the top window.
 
     /**
         Returns a pointer to the top window.
 

-        @remarks If the top window hasn't been set using SetTopWindow(),
-                 this function will find the first top-level window
-                 (frame or dialog) and return that.
+        @remarks
+            If the top window hasn't been set using SetTopWindow(), this function
+            will find the first top-level window (frame or dialog or instance of
+            wxTopLevelWindow) from the internal top level window list and return that.

 
         @see SetTopWindow()
     */
 
         @see SetTopWindow()
     */


@@ -548,6 +681,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.


@@ -574,17 +726,10 @@ 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
+        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
 
     /**
         Allows the programmer to specify whether the application will exit when the


@@ -598,17 +743,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.
 


@@ -624,9 +758,13 @@ public:
         Sets the 'top' window. You can call this from within OnInit() to let wxWidgets
         know which is the main window. You don't have to set the top window;
         it is only a convenience so that (for example) certain dialogs without parents
         Sets the 'top' window. You can call this from within OnInit() to let wxWidgets
         know which is the main window. You don't have to set the top window;
         it is only a convenience so that (for example) certain dialogs without parents

-        can use a specific window as the top window. If no top window is specified by the
-        application, wxWidgets just uses the first frame or dialog in its top-level window
-        list, when it needs to use the top window.
+        can use a specific window as the top window.
+
+        If no top window is specified by the application, wxWidgets just uses the
+        first frame or dialog (or better, any wxTopLevelWindow) in its top-level
+        window list, when it needs to use the top window.
+        If you previously called SetTopWindow() and now you need to restore this
+        automatic behaviour you can call @code wxApp::SetTopWindow(NULL) @endcode.

 
         @param window
             The new top window.
 
         @param window
             The new top window.


@@ -652,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();
+
+    //@}
+

 };
 
 
 };
 
 


@@ -661,40 +865,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
 
     @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 )

 
 //@}
 
 
 //@}
 


@@ -709,15 +915,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
 //@{
 
 /**
     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


@@ -784,22 +990,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}
 */


@@ -851,7 +1053,7 @@ int wxEntry(HINSTANCE hInstance,
 
 
 
 
 
 

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

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


@@ -867,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()
+
+//@}
+