]> git.saurik.com Git - wxWidgets.git/blame - interface/stdpaths.h
use wx-style header and commets; fix indentation to be 4 spaces; move Doxygen comment...
[wxWidgets.git] / interface / stdpaths.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: stdpaths.h
e54c96f1 3// Purpose: interface of wxStandardPaths
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9/**
10 @class wxStandardPaths
11 @wxheader{stdpaths.h}
7c913512 12
23324ae1
FM
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.
7c913512 15
23324ae1
FM
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.
7c913512 22
23324ae1
FM
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.
7c913512 28
23324ae1
FM
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.
7c913512 32
23324ae1
FM
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.
7c913512 37
23324ae1
FM
38 This class is MT-safe: its methods may be called concurrently from different
39 threads without additional locking.
7c913512 40
23324ae1
FM
41 @library{wxbase}
42 @category{file}
7c913512 43
e54c96f1 44 @see wxFileConfig
23324ae1 45*/
7c913512 46class wxStandardPaths
23324ae1
FM
47{
48public:
49 /**
50 Returns reference to the unique global standard paths object.
51 */
4cc4bfaf 52 static wxStandardPathsBase Get();
23324ae1
FM
53
54 /**
55 Return the directory containing the system config files.
23324ae1 56 Example return values:
23324ae1
FM
57 Unix: @c /etc
58 Windows: @c C:\Documents and Settings\All Users\Application Data
59 Mac: @c /Library/Preferences
3c4f71cc 60
4cc4bfaf 61 @see wxFileConfig
23324ae1 62 */
328f5751 63 wxString GetConfigDir() const;
23324ae1
FM
64
65 /**
66 Return the location of the applications global, i.e. not user-specific,
67 data files.
23324ae1 68 Example return values:
23324ae1
FM
69 Unix: @c @e prefix/share/@e appname
70 Windows: the directory where the executable file is located
71 Mac: @c @e appname.app/Contents/SharedSupport bundle subdirectory
3c4f71cc 72
4cc4bfaf 73 @see GetLocalDataDir()
23324ae1 74 */
328f5751 75 wxString GetDataDir() const;
23324ae1
FM
76
77 /**
78 Return the directory containing the current user's documents.
23324ae1 79 Example return values:
23324ae1
FM
80 Unix: @c ~ (the home directory)
81 Windows: @c C:\Documents and Settings\@e username\Documents
82 Mac: @c ~/Documents
3c4f71cc 83
e54c96f1 84 @wxsince{2.7.0}
23324ae1 85 */
328f5751 86 wxString GetDocumentsDir() const;
23324ae1
FM
87
88 /**
89 Return the directory and the filename for the current executable.
23324ae1 90 Example return values:
23324ae1
FM
91 Unix: @c /usr/local/bin/exename
92 Windows: @c C:\Programs\AppFolder\exename.exe
93 Mac: @c /Programs/exename
94 */
328f5751 95 wxString GetExecutablePath() const;
23324ae1
FM
96
97 /**
98 @b Note: This function is only available under Unix.
23324ae1
FM
99 Return the program installation prefix, e.g. @c /usr, @c /opt or
100 @c /home/zeitlin.
23324ae1
FM
101 If the prefix had been previously by
102 SetInstallPrefix(), returns that
103 value, otherwise tries to determine it automatically (Linux only right
104 now) and finally returns the default @c /usr/local value if it failed.
105 */
328f5751 106 wxString GetInstallPrefix() const;
23324ae1
FM
107
108 /**
109 Return the location for application data files which are host-specific and
110 can't, or shouldn't, be shared with the other machines.
23324ae1
FM
111 This is the same as GetDataDir() except
112 under Unix where it returns @c /etc/@e appname.
113 */
328f5751 114 wxString GetLocalDataDir() const;
23324ae1
FM
115
116 /**
117 Return the localized resources directory containing the resource files of the
118 specified category for the given language.
4cc4bfaf 119 In general this is just the same as @a lang subdirectory of
23324ae1
FM
120 GetResourcesDir() (or
121 @c @e lang.lproj under Mac OS X) but is something quite
122 different for message catalog category under Unix where it returns the standard
123 @c @e prefix/share/locale/@e lang/LC_MESSAGES directory.
3c4f71cc 124
e54c96f1 125 @wxsince{2.7.0}
23324ae1
FM
126 */
127 wxString GetLocalizedResourcesDir(const wxString& lang,
328f5751 128 ResourceCat category = ResourceCat_None) const;
23324ae1
FM
129
130 /**
131 Return the directory where the loadable modules (plugins) live.
23324ae1 132 Example return values:
23324ae1
FM
133 Unix: @c @e prefix/lib/@e appname
134 Windows: the directory of the executable file
135 Mac: @c @e appname.app/Contents/PlugIns bundle subdirectory
3c4f71cc 136
4cc4bfaf 137 @see wxDynamicLibrary
23324ae1 138 */
328f5751 139 wxString GetPluginsDir() const;
23324ae1
FM
140
141 /**
142 Return the directory where the application resource files are located. The
143 resources are the auxiliary data files needed for the application to run and
144 include, for example, image and sound files it might use.
23324ae1
FM
145 This function is the same as GetDataDir() for
146 all platforms except Mac OS X.
23324ae1 147 Example return values:
23324ae1
FM
148 Unix: @c @e prefix/share/@e appname
149 Windows: the directory where the executable file is located
150 Mac: @c @e appname.app/Contents/Resources bundle subdirectory
3c4f71cc 151
e54c96f1 152 @wxsince{2.7.0}
3c4f71cc 153
4cc4bfaf 154 @see GetLocalizedResourcesDir()
23324ae1 155 */
328f5751 156 wxString GetResourcesDir() const;
23324ae1
FM
157
158 /**
159 Return the directory for storing temporary files. To create unique temporary
160 files,
161 it is best to use wxFileName::CreateTempFileName for correct behaviour when
162 multiple processes are attempting to create temporary files.
3c4f71cc 163
e54c96f1 164 @wxsince{2.7.2}
23324ae1 165 */
328f5751 166 wxString GetTempDir() const;
23324ae1
FM
167
168 /**
169 Return the directory for the user config files:
23324ae1
FM
170 Unix: @c ~ (the home directory)
171 Windows: @c C:\Documents and Settings\@e username\Application Data
172 Mac: @c ~/Library/Preferences
23324ae1
FM
173 Only use this method if you have a single configuration file to put in this
174 directory, otherwise GetUserDataDir() is
175 more appropriate.
176 */
328f5751 177 wxString GetUserConfigDir() const;
23324ae1
FM
178
179 /**
180 Return the directory for the user-dependent application data files:
23324ae1
FM
181 Unix: @c ~/.@e appname
182 Windows: @c C:\Documents and Settings\@e username\Application Data\@e
183 appname
184 Mac: @c ~/Library/Application Support/@e appname
185 */
328f5751 186 wxString GetUserDataDir() const;
23324ae1
FM
187
188 /**
189 Return the directory for user data files which shouldn't be shared with
190 the other machines.
23324ae1
FM
191 This is the same as GetUserDataDir() for
192 all platforms except Windows where it returns
193 @c C:\Documents and Settings\@e username\Local Settings\Application Data\@e
194 appname
195 */
328f5751 196 wxString GetUserLocalDataDir() const;
23324ae1
FM
197
198 /**
199 @b Note: This function is only available under Unix.
23324ae1
FM
200 Lets wxStandardPaths know about the real program installation prefix on a Unix
201 system. By default, the value returned by
202 GetInstallPrefix() is used.
23324ae1
FM
203 Although under Linux systems the program prefix may usually be determined
204 automatically, portable programs should call this function. Usually the prefix
205 is set during program configuration if using GNU autotools and so it is enough
206 to pass its value defined in @c config.h to this function.
207 */
208 void SetInstallPrefix(const wxString& prefix);
209
210 /**
211 Controls what application information is used when constructing paths that
212 should be unique to this program, such as the application data directory, the
213 plugins directory on Unix, etc.
4cc4bfaf 214 Valid values for @a info are @c AppInfo_None and either one or
23324ae1
FM
215 combination of @c AppInfo_AppName and @c AppInfo_VendorName. The
216 first one tells this class to not use neither application nor vendor name in
217 the paths.
23324ae1
FM
218 By default, only the application name is used under Unix systems but both
219 application and vendor names are used under Windows and Mac.
220 */
221 void UseAppInfo(int info);
222};
e54c96f1 223