interface/wx/stdpaths.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        stdpaths.h
   3 // Purpose:     interface of wxStandardPaths
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxStandardPaths
  11
  12     wxStandardPaths returns the standard locations in the file system and should be
  13     used by applications to find their data files in a portable way.
  14
  15     In the description of the methods below, the example return values are given
  16     for the Unix, Windows and Mac OS X systems, however please note that these are
  17     just the examples and the actual values may differ. For example, under Windows:
  18     the system administrator may change the standard directories locations, i.e.
  19     the Windows directory may be named @c W:\\Win2003 instead of
  20     the default @c C:\\Windows.
  21
  22     The strings @c appname and @c username should be
  23     replaced with the value returned by wxApp::GetAppName
  24     and the name of the currently logged in user, respectively. The string
  25     @c prefix is only used under Unix and is @c /usr/local by
  26     default but may be changed using wxStandardPaths::SetInstallPrefix.
  27
  28     The directories returned by the methods of this class may or may not exist. If
  29     they don't exist, it's up to the caller to create them, wxStandardPaths doesn't
  30     do it.
  31
  32     Finally note that these functions only work with standardly packaged
  33     applications. I.e. under Unix you should follow the standard installation
  34     conventions and under Mac you should create your application bundle according
  35     to the Apple guidelines. Again, this class doesn't help you to do it.
  36
  37     This class is MT-safe: its methods may be called concurrently from different
  38     threads without additional locking.
  39
  40     @library{wxbase}
  41     @category{file}
  42
  43     @see wxFileConfig
  44         */
  45 class wxStandardPaths
  46 {
  47 public:
  48     /**
  49         Returns reference to the unique global standard paths object.
  50     */
  51     static wxStandardPathsBase Get();
  52
  53     /**
  54         Return the directory containing the system config files.
  55         Example return values:
  56              - Unix: @c /etc
  57              - Windows: @c C:\\Documents @c and @c Settings\\All @c Users\\Application Data
  58              - Mac: @c /Library/Preferences
  59
  60         @see wxFileConfig
  61     */
  62     wxString GetConfigDir() const;
  63
  64     /**
  65         Return the location of the applications global, i.e. not user-specific,
  66         data files.
  67         Example return values:
  68              - Unix: @c prefix/share/appname
  69              - Windows: the directory where the executable file is located
  70              - Mac: @c appname.app/Contents/SharedSupport bundle subdirectory
  71
  72         @see GetLocalDataDir()
  73     */
  74     wxString GetDataDir() const;
  75
  76     /**
  77         Return the directory containing the current user's documents.
  78         Example return values:
  79              - Unix: @c ~ (the home directory)
  80              - Windows: @c C:\\Documents @c and @c Settings\\username\\Documents
  81              - Mac: @c ~/Documents
  82
  83         @since 2.7.0
  84     */
  85     wxString GetDocumentsDir() const;
  86
  87     /**
  88         Return the directory and the filename for the current executable.
  89         Example return values:
  90              - Unix: @c /usr/local/bin/exename
  91              - Windows: @c C:\\Programs\\AppFolder\\exename.exe
  92              - Mac: @c /Programs/exename
  93     */
  94     wxString GetExecutablePath() const;
  95
  96     /**
  97         @note This function is only available under Unix.
  98         Return the program installation prefix, e.g. @c /usr, @c /opt or
  99         @c /home/zeitlin.
 100         If the prefix had been previously by SetInstallPrefix(), returns that
 101         value, otherwise tries to determine it automatically (Linux only right
 102         now) and finally returns the default @c /usr/local value if it failed.
 103     */
 104     wxString GetInstallPrefix() const;
 105
 106     /**
 107         Return the location for application data files which are host-specific and
 108         can't, or shouldn't, be shared with the other machines.
 109         This is the same as GetDataDir() except
 110         under Unix where it returns @c /etc/appname.
 111     */
 112     wxString GetLocalDataDir() const;
 113
 114     /**
 115         Return the localized resources directory containing the resource files of the
 116         specified category for the given language.
 117         In general this is just the same as @a lang subdirectory of
 118         GetResourcesDir() (or @c lang.lproj under Mac OS X) but is something quite
 119         different for message catalog category under Unix where it returns the standard
 120         @c prefix/share/locale/lang/LC_MESSAGES directory.
 121
 122         @since 2.7.0
 123     */
 124     wxString GetLocalizedResourcesDir(const wxString& lang,
 125                                       ResourceCat category = ResourceCat_None) const;
 126
 127     /**
 128         Return the directory where the loadable modules (plugins) live.
 129         Example return values:
 130              - Unix: @c prefix/lib/appname
 131              - Windows: the directory of the executable file
 132              - Mac: @c appname.app/Contents/PlugIns bundle subdirectory
 133
 134         @see wxDynamicLibrary
 135     */
 136     wxString GetPluginsDir() const;
 137
 138     /**
 139         Return the directory where the application resource files are located. The
 140         resources are the auxiliary data files needed for the application to run and
 141         include, for example, image and sound files it might use.
 142         This function is the same as GetDataDir() for
 143         all platforms except Mac OS X.
 144         Example return values:
 145              - Unix: @c prefix/share/@e appname
 146              - Windows: the directory where the executable file is located
 147              - Mac: @c appname.app/Contents/Resources bundle subdirectory
 148
 149         @since 2.7.0
 150
 151         @see GetLocalizedResourcesDir()
 152     */
 153     wxString GetResourcesDir() const;
 154
 155     /**
 156         Return the directory for storing temporary files. To create unique temporary
 157         files,
 158         it is best to use wxFileName::CreateTempFileName for correct behaviour when
 159         multiple processes are attempting to create temporary files.
 160
 161         @since 2.7.2
 162     */
 163     wxString GetTempDir() const;
 164
 165     /**
 166         Return the directory for the user config files:
 167              - Unix: @c ~ (the home directory)
 168              - Windows: @c C:\\Documents @c and @c Settings\\username\\Application Data
 169              - Mac: @c ~/Library/Preferences
 170         Only use this method if you have a single configuration file to put in this
 171         directory, otherwise GetUserDataDir() is
 172         more appropriate.
 173     */
 174     wxString GetUserConfigDir() const;
 175
 176     /**
 177         Return the directory for the user-dependent application data files:
 178              - Unix: @c ~/.appname
 179              - Windows: @c C:\\Documents @c and @c Settings\\username\Application @c Data\appname
 180              - Mac: @c ~/Library/Application @c Support/appname
 181     */
 182     wxString GetUserDataDir() const;
 183
 184     /**
 185         Return the directory for user data files which shouldn't be shared with
 186         the other machines.
 187         This is the same as GetUserDataDir() for all platforms except Windows where it returns
 188         @c C:\\Documents @c and @c Settings\\username\\Local @c Settings\\Application @c Data\appname
 189     */
 190     wxString GetUserLocalDataDir() const;
 191
 192     /**
 193         @note This function is only available under Unix.
 194         Lets wxStandardPaths know about the real program installation prefix on a Unix
 195         system. By default, the value returned by
 196         GetInstallPrefix() is used.
 197         Although under Linux systems the program prefix may usually be determined
 198         automatically, portable programs should call this function. Usually the prefix
 199         is set during program configuration if using GNU autotools and so it is enough
 200         to pass its value defined in @c config.h to this function.
 201     */
 202     void SetInstallPrefix(const wxString& prefix);
 203
 204     /**
 205         Controls what application information is used when constructing paths that
 206         should be unique to this program, such as the application data directory, the
 207         plugins directory on Unix, etc.
 208         Valid values for @a info are @c AppInfo_None and either one or
 209         combination of @c AppInfo_AppName and @c AppInfo_VendorName. The
 210         first one tells this class to not use neither application nor vendor name in
 211         the paths.
 212         By default, only the application name is used under Unix systems but both
 213         application and vendor names are used under Windows and Mac.
 214     */
 215     void UseAppInfo(int info);
 216 };
 217