X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4701dc09838c3da46a8bc2836265a7dffee541ee..ca282726be518ce2f214b890dbaafce736f14e36:/interface/wx/stdpaths.h diff --git a/interface/wx/stdpaths.h b/interface/wx/stdpaths.h index ee4c21030e..9cd97ca917 100644 --- a/interface/wx/stdpaths.h +++ b/interface/wx/stdpaths.h @@ -3,7 +3,7 @@ // Purpose: interface of wxStandardPaths // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -12,17 +12,30 @@ 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: - the system administrator may change the standard directories locations, i.e. + the system administrator may change the standard directories locations, e.g. the Windows directory may be named @c "W:\Win2003" instead of the default @c "C:\Windows". - The strings @c appname and @c username should be replaced with the value - returned by wxApp::GetAppName() and the name of the currently logged in user, - respectively. The string @c prefix is only used under Unix and is @c /usr/local by - default but may be changed using wxStandardPaths::SetInstallPrefix. + 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, 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. + and @c prefix is only used under Unix and is @c /usr/local by default but + may be changed using wxStandardPaths::SetInstallPrefix(). The directories returned by the methods of this class may or may not exist. If they don't exist, it's up to the caller to create them, wxStandardPaths doesn't @@ -36,10 +49,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} @@ -48,10 +57,51 @@ 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. + + After a call to this function the program directory will be exactly the + directory containing the main application binary, i.e. it undoes the + effect of any previous IgnoreAppSubDir() calls including the ones done + indirectly by IgnoreAppBuildSubDirs() called from the class + constructor. + + @since 2.9.1 + */ + void DontIgnoreAppSubDir(); + /** Returns reference to the unique global standard paths object. */ - static wxStandardPathsBase Get(); + static wxStandardPaths& Get(); + + /** + Return the directory for the document files used by this application. + + If the application-specific directory doesn't exist, this function + returns GetDocumentsDir(). + + Example return values: + - Unix: @c ~/appinfo + - Windows: @c "C:\Documents and Settings\username\My Documents\appinfo" + - Mac: @c ~/Documents/appinfo + + @since 2.9.0 + + @see GetAppDocumentsDir() + */ + virtual wxString GetAppDocumentsDir() const; /** Return the directory containing the system config files. @@ -67,10 +117,19 @@ public: /** Return the location of the applications global, i.e. not user-specific, data files. + Example return values: - - Unix: @c prefix/share/appname + - Unix: @c prefix/share/appinfo - Windows: the directory where the executable file is located - - Mac: @c appname.app/Contents/SharedSupport bundle subdirectory + - 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() */ @@ -78,12 +137,15 @@ public: /** Return the directory containing the current user's documents. + Example return values: - Unix: @c ~ (the home directory) - Windows: @c "C:\Documents and Settings\username\My Documents" - Mac: @c ~/Documents @since 2.7.0 + + @see GetAppDocumentsDir() */ virtual wxString GetDocumentsDir() const; @@ -92,7 +154,7 @@ 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; @@ -103,7 +165,10 @@ public: 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; @@ -111,7 +176,7 @@ public: Return the location for application data files which are host-specific and can't, or shouldn't, be shared with the other machines. - This is the same as GetDataDir() except under Unix where it returns @c /etc/appname. + This is the same as GetDataDir() except under Unix where it returns @c /etc/appinfo. */ virtual wxString GetLocalDataDir() const; @@ -126,15 +191,16 @@ public: @since 2.7.0 */ - wxString GetLocalizedResourcesDir(const wxString& lang, - ResourceCat category = ResourceCat_None) const; + virtual wxString + GetLocalizedResourcesDir(const wxString& lang, + ResourceCat category = ResourceCat_None) const; /** Return the directory where the loadable modules (plugins) live. Example return values: - - Unix: @c prefix/lib/appname + - Unix: @c prefix/lib/appinfo - Windows: the directory of the executable file - - Mac: @c appname.app/Contents/PlugIns bundle subdirectory + - Mac: @c appinfo.app/Contents/PlugIns bundle subdirectory @see wxDynamicLibrary */ @@ -148,9 +214,9 @@ public: This function is the same as GetDataDir() for all platforms except Mac OS X. Example return values: - - Unix: @c prefix/share/appname + - Unix: @c prefix/share/appinfo - Windows: the directory where the executable file is located - - Mac: @c appname.app/Contents/Resources bundle subdirectory + - Mac: @c appinfo.app/Contents/Resources bundle subdirectory @since 2.7.0 @@ -174,15 +240,16 @@ 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; /** Return the directory for the user-dependent application data files: - - Unix: @c ~/.appname - - Windows: @c "C:\Documents and Settings\username\Application Data\appname" - - Mac: @c "~/Library/Application Support/appname" + - Unix: @c ~/.appinfo + - Windows: @c "C:\Documents and Settings\username\Application Data\appinfo" + - Mac: @c "~/Library/Application Support/appinfo" */ virtual wxString GetUserDataDir() const; @@ -191,10 +258,77 @@ public: the other machines. This is the same as GetUserDataDir() for all platforms except Windows where it returns - @c "C:\Documents and Settings\username\Local Settings\Application Data\appname" + @c "C:\Documents and Settings\username\Local Settings\Application Data\appinfo" */ virtual wxString GetUserLocalDataDir() const; + /** + MSW-specific function to customize application directory detection. + + This class supposes that data, plugins &c files are located under the + program directory which is the directory containing the application + binary itself. But sometimes this binary may be in a subdirectory of + the main program directory, e.g. this happens in at least the following + common cases: + - The program is in "bin" subdirectory of the installation directory. + - The program is in "debug" subdirectory of the directory containing + sources and data files during development + + By calling this function you instruct the class to remove the last + component of the path if it matches its argument. Notice that it may be + called more than once, e.g. you can call both IgnoreAppSubDir("bin") and + IgnoreAppSubDir("debug") to take care of both production and development + cases above but that each call will only remove the last path component. + Finally note that the argument can contain wild cards so you can also + call IgnoreAppSubDir("vc*msw*") to ignore all build directories at once + when using wxWidgets-inspired output directories names. + + @since 2.9.1 + + @see IgnoreAppBuildSubDirs() + + @param subdirPattern + The subdirectory containing the application binary which should be + ignored when determining the top application directory. The pattern + is case-insensitive and may contain wild card characters @c '?' and + @c '*'. + */ + void IgnoreAppSubDir(const wxString& subdirPattern); + + /** + MSW-specific function to ignore all common build directories. + + This function calls IgnoreAppSubDir() with all common values for build + directory, e.g. @c "debug" and @c "release". + + It is called by the class constructor and so the build directories are + always ignored by default. You may use DontIgnoreAppSubDir() to avoid + ignoring them if this is inappropriate for your application. + + @since 2.9.1 + */ + void IgnoreAppBuildSubDirs(); + + /** + Returns location of Windows shell special folder. + + This function is, by definition, MSW-specific. It can be used to access + pre-defined shell directories not covered by the existing methods of + this class, e.g.: + @code + #ifdef __WXMSW__ + // get the location of files waiting to be burned on a CD + wxString cdburnArea = + wxStandardPaths::MSWGetShellDir(CSIDL_CDBURN_AREA); + #endif // __WXMSW__ + @endcode + + @param csidl + + @since 2.9.1 + */ + static wxString MSWGetShellDir(int csidl); + /** Lets wxStandardPaths know about the real program installation prefix on a Unix system. By default, the value returned by GetInstallPrefix() is used. @@ -204,7 +338,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); @@ -213,12 +350,17 @@ public: should be unique to this program, such as the application data directory, the plugins directory on Unix, etc. - Valid values for @a info are @c AppInfo_None and either one or combination - of @c AppInfo_AppName and @c AppInfo_VendorName. The first one tells this - class to not use neither application nor vendor name in the paths. + Valid values for @a info are: + - @c AppInfo_None: don't use neither application nor vendor name in + the paths. + - @c AppInfo_AppName: use the application name in the paths. + - @c AppInfo_VendorName: use the vendor name in the paths, usually + used combined with AppInfo_AppName, i.e. as @code AppInfo_AppName | + AppInfo_VendorName @endcode + + By default, only the application name is used. - By default, only the application name is used under Unix systems but both - application and vendor names are used under Windows and Mac. + @since 2.9.0 */ void UseAppInfo(int info); };