]>
Commit | Line | Data |
---|---|---|
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 |