X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/dde19c2180ef8d6415af7bb2492bfcb0a2d5c7e4..d38315df30415b030d93172123920d69c5c5e3b6:/interface/wx/app.h

diff --git a/interface/wx/app.h b/interface/wx/app.h
index a67a414d69..4e8be1de06 100644
--- a/interface/wx/app.h
+++ b/interface/wx/app.h
@@ -24,11 +24,11 @@
         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.
 
-    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.
 
@@ -91,6 +91,14 @@ public:
     */
     virtual int FilterEvent(wxEvent& event);
 
+    /**
+        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;
 
     /**
         This function simply invokes the given method @a func of the specified
@@ -103,6 +111,113 @@ public:
                              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;
+
+    //@}
+
+
+    /**
+        @name Pending events
+
+        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).
+    */
+    //@{
+
+    /**
+        Process all pending events; it is necessary to call this function to
+        process events posted with wxEvtHandler::QueueEvent or wxEvtHandler::AddPendingEvent.
+
+        This happens during each event loop iteration (see wxEventLoopBase) in GUI mode but
+        it may be also called directly.
+
+        Note that this function does not only process the pending events for the wxApp object
+        itself (which derives from wxEvtHandler) but also the pending events for @e any
+        event handler of this application.
+
+        This function will immediately return and do nothing if SuspendProcessingOfPendingEvents()
+        was called.
+    */
+    virtual void ProcessPendingEvents();
+
+    /**
+        Deletes the pending events of all wxEvtHandlers of this application.
+
+        See wxEvtHandler::DeletePendingEvents() for warnings about deleting the pending
+        events.
+    */
+    void DeletePendingEvents();
+
+    /**
+        Returns @true if there are pending events on the internal pending event list.
+
+        Whenever wxEvtHandler::QueueEvent or wxEvtHandler::AddPendingEvent() are
+        called (not only for wxApp itself, but for any event handler of the application!),
+        the internal wxApp's list of handlers with pending events is updated and this
+        function will return true.
+    */
+    bool HasPendingEvents() const;
+
+    /**
+        Temporary suspends processing of the pending events.
+
+        @see ResumeProcessingOfPendingEvents()
+    */
+    void SuspendProcessingOfPendingEvents();
+
+    /**
+        Resume processing of the pending events previously stopped because of a
+        call to SuspendProcessingOfPendingEvents().
+    */
+    void ResumeProcessingOfPendingEvents();
+
+    //@}
+
+    /**
+        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;
+
     //@}
 
 
@@ -145,7 +260,7 @@ public:
         Called in response of an "open-application" Apple event.
         Override this to create a new document in your app.
 
-        @onlyfor{wxmac}
+        @onlyfor{wxosx}
     */
     virtual void MacNewFile();
 
@@ -156,28 +271,28 @@ public:
         user double clicked on it or if the document file was dropped on either the
         running application or the application icon in Finder.
 
-        @onlyfor{wxmac}
+        @onlyfor{wxosx}
     */
     virtual void MacOpenFile(const wxString& fileName);
 
     /**
         Called in response of a "get-url" Apple event.
 
-        @onlyfor{wxmac}
+        @onlyfor{wxosx}
     */
     virtual void MacOpenURL(const wxString& url);
 
     /**
         Called in response of a "print-document" Apple event.
 
-        @onlyfor{wxmac}
+        @onlyfor{wxosx}
     */
     virtual void MacPrintFile(const wxString& fileName);
 
     /**
         Called in response of a "reopen-application" Apple event.
 
-        @onlyfor{wxmac}
+        @onlyfor{wxosx}
     */
     virtual void MacReopenApp();
 
@@ -254,6 +369,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
@@ -360,8 +495,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
-        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
     */
@@ -370,8 +510,9 @@ public:
     /**
         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()
     */
@@ -493,6 +634,25 @@ public:
     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}
 
@@ -514,7 +674,7 @@ public:
 
     /**
         Get display mode that is used use. This is only used in framebuffer
-        wxWin ports (such as wxMGL or wxDFB).
+        wxWidgets ports (such as wxMGL or wxDFB).
     */
     virtual wxVideoMode GetDisplayMode() const;
 
@@ -618,9 +778,8 @@ public:
     virtual bool SendIdleEvents(wxWindow* win, wxIdleEvent& event);
 
     /**
-        Set display mode to use. This is only used in framebuffer wxWin
-        ports (such as wxMGL or wxDFB). This method should be called from
-        wxApp::OnInitGui.
+        Set display mode to use. This is only used in framebuffer wxWidgets
+        ports (such as wxMGL or wxDFB).
     */
     virtual bool SetDisplayMode(const wxVideoMode& info);
 
@@ -697,35 +856,37 @@ public:
 
 /**
     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
-    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 )
 
 //@}
 
@@ -745,10 +906,10 @@ wxApp *wxTheApp;
 
 /**
     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
@@ -894,3 +1055,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()
+
+//@}
+