// Purpose: interface of wxStandardPaths
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
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
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.
/**
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()
*/
/**
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;
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 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;
@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.
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
*/
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
/**
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;
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.
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);
};
projects / wxWidgets.git / blobdiff