X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/d181e877b04950068cb809b0d3d1a911bea3de74..fcd209b6a20b41e7ddf9acf837311ac6779ea41f:/interface/wx/app.h diff --git a/interface/wx/app.h b/interface/wx/app.h index 4b93f3f140..893ee20c6c 100644 --- a/interface/wx/app.h +++ b/interface/wx/app.h @@ -35,7 +35,7 @@ @library{wxbase} @category{appmanagement} - @see @ref overview_app, wxApp, wxAppTraits, wxEventLoop + @see @ref overview_app, wxApp, wxAppTraits, wxEventLoopBase */ class wxAppConsole : public wxEvtHandler { @@ -54,6 +54,12 @@ public: */ virtual ~wxAppConsole(); + + /** + @name Event-handling + */ + //@{ + /** Dispatches the next event in the windowing system event queue. Blocks until an event appears if there are none currently @@ -68,7 +74,7 @@ public: @return @false if the event loop should stop and @true otherwise. - @see Pending() + @see Pending(), wxEventLoopBase */ virtual bool Dispatch(); @@ -90,81 +96,95 @@ public: */ virtual int FilterEvent(wxEvent& event); - /** - Returns the user-readable application name. - The difference between this string and the one returned by GetAppName() - is that this one is meant to be shown to the user and so should be used - for the window titles, page headers and so on while the other one - should be only used internally, e.g. for the file names or - configuration file keys. By default, returns the application name as - returned by GetAppName() capitalized using wxString::Capitalize(). - - @since 2.9.0 + /** + 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. - - @remarks wxWidgets sets this to a reasonable default before calling - OnInit(), but the application can reset it at will. - - @see GetAppDisplayName() + Returns @true if called from inside Yield(). */ - wxString GetAppName() const; + virtual bool IsYielding() const; /** - Gets the class name of the application. The class name may be used in a - platform specific manner to refer to the application. + Process all pending events; it is necessary to call this function to + process posted events. - @see SetClassName() + This happens during each event loop iteration in GUI mode but if there is + no main loop, it may be also called directly. */ - wxString GetClassName() const; + virtual void ProcessPendingEvents(); /** - Returns the one and only global application object. - Usually wxTheApp is used instead. + Called by wxWidgets on creation of the application. Override this if you wish + to provide your own (environment-dependent) main loop. - @see SetInstance() + @return 0 under X, and the wParam of the WM_QUIT message under Windows. */ - static wxAppConsole* GetInstance(); + virtual int MainLoop(); /** - Returns a pointer to the wxAppTraits object for the application. - If you want to customize the wxAppTraits object, you must override the - CreateTraits() function. + Returns @true if unprocessed events are in the window system event queue. + + @see Dispatch() */ - wxAppTraits* GetTraits(); + virtual bool Pending(); /** - 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. + Yields control to pending messages in the windowing system. - By default, returns the same string as GetVendorName(). + 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. - @since 2.9.0 + 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. + You can avoid unwanted reentrancies also using IsYielding(). + + 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. */ - const wxString& GetVendorDisplayName() const; + virtual bool Yield(bool onlyIfNeeded = false); + + //@} + /** - Returns the application's vendor name. + Allows external code to modify global ::wxTheApp, but you should really + know what you're doing if you call it. + + @param app + Replacement for the global application object. + + @see GetInstance() */ - const wxString& GetVendorName() const; + static void SetInstance(wxAppConsole* app); /** - This function simply invokes the given method @a func of the specified - event handler @a handler with the @a event as parameter. It exists solely - to allow to catch the C++ exceptions which could be thrown by all event - handlers in the application in one place: if you want to do this, override - this function in your wxApp-derived class and add try/catch clause(s) to it. + Returns the one and only global application object. + Usually wxTheApp is used instead. + + @see SetInstance() */ - virtual void HandleEvent(wxEvtHandler* handler, - wxEventFunction func, - wxEvent& event) const; + static wxAppConsole* GetInstance(); /** Returns @true if the main event loop is currently running, i.e. if the @@ -176,19 +196,11 @@ public: */ static bool IsMainLoopRunning(); - /** - Returns @true if called from inside Yield(). - */ - bool IsYielding() const; /** - Process all pending events; it is necessary to call this function to - process posted events. - - This happens during each event loop iteration in GUI mode but if there is - no main loop, it may be also called directly. + @name Mac-specific functions */ - virtual void ProcessPendingEvents(); + //@{ /** Called in response of an "open-application" Apple event. @@ -230,13 +242,13 @@ public: */ virtual void MacReopenApp(); - /** - Called by wxWidgets on creation of the application. Override this if you wish - to provide your own (environment-dependent) main loop. + //@} - @return 0 under X, and the wParam of the WM_QUIT message under Windows. + + /** + @name Callbacks for application-wide "events" */ - virtual int MainLoop(); + //@{ /** This function is called when an assert failure occurs, i.e. the condition @@ -394,12 +406,70 @@ public: */ virtual void OnUnhandledException(); + //@} + + /** - Returns @true if unprocessed events are in the window system event queue. + @name Application informations + */ + //@{ - @see Dispatch() + /** + Returns the user-readable application name. + + The difference between this string and the one returned by GetAppName() + is that this one is meant to be shown to the user and so should be used + for the window titles, page headers and so on while the other one + should be only used internally, e.g. for the file names or + configuration file keys. By default, returns the application name as + returned by GetAppName() capitalized using wxString::Capitalize(). + + @since 2.9.0 */ - virtual bool Pending(); + wxString GetAppDisplayName() const; + + /** + Returns the application name. + + @remarks wxWidgets sets this to a reasonable default before calling + OnInit(), but the application can reset it at will. + + @see GetAppDisplayName() + */ + wxString GetAppName() const; + + /** + Gets the class name of the application. The class name may be used in a + platform specific manner to refer to the application. + + @see SetClassName() + */ + wxString GetClassName() const; + + /** + Returns a pointer to the wxAppTraits object for the application. + If you want to customize the wxAppTraits object, you must override the + CreateTraits() function. + */ + wxAppTraits* GetTraits(); + + /** + Returns 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(). + + @since 2.9.0 + */ + 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 @@ -433,17 +503,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 @@ -459,32 +518,8 @@ public: */ 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. - You can avoid unwanted reentrancies also using IsYielding(). - - 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). @@ -517,12 +552,12 @@ public: video modes (see SetVideoMode()). In general, application-wide settings for GUI-only apps are accessible - from wxApp (or from wxSystemSettings). + from wxApp (or from wxSystemSettings or wxSystemOptions classes). @library{wxbase} @category{appmanagement} - @see @ref overview_app, wxAppTraits, wxEventLoop, wxSystemSettings + @see @ref overview_app, wxAppTraits, wxEventLoopBase, wxSystemSettings */ class wxApp : public wxAppConsole { @@ -643,17 +678,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. @@ -710,7 +734,7 @@ public: // ============================================================================ -/** @ingroup group_funcmacro_rtti */ +/** @addtogroup group_funcmacro_rtti */ //@{ /** @@ -758,7 +782,7 @@ wxApp *wxTheApp; -/** @ingroup group_funcmacro_appinitterm */ +/** @addtogroup group_funcmacro_appinitterm */ //@{ /** @@ -900,7 +924,7 @@ int wxEntry(HINSTANCE hInstance, -/** @ingroup group_funcmacro_procctrl */ +/** @addtogroup group_funcmacro_procctrl */ //@{ /**