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