interface/stdpaths.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        stdpaths.h
   3 // Purpose:     documentation for wxStandardPaths class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxStandardPaths
  11     @wxheader{stdpaths.h}
  12
  13     wxStandardPaths returns the standard locations in the file system and should be
  14     used by applications to find their data files in a portable way.
  15
  16     In the description of the methods below, the example return values are given
  17     for the Unix, Windows and Mac OS X systems, however please note that these are
  18     just the examples and the actual values may differ. For example, under Windows:
  19     the system administrator may change the standard directories locations, i.e.
  20     the Windows directory may be named @c W:\Win2003 instead of
  21     the default @c C:\Windows.
  22
  23     The strings @c @e appname and @c @e username should be
  24     replaced with the value returned by wxApp::GetAppName
  25     and the name of the currently logged in user, respectively. The string
  26     @c @e prefix is only used under Unix and is @c /usr/local by
  27     default but may be changed using wxStandardPaths::SetInstallPrefix.
  28
  29     The directories returned by the methods of this class may or may not exist. If
  30     they don't exist, it's up to the caller to create them, wxStandardPaths doesn't
  31     do it.
  32
  33     Finally note that these functions only work with standardly packaged
  34     applications. I.e. under Unix you should follow the standard installation
  35     conventions and under Mac you should create your application bundle according
  36     to the Apple guidelines. Again, this class doesn't help you to do it.
  37
  38     This class is MT-safe: its methods may be called concurrently from different
  39     threads without additional locking.
  40
  41     @library{wxbase}
  42     @category{file}
  43
  44     @seealso
  45     wxFileConfig
  46 */
  47 class wxStandardPaths
  48 {
  49 public:
  50     /**
  51         Returns reference to the unique global standard paths object.
  52     */
  53 #define static wxStandardPathsBase Get()     /* implementation is private */
  54
  55     /**
  56         Return the directory containing the system config files.
  57
  58         Example return values:
  59
  60              Unix: @c /etc
  61              Windows: @c C:\Documents and Settings\All Users\Application Data
  62              Mac: @c /Library/Preferences
  63
  64         @sa wxFileConfig
  65     */
  66     wxString GetConfigDir();
  67
  68     /**
  69         Return the location of the applications global, i.e. not user-specific,
  70         data files.
  71
  72         Example return values:
  73
  74              Unix: @c @e prefix/share/@e appname
  75              Windows: the directory where the executable file is located
  76              Mac: @c @e appname.app/Contents/SharedSupport bundle subdirectory
  77
  78         @sa GetLocalDataDir()
  79     */
  80     wxString GetDataDir();
  81
  82     /**
  83         Return the directory containing the current user's documents.
  84
  85         Example return values:
  86
  87              Unix: @c ~ (the home directory)
  88              Windows: @c C:\Documents and Settings\@e username\Documents
  89              Mac: @c ~/Documents
  90
  91         This function is new since wxWidgets version 2.7.0
  92     */
  93     wxString GetDocumentsDir();
  94
  95     /**
  96         Return the directory and the filename for the current executable.
  97
  98         Example return values:
  99
 100              Unix: @c /usr/local/bin/exename
 101              Windows: @c C:\Programs\AppFolder\exename.exe
 102              Mac: @c /Programs/exename
 103     */
 104     wxString GetExecutablePath();
 105
 106     /**
 107         @b Note: This function is only available under Unix.
 108
 109         Return the program installation prefix, e.g. @c /usr, @c /opt or
 110         @c /home/zeitlin.
 111
 112         If the prefix had been previously by
 113         SetInstallPrefix(), returns that
 114         value, otherwise tries to determine it automatically (Linux only right
 115         now) and finally returns the default @c /usr/local value if it failed.
 116     */
 117     wxString GetInstallPrefix();
 118
 119     /**
 120         Return the location for application data files which are host-specific and
 121         can't, or shouldn't, be shared with the other machines.
 122
 123         This is the same as GetDataDir() except
 124         under Unix where it returns @c /etc/@e appname.
 125     */
 126     wxString GetLocalDataDir();
 127
 128     /**
 129         Return the localized resources directory containing the resource files of the
 130         specified category for the given language.
 131
 132         In general this is just the same as @e lang subdirectory of
 133         GetResourcesDir() (or
 134         @c @e lang.lproj under Mac OS X) but is something quite
 135         different for message catalog category under Unix where it returns the standard
 136         @c @e prefix/share/locale/@e lang/LC_MESSAGES directory.
 137
 138         This function is new since wxWidgets version 2.7.0
 139     */
 140     wxString GetLocalizedResourcesDir(const wxString& lang,
 141                                       ResourceCat category = ResourceCat_None);
 142
 143     /**
 144         Return the directory where the loadable modules (plugins) live.
 145
 146         Example return values:
 147
 148              Unix: @c @e prefix/lib/@e appname
 149              Windows: the directory of the executable file
 150              Mac: @c @e appname.app/Contents/PlugIns bundle subdirectory
 151
 152         @sa wxDynamicLibrary
 153     */
 154     wxString GetPluginsDir();
 155
 156     /**
 157         Return the directory where the application resource files are located. The
 158         resources are the auxiliary data files needed for the application to run and
 159         include, for example, image and sound files it might use.
 160
 161         This function is the same as GetDataDir() for
 162         all platforms except Mac OS X.
 163
 164         Example return values:
 165
 166              Unix: @c @e prefix/share/@e appname
 167              Windows: the directory where the executable file is located
 168              Mac: @c @e appname.app/Contents/Resources bundle subdirectory
 169
 170         This function is new since wxWidgets version 2.7.0
 171
 172         @sa GetLocalizedResourcesDir()
 173     */
 174     wxString GetResourcesDir();
 175
 176     /**
 177         Return the directory for storing temporary files. To create unique temporary
 178         files,
 179         it is best to use wxFileName::CreateTempFileName for correct behaviour when
 180         multiple processes are attempting to create temporary files.
 181
 182         This function is new since wxWidgets version 2.7.2
 183     */
 184     wxString GetTempDir();
 185
 186     /**
 187         Return the directory for the user config files:
 188
 189              Unix: @c ~ (the home directory)
 190              Windows: @c C:\Documents and Settings\@e username\Application Data
 191              Mac: @c ~/Library/Preferences
 192
 193         Only use this method if you have a single configuration file to put in this
 194         directory, otherwise GetUserDataDir() is
 195         more appropriate.
 196     */
 197     wxString GetUserConfigDir();
 198
 199     /**
 200         Return the directory for the user-dependent application data files:
 201
 202              Unix: @c ~/.@e appname
 203              Windows: @c C:\Documents and Settings\@e username\Application Data\@e
 204         appname
 205              Mac: @c ~/Library/Application Support/@e appname
 206     */
 207     wxString GetUserDataDir();
 208
 209     /**
 210         Return the directory for user data files which shouldn't be shared with
 211         the other machines.
 212
 213         This is the same as GetUserDataDir() for
 214         all platforms except Windows where it returns
 215         @c C:\Documents and Settings\@e username\Local Settings\Application Data\@e
 216         appname
 217     */
 218     wxString GetUserLocalDataDir();
 219
 220     /**
 221         @b Note: This function is only available under Unix.
 222
 223         Lets wxStandardPaths know about the real program installation prefix on a Unix
 224         system. By default, the value returned by
 225         GetInstallPrefix() is used.
 226
 227         Although under Linux systems the program prefix may usually be determined
 228         automatically, portable programs should call this function. Usually the prefix
 229         is set during program configuration if using GNU autotools and so it is enough
 230         to pass its value defined in @c config.h to this function.
 231     */
 232     void SetInstallPrefix(const wxString& prefix);
 233
 234     /**
 235         Controls what application information is used when constructing paths that
 236         should be unique to this program, such as the application data directory, the
 237         plugins directory on Unix, etc.
 238
 239         Valid values for @e info are @c AppInfo_None and either one or
 240         combination of @c AppInfo_AppName and @c AppInfo_VendorName. The
 241         first one tells this class to not use neither application nor vendor name in
 242         the paths.
 243
 244         By default, only the application name is used under Unix systems but both
 245         application and vendor names are used under Windows and Mac.
 246     */
 247     void UseAppInfo(int info);
 248 };