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, e.g.
  19     the Windows directory may be named @c "W:\Win2003" instead of
  20     the default @c "C:\Windows".
  21
  22     Notice that in the examples below the string @c appinfo may be either just
  23     the application name (as returned by wxApp::GetAppName()) or a combination
  24     of the vendor name (wxApp::GetVendorName()) and the application name, with
  25     a path separator between them. By default, only the application name is
  26     used, use UseAppInfo() to change this.
  27
  28     The other placeholders should be self-explanatory: the string @c username
  29     should be replaced with the value the name of the currently logged in user.
  30     and @c prefix is only used under Unix and is @c /usr/local by default but
  31     may be changed using wxStandardPaths::SetInstallPrefix().
  32
  33     The directories returned by the methods of this class may or may not exist.
  34     If they don't exist, it's up to the caller to create them, wxStandardPaths doesn't
  35     do it.
  36
  37     Finally note that these functions only work with standardly packaged
  38     applications. I.e. under Unix you should follow the standard installation
  39     conventions and under Mac you should create your application bundle according
  40     to the Apple guidelines. Again, this class doesn't help you to do it.
  41
  42     This class is MT-safe: its methods may be called concurrently from different
  43     threads without additional locking.
  44
  45     Note that you don't allocate an instance of class wxStandardPaths, but retrieve the
  46     global standard paths object using @c wxStandardPaths::Get on which you call the
  47     desired methods.
  48
  49     @library{wxbase}
  50     @category{file}
  51
  52     @see wxFileConfig
  53 */
  54 class wxStandardPaths
  55 {
  56 public:
  57     /**
  58         MSW-specific function undoing the effect of IgnoreAppSubDir() calls.
  59
  60         After a call to this function the program directory will be exactly the
  61         directory containing the main application binary, i.e. it undoes the
  62         effect of any previous IgnoreAppSubDir() calls including the ones done
  63         indirectly by IgnoreAppBuildSubDirs() called from the class
  64         constructor.
  65
  66         @since 2.9.1
  67      */
  68     void DontIgnoreAppSubDir();
  69
  70     /**
  71         Returns reference to the unique global standard paths object.
  72     */
  73     static wxStandardPaths& Get();
  74
  75     /**
  76         Return the directory for the document files used by this application.
  77
  78         If the application-specific directory doesn't exist, this function
  79         returns GetDocumentsDir().
  80
  81         Example return values:
  82         - Unix: @c ~/appinfo
  83         - Windows: @c "C:\Documents and Settings\username\My Documents\appinfo"
  84         - Mac: @c ~/Documents/appinfo
  85
  86         @since 2.9.0
  87
  88         @see GetAppDocumentsDir()
  89      */
  90     virtual wxString GetAppDocumentsDir() const;
  91
  92     /**
  93         Return the directory containing the system config files.
  94         Example return values:
  95         - Unix: @c /etc
  96         - Windows: @c "C:\Documents and Settings\All Users\Application Data"
  97         - Mac: @c /Library/Preferences
  98
  99         @see wxFileConfig
 100     */
 101     virtual wxString GetConfigDir() const;
 102
 103     /**
 104         Return the location of the applications global, i.e. not user-specific,
 105         data files.
 106
 107         Example return values:
 108         - Unix: @c prefix/share/appinfo
 109         - Windows: the directory where the executable file is located
 110         - Mac: @c appinfo.app/Contents/SharedSupport bundle subdirectory
 111
 112         Under Unix (only) it is possible to override the default value returned
 113         from this function by setting the value of @c WX_APPNAME_DATA_DIR
 114         environment variable to the directory to use (where @c APPNAME is the
 115         upper-cased value of wxApp::GetAppName()). This is useful in order to
 116         be able to run applications using this function without installing them
 117         as you can simply set this environment variable to the source directory
 118         location to allow the application to find its files there.
 119
 120         @see GetLocalDataDir()
 121     */
 122     virtual wxString GetDataDir() const;
 123
 124     /**
 125         Return the directory containing the current user's documents.
 126
 127         Example return values:
 128         - Unix: @c ~ (the home directory)
 129         - Windows: @c "C:\Documents and Settings\username\My Documents"
 130         - Mac: @c ~/Documents
 131
 132         @since 2.7.0
 133
 134         @see GetAppDocumentsDir()
 135     */
 136     virtual wxString GetDocumentsDir() const;
 137
 138     /**
 139         Return the directory and the filename for the current executable.
 140         Example return values:
 141         - Unix: @c /usr/local/bin/exename
 142         - Windows: @c "C:\Programs\AppFolder\exename.exe"
 143         - Mac: @c /Programs/exename
 144     */
 145     virtual wxString GetExecutablePath() const;
 146
 147     /**
 148         Return the program installation prefix, e.g. @c /usr, @c /opt or @c /home/zeitlin.
 149
 150         If the prefix had been previously by SetInstallPrefix(), returns that
 151         value, otherwise tries to determine it automatically (Linux only right now)
 152         and finally returns the default @c /usr/local value if it failed.
 153
 154         @note This function is only available under Unix.
 155     */
 156     wxString GetInstallPrefix() const;
 157
 158     /**
 159         Return the location for application data files which are host-specific and
 160         can't, or shouldn't, be shared with the other machines.
 161
 162         This is the same as GetDataDir() except under Unix where it returns @c /etc/appinfo.
 163     */
 164     virtual wxString GetLocalDataDir() const;
 165
 166     /**
 167         Return the localized resources directory containing the resource files of the
 168         specified category for the given language.
 169
 170         In general this is just the same as @a lang subdirectory of GetResourcesDir()
 171         (or @c lang.lproj under Mac OS X) but is something quite different for
 172         message catalog category under Unix where it returns the standard
 173         @c prefix/share/locale/lang/LC_MESSAGES directory.
 174
 175         @since 2.7.0
 176     */
 177     virtual wxString GetLocalizedResourcesDir(const wxString& lang,
 178                                               ResourceCat category) const;
 179
 180     /**
 181         Return the directory where the loadable modules (plugins) live.
 182         Example return values:
 183         - Unix: @c prefix/lib/appinfo
 184         - Windows: the directory of the executable file
 185         - Mac: @c appinfo.app/Contents/PlugIns bundle subdirectory
 186
 187         @see wxDynamicLibrary
 188     */
 189     virtual wxString GetPluginsDir() const;
 190
 191     /**
 192         Return the directory where the application resource files are located.
 193
 194         The resources are the auxiliary data files needed for the application to run
 195         and include, for example, image and sound files it might use.
 196
 197         This function is the same as GetDataDir() for all platforms except Mac OS X.
 198         Example return values:
 199         - Unix: @c prefix/share/appinfo
 200         - Windows: the directory where the executable file is located
 201         - Mac: @c appinfo.app/Contents/Resources bundle subdirectory
 202
 203         @since 2.7.0
 204
 205         @see GetLocalizedResourcesDir()
 206     */
 207     virtual wxString GetResourcesDir() const;
 208
 209     /**
 210         Return the directory for storing temporary files.
 211         To create unique temporary files, it is best to use wxFileName::CreateTempFileName
 212         for correct behaviour when multiple processes are attempting to create temporary files.
 213
 214         @since 2.7.2
 215     */
 216     virtual wxString GetTempDir() const;
 217
 218     /**
 219         Return the directory for the user config files:
 220         - Unix: @c ~ (the home directory)
 221         - Windows: @c "C:\Documents and Settings\username\Application Data"
 222         - Mac: @c ~/Library/Preferences
 223
 224         Only use this method if you have a single configuration file to put in this
 225         directory, otherwise GetUserDataDir() is more appropriate.
 226     */
 227     virtual wxString GetUserConfigDir() const;
 228
 229     /**
 230         Return the directory for the user-dependent application data files:
 231         - Unix: @c ~/.appinfo
 232         - Windows: @c "C:\Documents and Settings\username\Application Data\appinfo"
 233         - Mac: @c "~/Library/Application Support/appinfo"
 234     */
 235     virtual wxString GetUserDataDir() const;
 236
 237     /**
 238         Return the directory for user data files which shouldn't be shared with
 239         the other machines.
 240
 241         This is the same as GetUserDataDir() for all platforms except Windows where it returns
 242         @c "C:\Documents and Settings\username\Local Settings\Application Data\appinfo"
 243     */
 244     virtual wxString GetUserLocalDataDir() const;
 245
 246     /**
 247         MSW-specific function to customize application directory detection.
 248
 249         This class supposes that data, plugins &c files are located under the
 250         program directory which is the directory containing the application
 251         binary itself. But sometimes this binary may be in a subdirectory of
 252         the main program directory, e.g. this happens in at least the following
 253         common cases:
 254          - The program is in "bin" subdirectory of the installation directory.
 255          - The program is in "debug" subdirectory of the directory containing
 256            sources and data files during development
 257
 258         By calling this function you instruct the class to remove the last
 259         component of the path if it matches its argument. Notice that it may be
 260         called more than once, e.g. you can call both IgnoreAppSubDir("bin") and
 261         IgnoreAppSubDir("debug") to take care of both production and development
 262         cases above but that each call will only remove the last path component.
 263         Finally note that the argument can contain wild cards so you can also
 264         call IgnoreAppSubDir("vc*msw*") to ignore all build directories at once
 265         when using wxWidgets-inspired output directories names.
 266
 267         @since 2.9.1
 268
 269         @see IgnoreAppBuildSubDirs()
 270
 271         @param subdirPattern
 272             The subdirectory containing the application binary which should be
 273             ignored when determining the top application directory. The pattern
 274             is case-insensitive and may contain wild card characters @c '?' and
 275             @c '*'.
 276      */
 277     void IgnoreAppSubDir(const wxString& subdirPattern);
 278
 279     /**
 280         MSW-specific function to ignore all common build directories.
 281
 282         This function calls IgnoreAppSubDir() with all common values for build
 283         directory, e.g. @c "debug" and @c "release".
 284
 285         It is called by the class constructor and so the build directories are
 286         always ignored by default. You may use DontIgnoreAppSubDir() to avoid
 287         ignoring them if this is inappropriate for your application.
 288
 289         @since 2.9.1
 290      */
 291     void IgnoreAppBuildSubDirs();
 292
 293     /**
 294         Returns location of Windows shell special folder.
 295
 296         This function is, by definition, MSW-specific. It can be used to access
 297         pre-defined shell directories not covered by the existing methods of
 298         this class, e.g.:
 299         @code
 300         #ifdef __WXMSW__
 301             // get the location of files waiting to be burned on a CD
 302             wxString cdburnArea =
 303                 wxStandardPaths::MSWGetShellDir(CSIDL_CDBURN_AREA);
 304         #endif // __WXMSW__
 305         @endcode
 306
 307         @param csidl
 308
 309         @since 2.9.1
 310      */
 311     static wxString MSWGetShellDir(int csidl);
 312
 313     /**
 314         Lets wxStandardPaths know about the real program installation prefix on a Unix
 315         system. By default, the value returned by GetInstallPrefix() is used.
 316
 317         Although under Linux systems the program prefix may usually be determined
 318         automatically, portable programs should call this function. Usually the prefix
 319         is set during program configuration if using GNU autotools and so it is enough
 320         to pass its value defined in @c config.h to this function.
 321
 322         @note This function is only available under Unix.
 323     */
 324     void SetInstallPrefix(const wxString& prefix);
 325
 326     /**
 327         Controls what application information is used when constructing paths that
 328         should be unique to this program, such as the application data directory, the
 329         plugins directory on Unix, etc.
 330
 331         Valid values for @a info are:
 332             - @c AppInfo_None: don't use neither application nor vendor name in
 333             the paths.
 334             - @c AppInfo_AppName: use the application name in the paths.
 335             - @c AppInfo_VendorName: use the vendor name in the paths, usually
 336             used combined with AppInfo_AppName, i.e. as @code AppInfo_AppName |
 337             AppInfo_VendorName @endcode
 338
 339         By default, only the application name is used.
 340
 341         @since 2.9.0
 342     */
 343     void UseAppInfo(int info);
 344 };
 345