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