X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4f83b9fc549a66de1e76362c9b1ff78236ef7ec7..36a0190ebd5bd9a7302f60f6dcd608b80574e21c:/interface/wx/stdpaths.h diff --git a/interface/wx/stdpaths.h b/interface/wx/stdpaths.h index 22a36bdb30..2c49a2f574 100644 --- a/interface/wx/stdpaths.h +++ b/interface/wx/stdpaths.h @@ -2,8 +2,7 @@ // Name: stdpaths.h // Purpose: interface of wxStandardPaths // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -12,6 +11,13 @@ wxStandardPaths returns the standard locations in the file system and should be used by applications to find their data files in a portable way. + Note that you must not create objects of class wxStandardPaths directly, + but use the global standard paths object returned by wxStandardPaths::Get() + (which can be of a type derived from wxStandardPaths and not of exactly + this type) and call the methods you need on it. The object returned by + Get() may be customized by overriding wxAppTraits::GetStandardPaths() + methods. + In the description of the methods below, the example return values are given for the Unix, Windows and Mac OS X systems, however please note that these are just the examples and the actual values may differ. For example, under Windows: @@ -22,8 +28,8 @@ Notice that in the examples below the string @c appinfo may be either just the application name (as returned by wxApp::GetAppName()) or a combination of the vendor name (wxApp::GetVendorName()) and the application name, with - a path separator between them. By default, the vendor name is used under - Windows and OS X but not under other Unix systems, see UseAppInfo(). + a path separator between them. By default, only the application name is + used, use UseAppInfo() to change this. The other placeholders should be self-explanatory: the string @c username should be replaced with the value the name of the currently logged in user. @@ -42,10 +48,6 @@ This class is MT-safe: its methods may be called concurrently from different threads without additional locking. - Note that you don't allocate an instance of class wxStandardPaths, but retrieve the - global standard paths object using @c wxStandardPaths::Get on which you call the - desired methods. - @library{wxbase} @category{file} @@ -54,6 +56,17 @@ class wxStandardPaths { public: + /// Possible values for category parameter of GetLocalizedResourcesDir(). + enum ResourceCat + { + /// No special category, this is the default. + ResourceCat_None, + + /// Message catalog resources category. + ResourceCat_Messages + }; + + /** MSW-specific function undoing the effect of IgnoreAppSubDir() calls. @@ -101,13 +114,22 @@ public: virtual wxString GetConfigDir() const; /** - Return the location of the applications global, i.e. not user-specific, + Return the location of the applications global, i.e.\ not user-specific, data files. + Example return values: - Unix: @c prefix/share/appinfo - Windows: the directory where the executable file is located - Mac: @c appinfo.app/Contents/SharedSupport bundle subdirectory + Under Unix (only) it is possible to override the default value returned + from this function by setting the value of @c WX_APPNAME_DATA_DIR + environment variable to the directory to use (where @c APPNAME is the + upper-cased value of wxApp::GetAppName()). This is useful in order to + be able to run applications using this function without installing them + as you can simply set this environment variable to the source directory + location to allow the application to find its files there. + @see GetLocalDataDir() */ virtual wxString GetDataDir() const; @@ -131,18 +153,21 @@ public: Example return values: - Unix: @c /usr/local/bin/exename - Windows: @c "C:\Programs\AppFolder\exename.exe" - - Mac: @c /Programs/exename + - Mac: @c /Applications/exename.app/Contents/MacOS/exename */ virtual wxString GetExecutablePath() const; /** - Return the program installation prefix, e.g. @c /usr, @c /opt or @c /home/zeitlin. + Return the program installation prefix, e.g.\ @c /usr, @c /opt or @c /home/zeitlin. If the prefix had been previously by SetInstallPrefix(), returns that value, otherwise tries to determine it automatically (Linux only right now) and finally returns the default @c /usr/local value if it failed. - @note This function is only available under Unix. + @note This function is only available under Unix platforms (but not limited + to wxGTK mentioned below). + + @onlyfor{wxos2,wxgtk} */ wxString GetInstallPrefix() const; @@ -165,8 +190,9 @@ public: @since 2.7.0 */ - virtual wxString GetLocalizedResourcesDir(const wxString& lang, - ResourceCat category) const; + virtual wxString + GetLocalizedResourcesDir(const wxString& lang, + ResourceCat category = ResourceCat_None) const; /** Return the directory where the loadable modules (plugins) live. @@ -213,7 +239,8 @@ public: - Mac: @c ~/Library/Preferences Only use this method if you have a single configuration file to put in this - directory, otherwise GetUserDataDir() is more appropriate. + directory, otherwise GetUserDataDir() is more appropriate as the latter + adds @c appinfo to the path, unlike this function. */ virtual wxString GetUserConfigDir() const; @@ -310,7 +337,10 @@ public: is set during program configuration if using GNU autotools and so it is enough to pass its value defined in @c config.h to this function. - @note This function is only available under Unix. + @note This function is only available under Unix platforms (but not limited + to wxGTK mentioned below). + + @onlyfor{wxos2,wxgtk} */ void SetInstallPrefix(const wxString& prefix); @@ -327,11 +357,20 @@ public: used combined with AppInfo_AppName, i.e. as @code AppInfo_AppName | AppInfo_VendorName @endcode - By default, only the application name is used under Unix systems but both - application and vendor names are used under Windows and Mac. + By default, only the application name is used. @since 2.9.0 */ void UseAppInfo(int info); + +protected: + /** + Protected default constructor. + + This constructor is protected in order to prevent creation of objects + of this class as Get() should be used instead to access the unique + global wxStandardPaths object of the correct type. + */ + wxStandardPaths(); };