From: Francesco Montorsi Date: Thu, 20 Mar 2008 23:45:15 +0000 (+0000) Subject: splitted wxApp docs in wxApp+wxAppConsole docs; fix the signature of the documented... X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/8064223b7b1b3657363b7a635c381b9269d95e55 splitted wxApp docs in wxApp+wxAppConsole docs; fix the signature of the documented functions git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52641 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- diff --git a/interface/app.h b/interface/app.h index da39a0ce49..295b3ba3fa 100644 --- a/interface/app.h +++ b/interface/app.h @@ -6,62 +6,48 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// + /** - @class wxApp + @class wxAppConsole @wxheader{app.h} - The wxApp class represents the application itself. It is used to: + This class is essential for writing console-only or hybrid apps without + having to define wxUSE_GUI=0. - @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. + @todo MORE INFO @library{wxbase} @category{appmanagement} @see @ref overview_app */ -class wxApp : public wxEvtHandler +class wxAppConsole : public wxEvtHandler { -public: +protected: /** - Constructor. Called implicitly with a definition of a wxApp object. - */ - wxApp(); + Creates the wxAppTraits object when GetTraits() needs it for the first time. - /** - Destructor. Will be called implicitly on program exit if the wxApp - object is created on the stack. + @see wxAppTraits */ - ~wxApp(); + virtual wxAppTraits* CreateTraits(); - /** - Creates a wxLog class for the application to use for logging errors. - The default implementation returns a new wxLogGui class. +public: - @see wxLog + /** + Constructor. */ - virtual wxLog* CreateLogTarget(); + wxAppConsole(); /** - Creates the wxAppTraits object when GetTraits() needs it for the first time. - - @see wxAppTraits + Destructor. */ - virtual wxAppTraits* CreateTraits(); + 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. @code @@ -69,9 +55,11 @@ public: Dispatch(); @endcode + @return @false if the event loop should stop and @true otherwise. + @see Pending() */ - virtual void Dispatch(); + virtual bool Dispatch(); /** Call this to explicitly exit the main message (event) loop. @@ -89,7 +77,7 @@ public: 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). */ - int FilterEvent(wxEvent& event); + virtual int FilterEvent(wxEvent& event); /** Returns the user-readable application name. @@ -122,14 +110,6 @@ public: */ wxString GetClassName() const; - /** - Returns @true if the application will exit when the top-level window is - deleted, @false otherwise. - - @see SetExitOnFrameDelete(), @ref overview_app_shutdown - */ - bool GetExitOnFrameDelete() const; - /** Returns the one and only global application object. Usually ::wxTheApp is usead instead. @@ -138,17 +118,6 @@ public: */ static wxAppConsole* GetInstance(); - /** - 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. - - @see SetTopWindow() - */ - virtual wxWindow* GetTopWindow() const; - /** Returns a pointer to the wxAppTraits object for the application. If you want to customize the wxAppTraits object, you must override the @@ -156,14 +125,6 @@ public: */ wxAppTraits* GetTraits(); - /** - Returns @true if the application will use the best visual on systems that support - different visuals, @false otherwise. - - @see SetUseBestVisual() - */ - bool GetUseBestVisual() const; - /** 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 @@ -175,12 +136,12 @@ public: @wxsince{2.9.0} */ - wxString GetVendorDisplayName() const; + const wxString& GetVendorDisplayName() const; /** Returns the application's vendor name. */ - wxString GetVendorName() const; + const wxString& GetVendorName() const; /** This function simply invokes the given method @a func of the specified @@ -189,19 +150,10 @@ public: 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. */ - virtual void HandleEvent(wxEvtHandler handler, + virtual void HandleEvent(wxEvtHandler* handler, wxEventFunction func, wxEvent& event) const; - /** - Returns @true if the application is active, i.e. if one of its windows is - currently in the foreground. - - If this function returns @false and you need to attract users attention to - the application, you may use wxTopLevelWindow::RequestUserAttention to do it. - */ - bool IsActive() const; - /** Returns @true if the main event loop is currently running, i.e. if the application is inside OnRun(). @@ -216,7 +168,7 @@ public: Mac specific. Called in response of an "open-application" Apple event. Override this to create a new document in your app. */ - void MacNewFile(); + virtual void MacNewFile(); /** Mac specific. Called in response of an "open-document" Apple event. @@ -225,22 +177,22 @@ public: user double clicked on it or if the document file was dropped on either the running application or the application icon in Finder. */ - void MacOpenFile(const wxString& fileName); + virtual void MacOpenFile(const wxString& fileName); /** Mac specific. Called in response of a "get-url" Apple event. */ - void MacOpenURL(const wxString& url); + virtual void MacOpenURL(const wxString& url); /** Mac specific. Called in response of a "print-document" Apple event. */ - void MacPrintFile(const wxString& fileName); + virtual void MacPrintFile(const wxString& fileName); /** Mac specific. Called in response of a "reopen-application" Apple event. */ - void MacReopenApp(); + virtual void MacReopenApp(); /** Called by wxWidgets on creation of the application. Override this if you wish @@ -273,10 +225,10 @@ public: the message specified as argument to wxASSERT_MSG or wxFAIL_MSG, will be @NULL if just wxASSERT or wxFAIL was used */ - void OnAssertFailure(const wxChar file, int line, - const wxChar func, - const wxChar cond, - const wxChar msg); + virtual void OnAssertFailure(const wxChar file, int line, + const wxChar func, + const wxChar cond, + const wxChar msg); /** Called when command line parsing fails (i.e. an incorrect command line option @@ -288,7 +240,7 @@ public: @see OnInitCmdLine() */ - bool OnCmdLineError(wxCmdLineParser& parser); + virtual bool OnCmdLineError(wxCmdLineParser& parser); /** Called when the help option (@c --help) was specified on the command line. @@ -299,7 +251,7 @@ public: @see OnInitCmdLine() */ - bool OnCmdLineHelp(wxCmdLineParser& parser); + virtual bool OnCmdLineHelp(wxCmdLineParser& parser); /** Called after the command line had been successfully parsed. You may override @@ -313,7 +265,7 @@ public: @see OnInitCmdLine() */ - bool OnCmdLineParsed(wxCmdLineParser& parser); + virtual bool OnCmdLineParsed(wxCmdLineParser& parser); /** This function is called if an unhandled exception occurs inside the main @@ -356,7 +308,7 @@ public: @see wxHandleFatalExceptions() */ - void OnFatalException(); + virtual void OnFatalException(); /** This must be provided by the application, and will usually create the @@ -372,14 +324,14 @@ public: Return @true to continue processing, @false to exit the application immediately. */ - bool OnInit(); + virtual bool OnInit(); /** Called from OnInit() and may be used to initialize the parser with the command line options for this application. The base class versions adds support for a few standard options only. */ - void OnInitCmdLine(wxCmdLineParser& parser); + virtual void OnInitCmdLine(wxCmdLineParser& parser); /** This virtual function is where the execution of a program written in wxWidgets @@ -413,6 +365,180 @@ public: */ virtual bool Pending(); + /** + Set the application name to be used in the user-visible places such as window + titles. See GetAppDisplayName() for more about the differences between the + display name and name. + */ + void SetAppDisplayName(const wxString& name); + + /** + Sets the name of the application. This name should be used for file names, + configuration file entries and other internal strings. For the user-visible + strings, such as the window titles, the application display name set by + SetAppDisplayName() is used instead. + + By default the application name is set to the name of its executable file. + + @see GetAppName() + */ + void SetAppName(const wxString& name); + + /** + Sets the class name of the application. This may be used in a platform specific + manner to refer to the application. + + @see GetClassName() + */ + 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 + display name and name. + */ + void SetVendorDisplayName(const wxString& name); + + /** + Sets the name of application's vendor. The name will be used + in registry access. A default name is set by wxWidgets. + + @see GetVendorName() + */ + 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). + */ + int argc; + + /** + Command line arguments (after environment-specific processing). + + 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() + since command line arguments are used differently there. + + You may use the wxCmdLineParser to parse command line arguments. + */ + wxChar** argv; +}; + + + + +/** + @class wxApp + @wxheader{app.h} + + 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. + + @library{wxbase} + @category{appmanagement} + + @see @ref overview_app +*/ +class wxApp : public wxAppConsole +{ +public: + /** + Constructor. Called implicitly with a definition of a wxApp object. + */ + wxApp(); + + /** + Destructor. Will be called implicitly on program exit if the wxApp + object is created on the stack. + */ + virtual ~wxApp(); + + /** + Returns @true if the application will exit when the top-level frame is deleted. + + @see SetExitOnFrameDelete() + */ + bool GetExitOnFrameDelete() const; + + /** + Returns @true if the application will use the best visual on systems that support + different visuals, @false otherwise. + + @see SetUseBestVisual() + */ + bool GetUseBestVisual() const; + + /** + 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. + + @see SetTopWindow() + */ + virtual wxWindow* GetTopWindow() const; + + /** + Returns @true if the application is active, i.e. if one of its windows is + currently in the foreground. + + If this function returns @false and you need to attract users attention to + the application, you may use wxTopLevelWindow::RequestUserAttention to do it. + */ + bool IsActive() const; + /** 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. @@ -449,33 +575,6 @@ public: */ bool SendIdleEvents(wxWindow* win, wxIdleEvent& event); - /** - Set the application name to be used in the user-visible places such as window - titles. See GetAppDisplayName() for more about the differences between the - display name and name. - */ - void SetAppDisplayName(const wxString& name); - - /** - Sets the name of the application. This name should be used for file names, - configuration file entries and other internal strings. For the user-visible - strings, such as the window titles, the application display name set by - SetAppDisplayName() is used instead. - - By default the application name is set to the name of its executable file. - - @see GetAppName() - */ - void SetAppName(const wxString& name); - - /** - Sets the class name of the application. This may be used in a platform specific - manner to refer to the application. - - @see GetClassName() - */ - void SetClassName(const wxString& name); - /** Allows the programmer to specify whether the application will exit when the top-level frame is deleted. @@ -508,7 +607,7 @@ public: @param theme The name of the new theme or an absolute path to a gtkrc-theme-file */ - bool SetNativeTheme(const wxString& theme); + virtual bool SetNativeTheme(const wxString& theme); /** Sets the 'top' window. You can call this from within OnInit() to let wxWidgets @@ -542,64 +641,6 @@ public: visual and abort the app if none is found. */ void SetUseBestVisual(bool flag, bool forceTrueColour = false); - - /** - Set the vendor name to be used in the user-visible places. - See GetVendorDisplayName() for more about the differences between the - display name and name. - */ - void SetVendorDisplayName(const wxString& name); - - /** - Sets the name of application's vendor. The name will be used - in registry access. A default name is set by wxWidgets. - - @see GetVendorName() - */ - 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. - */ - bool Yield(bool onlyIfNeeded = false); - - /** - Number of command line arguments (after environment-specific processing). - */ - int argc; - - /** - Command line arguments (after environment-specific processing). - - 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() - since command line arguments are used differently there. - - You may use the wxCmdLineParser to parse command line arguments. - */ - wxChar** argv; }; diff --git a/interface/apptrait.h b/interface/apptrait.h index 6089c80cff..441ba6541a 100644 --- a/interface/apptrait.h +++ b/interface/apptrait.h @@ -43,7 +43,10 @@ public: virtual wxFontMapper* CreateFontMapper(); /** - Creates the default log target for the application. + Creates a wxLog class for the application to use for logging errors. + The default implementation returns a new wxLogGui class. + + @see wxLog */ virtual wxLog* CreateLogTarget();