From 4b2214224f2fdd300791004e53d537ec901ef3ba Mon Sep 17 00:00:00 2001 From: Francesco Montorsi Date: Sun, 25 Jan 2009 17:11:13 +0000 Subject: [PATCH] organize in groups wxAppConsole functions git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@58403 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- interface/wx/app.h | 252 +++++++++++++++++++++++++-------------------- 1 file changed, 138 insertions(+), 114 deletions(-) diff --git a/interface/wx/app.h b/interface/wx/app.h index 307a697bc7..893ee20c6c 100644 --- a/interface/wx/app.h +++ b/interface/wx/app.h @@ -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). @@ -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. -- 2.45.2