interface/wx/stdpaths.h

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