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 platforms (but not limited
 169         to wxGTK mentioned below).
 170
 171         @onlyfor{wxos2,wxgtk}
 172     */
 173     wxString GetInstallPrefix() const;
 174
 175     /**
 176         Return the location for application data files which are host-specific and
 177         can't, or shouldn't, be shared with the other machines.
 178
 179         This is the same as GetDataDir() except under Unix where it returns @c /etc/appinfo.
 180     */
 181     virtual wxString GetLocalDataDir() const;
 182
 183     /**
 184         Return the localized resources directory containing the resource files of the
 185         specified category for the given language.
 186
 187         In general this is just the same as @a lang subdirectory of GetResourcesDir()
 188         (or @c lang.lproj under Mac OS X) but is something quite different for
 189         message catalog category under Unix where it returns the standard
 190         @c prefix/share/locale/lang/LC_MESSAGES directory.
 191
 192         @since 2.7.0
 193     */
 194     virtual wxString
 195     GetLocalizedResourcesDir(const wxString& lang,
 196                              ResourceCat category = ResourceCat_None) const;
 197
 198     /**
 199         Return the directory where the loadable modules (plugins) live.
 200         Example return values:
 201         - Unix: @c prefix/lib/appinfo
 202         - Windows: the directory of the executable file
 203         - Mac: @c appinfo.app/Contents/PlugIns bundle subdirectory
 204
 205         @see wxDynamicLibrary
 206     */
 207     virtual wxString GetPluginsDir() const;
 208
 209     /**
 210         Return the directory where the application resource files are located.
 211
 212         The resources are the auxiliary data files needed for the application to run
 213         and include, for example, image and sound files it might use.
 214
 215         This function is the same as GetDataDir() for all platforms except Mac OS X.
 216         Example return values:
 217         - Unix: @c prefix/share/appinfo
 218         - Windows: the directory where the executable file is located
 219         - Mac: @c appinfo.app/Contents/Resources bundle subdirectory
 220
 221         @since 2.7.0
 222
 223         @see GetLocalizedResourcesDir()
 224     */
 225     virtual wxString GetResourcesDir() const;
 226
 227     /**
 228         Return the directory for storing temporary files.
 229         To create unique temporary files, it is best to use wxFileName::CreateTempFileName
 230         for correct behaviour when multiple processes are attempting to create temporary files.
 231
 232         @since 2.7.2
 233     */
 234     virtual wxString GetTempDir() const;
 235
 236     /**
 237         Return the directory for the user config files:
 238         - Unix: @c ~ (the home directory)
 239         - Windows: @c "C:\Documents and Settings\username\Application Data"
 240         - Mac: @c ~/Library/Preferences
 241
 242         Only use this method if you have a single configuration file to put in this
 243         directory, otherwise GetUserDataDir() is more appropriate as the latter
 244         adds @c appinfo to the path, unlike this function.
 245     */
 246     virtual wxString GetUserConfigDir() const;
 247
 248     /**
 249         Return the directory for the user-dependent application data files:
 250         - Unix: @c ~/.appinfo
 251         - Windows: @c "C:\Documents and Settings\username\Application Data\appinfo"
 252         - Mac: @c "~/Library/Application Support/appinfo"
 253     */
 254     virtual wxString GetUserDataDir() const;
 255
 256     /**
 257         Return the directory for user data files which shouldn't be shared with
 258         the other machines.
 259
 260         This is the same as GetUserDataDir() for all platforms except Windows where it returns
 261         @c "C:\Documents and Settings\username\Local Settings\Application Data\appinfo"
 262     */
 263     virtual wxString GetUserLocalDataDir() const;
 264
 265     /**
 266         MSW-specific function to customize application directory detection.
 267
 268         This class supposes that data, plugins &c files are located under the
 269         program directory which is the directory containing the application
 270         binary itself. But sometimes this binary may be in a subdirectory of
 271         the main program directory, e.g. this happens in at least the following
 272         common cases:
 273          - The program is in "bin" subdirectory of the installation directory.
 274          - The program is in "debug" subdirectory of the directory containing
 275            sources and data files during development
 276
 277         By calling this function you instruct the class to remove the last
 278         component of the path if it matches its argument. Notice that it may be
 279         called more than once, e.g. you can call both IgnoreAppSubDir("bin") and
 280         IgnoreAppSubDir("debug") to take care of both production and development
 281         cases above but that each call will only remove the last path component.
 282         Finally note that the argument can contain wild cards so you can also
 283         call IgnoreAppSubDir("vc*msw*") to ignore all build directories at once
 284         when using wxWidgets-inspired output directories names.
 285
 286         @since 2.9.1
 287
 288         @see IgnoreAppBuildSubDirs()
 289
 290         @param subdirPattern
 291             The subdirectory containing the application binary which should be
 292             ignored when determining the top application directory. The pattern
 293             is case-insensitive and may contain wild card characters @c '?' and
 294             @c '*'.
 295      */
 296     void IgnoreAppSubDir(const wxString& subdirPattern);
 297
 298     /**
 299         MSW-specific function to ignore all common build directories.
 300
 301         This function calls IgnoreAppSubDir() with all common values for build
 302         directory, e.g. @c "debug" and @c "release".
 303
 304         It is called by the class constructor and so the build directories are
 305         always ignored by default. You may use DontIgnoreAppSubDir() to avoid
 306         ignoring them if this is inappropriate for your application.
 307
 308         @since 2.9.1
 309      */
 310     void IgnoreAppBuildSubDirs();
 311
 312     /**
 313         Returns location of Windows shell special folder.
 314
 315         This function is, by definition, MSW-specific. It can be used to access
 316         pre-defined shell directories not covered by the existing methods of
 317         this class, e.g.:
 318         @code
 319         #ifdef __WXMSW__
 320             // get the location of files waiting to be burned on a CD
 321             wxString cdburnArea =
 322                 wxStandardPaths::MSWGetShellDir(CSIDL_CDBURN_AREA);
 323         #endif // __WXMSW__
 324         @endcode
 325
 326         @param csidl
 327
 328         @since 2.9.1
 329      */
 330     static wxString MSWGetShellDir(int csidl);
 331
 332     /**
 333         Lets wxStandardPaths know about the real program installation prefix on a Unix
 334         system. By default, the value returned by GetInstallPrefix() is used.
 335
 336         Although under Linux systems the program prefix may usually be determined
 337         automatically, portable programs should call this function. Usually the prefix
 338         is set during program configuration if using GNU autotools and so it is enough
 339         to pass its value defined in @c config.h to this function.
 340
 341         @note This function is only available under Unix platforms (but not limited
 342         to wxGTK mentioned below).
 343
 344         @onlyfor{wxos2,wxgtk}
 345     */
 346     void SetInstallPrefix(const wxString& prefix);
 347
 348     /**
 349         Controls what application information is used when constructing paths that
 350         should be unique to this program, such as the application data directory, the
 351         plugins directory on Unix, etc.
 352
 353         Valid values for @a info are:
 354             - @c AppInfo_None: don't use neither application nor vendor name in
 355             the paths.
 356             - @c AppInfo_AppName: use the application name in the paths.
 357             - @c AppInfo_VendorName: use the vendor name in the paths, usually
 358             used combined with AppInfo_AppName, i.e. as @code AppInfo_AppName |
 359             AppInfo_VendorName @endcode
 360
 361         By default, only the application name is used.
 362
 363         @since 2.9.0
 364     */
 365     void UseAppInfo(int info);
 366 };
 367