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