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