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