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.
 241     */
 242     virtual wxString GetUserConfigDir() const;
 243
 244     /**
 245         Return the directory for the user-dependent application data files:
 246         - Unix: @c ~/.appinfo
 247         - Windows: @c "C:\Documents and Settings\username\Application Data\appinfo"
 248         - Mac: @c "~/Library/Application Support/appinfo"
 249     */
 250     virtual wxString GetUserDataDir() const;
 251
 252     /**
 253         Return the directory for user data files which shouldn't be shared with
 254         the other machines.
 255
 256         This is the same as GetUserDataDir() for all platforms except Windows where it returns
 257         @c "C:\Documents and Settings\username\Local Settings\Application Data\appinfo"
 258     */
 259     virtual wxString GetUserLocalDataDir() const;
 260
 261     /**
 262         MSW-specific function to customize application directory detection.
 263
 264         This class supposes that data, plugins &c files are located under the
 265         program directory which is the directory containing the application
 266         binary itself. But sometimes this binary may be in a subdirectory of
 267         the main program directory, e.g. this happens in at least the following
 268         common cases:
 269          - The program is in "bin" subdirectory of the installation directory.
 270          - The program is in "debug" subdirectory of the directory containing
 271            sources and data files during development
 272
 273         By calling this function you instruct the class to remove the last
 274         component of the path if it matches its argument. Notice that it may be
 275         called more than once, e.g. you can call both IgnoreAppSubDir("bin") and
 276         IgnoreAppSubDir("debug") to take care of both production and development
 277         cases above but that each call will only remove the last path component.
 278         Finally note that the argument can contain wild cards so you can also
 279         call IgnoreAppSubDir("vc*msw*") to ignore all build directories at once
 280         when using wxWidgets-inspired output directories names.
 281
 282         @since 2.9.1
 283
 284         @see IgnoreAppBuildSubDirs()
 285
 286         @param subdirPattern
 287             The subdirectory containing the application binary which should be
 288             ignored when determining the top application directory. The pattern
 289             is case-insensitive and may contain wild card characters @c '?' and
 290             @c '*'.
 291      */
 292     void IgnoreAppSubDir(const wxString& subdirPattern);
 293
 294     /**
 295         MSW-specific function to ignore all common build directories.
 296
 297         This function calls IgnoreAppSubDir() with all common values for build
 298         directory, e.g. @c "debug" and @c "release".
 299
 300         It is called by the class constructor and so the build directories are
 301         always ignored by default. You may use DontIgnoreAppSubDir() to avoid
 302         ignoring them if this is inappropriate for your application.
 303
 304         @since 2.9.1
 305      */
 306     void IgnoreAppBuildSubDirs();
 307
 308     /**
 309         Returns location of Windows shell special folder.
 310
 311         This function is, by definition, MSW-specific. It can be used to access
 312         pre-defined shell directories not covered by the existing methods of
 313         this class, e.g.:
 314         @code
 315         #ifdef __WXMSW__
 316             // get the location of files waiting to be burned on a CD
 317             wxString cdburnArea =
 318                 wxStandardPaths::MSWGetShellDir(CSIDL_CDBURN_AREA);
 319         #endif // __WXMSW__
 320         @endcode
 321
 322         @param csidl
 323
 324         @since 2.9.1
 325      */
 326     static wxString MSWGetShellDir(int csidl);
 327
 328     /**
 329         Lets wxStandardPaths know about the real program installation prefix on a Unix
 330         system. By default, the value returned by GetInstallPrefix() is used.
 331
 332         Although under Linux systems the program prefix may usually be determined
 333         automatically, portable programs should call this function. Usually the prefix
 334         is set during program configuration if using GNU autotools and so it is enough
 335         to pass its value defined in @c config.h to this function.
 336
 337         @note This function is only available under Unix.
 338     */
 339     void SetInstallPrefix(const wxString& prefix);
 340
 341     /**
 342         Controls what application information is used when constructing paths that
 343         should be unique to this program, such as the application data directory, the
 344         plugins directory on Unix, etc.
 345
 346         Valid values for @a info are:
 347             - @c AppInfo_None: don't use neither application nor vendor name in
 348             the paths.
 349             - @c AppInfo_AppName: use the application name in the paths.
 350             - @c AppInfo_VendorName: use the vendor name in the paths, usually
 351             used combined with AppInfo_AppName, i.e. as @code AppInfo_AppName |
 352             AppInfo_VendorName @endcode
 353
 354         By default, only the application name is used.
 355
 356         @since 2.9.0
 357     */
 358     void UseAppInfo(int info);
 359 };
 360