Warning: That file was not part of the compilation database. It may have many parsing errors.
1 | /* |
---|---|
2 | This file is part of the KDE libraries |
3 | Copyright (C) 1999 Sirtaj Singh Kang <taj@kde.org> |
4 | Copyright (C) 1999 Stephan Kulow <coolo@kde.org> |
5 | Copyright (C) 1999 Waldo Bastian <bastian@kde.org> |
6 | |
7 | This library is free software; you can redistribute it and/or |
8 | modify it under the terms of the GNU Library General Public |
9 | License as published by the Free Software Foundation; either |
10 | version 2 of the License, or (at your option) any later version. |
11 | |
12 | This library is distributed in the hope that it will be useful, |
13 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
14 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
15 | Library General Public License for more details. |
16 | |
17 | You should have received a copy of the GNU Library General Public License |
18 | along with this library; see the file COPYING.LIB. If not, write to |
19 | the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, |
20 | Boston, MA 02110-1301, USA. |
21 | */ |
22 | |
23 | #ifndef KSTANDARDDIRS_H |
24 | #define KSTANDARDDIRS_H |
25 | |
26 | #include <QtCore/QStringList> |
27 | #include <kglobal.h> |
28 | #include <QtCore/QMap> |
29 | |
30 | class KConfig; |
31 | |
32 | /** |
33 | * @short Site-independent access to standard KDE directories. |
34 | * @author Stephan Kulow <coolo@kde.org> and Sirtaj Singh Kang <taj@kde.org> |
35 | * |
36 | * This is one of the most central classes in kdelibs: It knows where KDE-related files |
37 | * reside on the user's hard disk. It's meant to be the only one that knows -- |
38 | * so applications and the end user don't have to. |
39 | * |
40 | * Applications should always refer to a file with a resource type. |
41 | * The application should leave it up to e.g. |
42 | * KStandardDirs::findResource("apps", "Home.desktop") |
43 | * to return the desired path <tt>/opt/kde/share/applnk/Home.desktop</tt> |
44 | * or ::locate("data", "kgame/background.jpg") to return |
45 | * <tt>/opt/kde/share/apps/kgame/background.jpg</tt> |
46 | * |
47 | * There are several toplevel prefixes under which files can be located. |
48 | * One of them is the kdelibs install location, one is the application |
49 | * install location, and one is <tt>$KDEHOME</tt>. |
50 | * Under these toplevel prefixes there are several well-defined suffixes |
51 | * where specific resource types can be found. |
52 | * For example, for the resource type @c "html" the suffixes could be |
53 | * @c share/doc/HTML and @c share/doc/kde/HTML. |
54 | * The search algorithm tries to locate the file under each prefix-suffix |
55 | * combination. |
56 | * |
57 | * It is also possible to register |
58 | * absolute paths that KStandardDirs looks up after not finding anything |
59 | * in the former steps. They can be useful if the user wants to provide |
60 | * specific directories that aren't in his <tt>$KDEHOME</tt> directory, for |
61 | * example for icons. |
62 | * |
63 | * <b>Standard resources that kdelibs allocates are:</b> |
64 | * |
65 | * @li @c apps - Applications menu (.desktop files). |
66 | * @li @c autostart - Autostart directories (both XDG and kde-specific) |
67 | * @li @c cache - Cached information (e.g. favicons, web-pages) |
68 | * @li @c cgi - CGIs to run from kdehelp. |
69 | * @li @c config - Configuration files. |
70 | * @li @c data - Where applications store data. |
71 | * @li @c emoticons - Emoticons themes |
72 | * @li @c exe - Executables in $prefix/bin. findExe() for a function that takes $PATH into account. |
73 | * @li @c html - HTML documentation. |
74 | * @li @c icon - Icons, see KIconLoader. |
75 | * @li @c kcfg - KConfigXT config files. |
76 | * @li @c lib - Libraries. |
77 | * @li @c locale - Translation files for KLocale. |
78 | * @li @c mime - Mime types defined by KDE-specific .desktop files. |
79 | * @li @c module - Module (dynamically loaded library). |
80 | * @li @c qtplugins - Qt plugins (dynamically loaded objects for Qt) |
81 | * @li @c services - Services. |
82 | * @li @c servicetypes - Service types. |
83 | * @li @c sound - Application sounds. |
84 | * @li @c templates - Templates for the "Create new file" functionality. |
85 | * @li @c wallpaper - Wallpapers. |
86 | * @li @c tmp - Temporary files (specific for both current host and current user) |
87 | * @li @c socket - UNIX Sockets (specific for both current host and current user) |
88 | * @li @c xdgconf-menu - Freedesktop.org standard location for menu layout (.menu) files. |
89 | * @li @c xdgdata-apps - Freedesktop.org standard location for application desktop files. |
90 | * @li @c xdgdata-dirs - Freedesktop.org standard location for menu descriptions (.directory files). |
91 | * @li @c xdgdata-mime - Freedesktop.org standard location for MIME type definitions. |
92 | * @li @c xdgdata-icon - Freedesktop.org standard location for icons. |
93 | * @li @c xdgdata-pixmap - Gnome-compatibility location for pixmaps. |
94 | * |
95 | * A type that is added by the class KApplication if you use it, is |
96 | * @c appdata. This one makes the use of the type data a bit easier as it |
97 | * appends the name of the application. |
98 | * So while you had to ::locate("data", "appname/filename") so you can |
99 | * also write ::locate("appdata", "filename") if your KApplication instance |
100 | * is called @c "appname" (as set via KApplication's constructor or KAboutData, if |
101 | * you use the global KStandardDirs object KGlobal::dirs()). |
102 | * Please note though that you cannot use the @c "appdata" |
103 | * type if you intend to use it in an applet for Kicker because 'appname' would |
104 | * be @c "Kicker" instead of the applet's name. Therefore, for applets, you've got |
105 | * to work around this by using ::locate("data", "appletname/filename"). |
106 | * |
107 | * <b>KStandardDirs supports the following environment variables:</b> |
108 | * |
109 | * @li @c KDEDIRS - This may set an additional number of directory prefixes to |
110 | * search for resources. The directories should be separated |
111 | * by <tt>':'</tt>. The directories are searched in the order they are |
112 | * specified. |
113 | * @li @c KDEHOME - The directory where changes are saved to. This directory is |
114 | * used to search for resources first. If @c KDEHOME is not |
115 | * specified it defaults to @c "$HOME/.kde" |
116 | * @li @c KDEROOTHOME - Like KDEHOME, but used for the root user. |
117 | * If @c KDEROOTHOME is not set it defaults to the <tt>.kde</tt> directory in the |
118 | * home directory of root, usually @c "/root/.kde". |
119 | * Note that the setting of @c $HOME is ignored in this case. |
120 | * |
121 | * @see KGlobalSettings |
122 | * |
123 | * |
124 | * On The Usage Of 'locate' and 'locateLocal' |
125 | * |
126 | * Typical KDE applications use resource files in one out of |
127 | * three ways: |
128 | * |
129 | * 1) A resource file is read but is never written. A system |
130 | * default is supplied but the user can override this |
131 | * default in his local .kde directory: |
132 | * |
133 | * @code |
134 | * // Code example |
135 | * myFile = KStandardDirs::locate("appdata", "groups.lst"); |
136 | * myData = myReadGroups(myFile); // myFile may be null |
137 | * @endcode |
138 | * |
139 | * 2) A resource file is read and written. If the user has no |
140 | * local version of the file the system default is used. |
141 | * The resource file is always written to the users local |
142 | * .kde directory. |
143 | * |
144 | * @code |
145 | * // Code example |
146 | * myFile = KStandardDirs::locate("appdata", "groups.lst") |
147 | * myData = myReadGroups(myFile); |
148 | * ... |
149 | * doSomething(myData); |
150 | * ... |
151 | * myFile = KStandardDirs::locateLocal("appdata", "groups.lst"); |
152 | * myWriteGroups(myFile, myData); |
153 | * @endcode |
154 | * |
155 | * 3) A resource file is read and written. No system default |
156 | * is used if the user has no local version of the file. |
157 | * The resource file is always written to the users local |
158 | * .kde directory. |
159 | * |
160 | * @code |
161 | * // Code example |
162 | * myFile = KStandardDirs::locateLocal("appdata", "groups.lst"); |
163 | * myData = myReadGroups(myFile); |
164 | * ... |
165 | * doSomething(myData); |
166 | * ... |
167 | * myFile = KStandardDirs::locateLocal("appdata", "groups.lst"); |
168 | * myWriteGroups(myFile, myData); |
169 | * @endcode |
170 | **/ |
171 | class KDECORE_EXPORT KStandardDirs |
172 | { |
173 | public: |
174 | /** |
175 | * KStandardDirs' constructor. It just initializes the caches. |
176 | * Note that you should normally not call this, but use KGlobal::dirs() |
177 | * instead, in order to reuse the same KStandardDirs object as much as possible. |
178 | * |
179 | * Creating other KStandardDirs instances can be useful in other threads. |
180 | * |
181 | * Thread safety note: using a shared KStandardDirs instance (such as KGlobal::dirs()) |
182 | * in multiple threads is thread-safe if you only call the readonly "lookup" methods |
183 | * (findExe, resourceDirs, findDirs, findResourceDir, findAllResources, saveLocation, |
184 | * relativeLocation). The methods that modify the object (all those starting with "add", |
185 | * basically all non-const methods) are obviously not thread-safe; set things up |
186 | * before creating threads. |
187 | */ |
188 | KStandardDirs(); |
189 | |
190 | enum SearchOption { NoSearchOptions = 0, |
191 | Recursive = 1, |
192 | NoDuplicates = 2, |
193 | IgnoreExecBit = 4 }; |
194 | Q_DECLARE_FLAGS( SearchOptions, SearchOption ) |
195 | |
196 | /** |
197 | * KStandardDirs' destructor. |
198 | */ |
199 | virtual ~KStandardDirs(); |
200 | |
201 | /** |
202 | * Adds another search dir to front of the @p fsstnd list. |
203 | * |
204 | * @li When compiling kdelibs, the prefix is added to this. |
205 | * @li @c KDEDIRS is taken into account |
206 | * @li Additional dirs may be loaded from kdeglobals. |
207 | * |
208 | * @param dir The directory to append relative paths to. |
209 | */ |
210 | void addPrefix( const QString& dir ); |
211 | |
212 | /** |
213 | * Adds another search dir to front of the @c XDG_CONFIG_XXX list |
214 | * of prefixes. |
215 | * This prefix is only used for resources that start with @c "xdgconf-" |
216 | * |
217 | * @param dir The directory to append relative paths to. |
218 | */ |
219 | void addXdgConfigPrefix( const QString& dir ); |
220 | |
221 | /** |
222 | * Adds another search dir to front of the @c XDG_DATA_XXX list |
223 | * of prefixes. |
224 | * This prefix is only used for resources that start with @c "xdgdata-" |
225 | * |
226 | * @param dir The directory to append relative paths to. |
227 | */ |
228 | void addXdgDataPrefix( const QString& dir ); |
229 | |
230 | /** |
231 | * Adds suffixes for types. |
232 | * |
233 | * You may add as many as you need, but it is advised that there |
234 | * is exactly one to make writing definite. |
235 | * All basic types are added by addKDEDefaults(), |
236 | * but for those you can add more relative paths as well. |
237 | * |
238 | * The later a suffix is added, the higher its priority. Note, that the |
239 | * suffix should end with / but doesn't have to start with one (as prefixes |
240 | * should end with one). So adding a suffix for app_pics would look |
241 | * like KGlobal::dirs()->addResourceType("app_pics", "data" ,"app/pics"); |
242 | * |
243 | * @param type Specifies a short descriptive string to access |
244 | * files of this type. |
245 | * @param relativename Specifies a directory relative to the root |
246 | * of the KFSSTND. |
247 | * @param priority if true, the directory is added before any other, |
248 | * otherwise after |
249 | * @return true if successful, false otherwise. |
250 | * |
251 | * @deprecated, use addResourceType(type, 0, relativename, priority) |
252 | */ |
253 | #ifndef KDE_NO_DEPRECATED |
254 | KDE_DEPRECATED bool addResourceType( const char *type, |
255 | const QString& relativename, bool priority = true ); |
256 | #endif |
257 | |
258 | /** |
259 | * Adds suffixes for types. |
260 | * |
261 | * You may add as many as you need, but it is advised that there |
262 | * is exactly one to make writing definite. |
263 | * All basic types are added by addKDEDefaults(), |
264 | * but for those you can add more relative paths as well. |
265 | * |
266 | * The later a suffix is added, the higher its priority. Note, that the |
267 | * suffix should end with / but doesn't have to start with one (as prefixes |
268 | * should end with one). So adding a suffix for app_pics would look |
269 | * like KGlobal::dirs()->addResourceType("app_pics", "data", "app/pics"); |
270 | * |
271 | * @param type Specifies a short descriptive string to access |
272 | * files of this type. |
273 | * @param basetype Specifies an already known type, or 0 if none |
274 | * @param relativename Specifies a directory relative to the basetype |
275 | * @param priority if true, the directory is added before any other, |
276 | * otherwise after |
277 | * @return true if successful, false otherwise. |
278 | */ |
279 | bool addResourceType( const char *type, const char *basetype, |
280 | const QString& relativename, bool priority = true ); |
281 | |
282 | /// @internal - just to avoid unwanted overload |
283 | bool addResourceType( const char *type, const char *basetype, |
284 | const char* relativename, bool priority = true ) |
285 | { |
286 | return addResourceType(type, basetype, QLatin1String(relativename), priority); |
287 | } |
288 | |
289 | /** |
290 | * Adds absolute path at the beginning of the search path for |
291 | * particular types (for example in case of icons where |
292 | * the user specifies extra paths). |
293 | * |
294 | * You shouldn't need this |
295 | * function in 99% of all cases besides adding user-given |
296 | * paths. |
297 | * |
298 | * @param type Specifies a short descriptive string to access files |
299 | * of this type. |
300 | * @param absdir Points to directory where to look for this specific |
301 | * type. Non-existent directories may be saved but pruned. |
302 | * @param priority if true, the directory is added before any other, |
303 | * otherwise after |
304 | * @return true if successful, false otherwise. |
305 | */ |
306 | bool addResourceDir( const char *type, |
307 | const QString& absdir, bool priority = true ); |
308 | |
309 | /** |
310 | * Tries to find a resource in the following order: |
311 | * @li All PREFIX/\<relativename> paths (most recent first). |
312 | * @li All absolute paths (most recent first). |
313 | * |
314 | * The filename should be a filename relative to the base dir |
315 | * for resources. So is a way to get the path to libkdecore.la |
316 | * to findResource("lib", "libkdecore.la"). KStandardDirs will |
317 | * then look into the subdir lib of all elements of all prefixes |
318 | * ($KDEDIRS) for a file libkdecore.la and return the path to |
319 | * the first one it finds (e.g. /opt/kde/lib/libkdecore.la). |
320 | * You can use the program kde4-config to list all resource types: |
321 | * @code |
322 | * $ kde4-config --types |
323 | * @endcode |
324 | * |
325 | * Example: |
326 | * @code |
327 | * QString iconfilename=KGlobal::dirs()->findResource("icon",QString("oxygen/22x22/apps/ktip.png")); |
328 | * @endcode |
329 | * |
330 | * @param type The type of the wanted resource |
331 | * @param filename A relative filename of the resource. |
332 | * |
333 | * @return A full path to the filename specified in the second |
334 | * argument, or QString() if not found. |
335 | */ |
336 | QString findResource( const char *type, |
337 | const QString& filename ) const; |
338 | |
339 | /** |
340 | * Checks whether a resource is restricted as part of the KIOSK |
341 | * framework. When a resource is restricted it means that user- |
342 | * specific files in the resource are ignored. |
343 | * |
344 | * E.g. by restricting the @c "wallpaper" resource, only system-wide |
345 | * installed wallpapers will be found by this class. Wallpapers |
346 | * installed under the @c $KDEHOME directory will be ignored. |
347 | * |
348 | * @param type The type of the resource to check |
349 | * @param relPath A relative path in the resource. |
350 | * |
351 | * @return True if the resource is restricted. |
352 | */ |
353 | bool isRestrictedResource( const char *type, |
354 | const QString& relPath=QString() ) const; |
355 | |
356 | /** |
357 | * Returns a number that identifies this version of the resource. |
358 | * When a change is made to the resource this number will change. |
359 | * |
360 | * @param type The type of the wanted resource |
361 | * @param filename A relative filename of the resource. |
362 | * @param options If the flags includes Recursive, |
363 | * all resources are taken into account |
364 | * otherwise only the one returned by findResource(). |
365 | * |
366 | * @return A number identifying the current version of the |
367 | * resource. |
368 | */ |
369 | quint32 calcResourceHash( const char *type, |
370 | const QString& filename, |
371 | SearchOptions options = NoSearchOptions) const; |
372 | |
373 | /** |
374 | * Tries to find all directories whose names consist of the |
375 | * specified type and a relative path. So |
376 | * findDirs("apps", "Settings") would return |
377 | * @li /home/joe/.kde/share/applnk/Settings/ |
378 | * @li /opt/kde/share/applnk/Settings/ |
379 | * |
380 | * (from the most local to the most global) |
381 | * |
382 | * Note that it appends @c / to the end of the directories, |
383 | * so you can use this right away as directory names. |
384 | * |
385 | * @param type The type of the base directory. |
386 | * @param reldir Relative directory. |
387 | * |
388 | * @return A list of matching directories, or an empty |
389 | * list if the resource specified is not found. |
390 | */ |
391 | QStringList findDirs( const char *type, |
392 | const QString& reldir ) const; |
393 | |
394 | /** |
395 | * Tries to find the directory the file is in. |
396 | * It works the same as findResource(), but it doesn't |
397 | * return the filename but the name of the directory. |
398 | * |
399 | * This way the application can access a couple of files |
400 | * that have been installed into the same directory without |
401 | * having to look for each file. |
402 | * |
403 | * findResourceDir("lib", "libkdecore.la") would return the |
404 | * path of the subdir libkdecore.la is found first in |
405 | * (e.g. /opt/kde/lib/) |
406 | * |
407 | * @param type The type of the wanted resource |
408 | * @param filename A relative filename of the resource. |
409 | * @return The directory where the file specified in the second |
410 | * argument is located, or QString() if the type |
411 | * of resource specified is unknown or the resource |
412 | * cannot be found. |
413 | */ |
414 | QString findResourceDir( const char *type, |
415 | const QString& filename) const; |
416 | |
417 | |
418 | /** |
419 | * Tries to find all resources with the specified type. |
420 | * |
421 | * The function will look into all specified directories |
422 | * and return all filenames in these directories. |
423 | * |
424 | * The "most local" files are returned before the "more global" files. |
425 | * |
426 | * @param type The type of resource to locate directories for. |
427 | * @param filter Only accept filenames that fit to filter. The filter |
428 | * may consist of an optional directory and a QRegExp |
429 | * wildcard expression. E.g. <tt>"images\*.jpg"</tt>. |
430 | * Use QString() if you do not want a filter. |
431 | * @param options if the flags passed include Recursive, subdirectories |
432 | * will also be search; if NoDuplicates is passed then only entries with |
433 | * unique filenames will be returned eliminating duplicates. |
434 | * |
435 | * @return List of all the files whose filename matches the |
436 | * specified filter. |
437 | */ |
438 | QStringList findAllResources( const char *type, |
439 | const QString& filter = QString(), |
440 | SearchOptions options = NoSearchOptions ) const; |
441 | |
442 | /** |
443 | * Tries to find all resources with the specified type. |
444 | * |
445 | * The function will look into all specified directories |
446 | * and return all filenames (full and relative paths) in |
447 | * these directories. |
448 | * |
449 | * The "most local" files are returned before the "more global" files. |
450 | * |
451 | * @param type The type of resource to locate directories for. Can be icon, |
452 | * lib, pixmap, .... To get a complete list, call |
453 | * @code |
454 | * kde4-config --types |
455 | * @endcode |
456 | * @param filter Only accept filenames that fit to filter. The filter |
457 | * may consist of an optional directory and a QRegExp |
458 | * wildcard expression. E.g. <tt>"images\*.jpg"</tt>. |
459 | * Use QString() if you do not want a filter. |
460 | * @param options if the flags passed include Recursive, subdirectories |
461 | * will also be search; if NoDuplicates is passed then only entries with |
462 | * unique filenames will be returned eliminating duplicates. |
463 | * |
464 | * @param relPaths The list to store the relative paths into |
465 | * These can be used later to ::locate() the file |
466 | * |
467 | * @return List of all the files whose filename matches the |
468 | * specified filter. |
469 | */ |
470 | QStringList findAllResources( const char *type, |
471 | const QString& filter, |
472 | SearchOptions options, |
473 | QStringList &relPaths) const; |
474 | |
475 | /** |
476 | * Returns a QStringList list of pathnames in the system path. |
477 | * |
478 | * @param pstr The path which will be searched. If this is |
479 | * null (default), the @c $PATH environment variable will |
480 | * be searched. |
481 | * |
482 | * @return a QStringList list of pathnames in the system path. |
483 | */ |
484 | static QStringList systemPaths( const QString& pstr=QString() ); |
485 | |
486 | /** |
487 | * Finds the executable in the system path. |
488 | * |
489 | * A valid executable must |
490 | * be a file and have its executable bit set. |
491 | * |
492 | * @param appname The name of the executable file for which to search. |
493 | * if this contains a path separator, it will be resolved |
494 | * according to the current working directory |
495 | * (shell-like behaviour). |
496 | * @param pathstr The path which will be searched. If this is |
497 | * null (default), the @c $PATH environment variable will |
498 | * be searched. |
499 | * @param options if the flags passed include IgnoreExecBit the path returned |
500 | * may not have the executable bit set. |
501 | * |
502 | * @return The path of the executable. If it was not found, |
503 | * it will return QString(). |
504 | * @see findAllExe() |
505 | */ |
506 | static QString findExe( const QString& appname, |
507 | const QString& pathstr = QString(), |
508 | SearchOptions options = NoSearchOptions ); |
509 | |
510 | /** |
511 | * Finds all occurrences of an executable in the system path. |
512 | * |
513 | * @param list will be filled with the pathnames of all the |
514 | * executables found. Will be empty if the executable |
515 | * was not found. |
516 | * @param appname the name of the executable for which to |
517 | * search. |
518 | * @param pathstr the path list which will be searched. If this |
519 | * is 0 (default), the @c $PATH environment variable will |
520 | * be searched. |
521 | * @param options if the flags passed include IgnoreExecBit the path returned |
522 | * may not have the executable bit set. |
523 | * |
524 | * @return The number of executables found, 0 if none were found. |
525 | * |
526 | * @see findExe() |
527 | */ |
528 | static int findAllExe( QStringList& list, const QString& appname, |
529 | const QString& pathstr=QString(), |
530 | SearchOptions options = NoSearchOptions ); |
531 | |
532 | /** |
533 | * Reads customized entries out of the given config object and add |
534 | * them via addResourceDirs(). |
535 | * |
536 | * @param config The object the entries are read from. This should |
537 | * contain global config files |
538 | * @return @c true if new config paths have been added |
539 | * from @p config. |
540 | **/ |
541 | bool addCustomized(KConfig *config); |
542 | |
543 | /** |
544 | * This function is used internally by almost all other function as |
545 | * it serves and fills the directories cache. |
546 | * |
547 | * @param type The type of resource |
548 | * @return The list of possible directories for the specified @p type. |
549 | * The function updates the cache if possible. If the resource |
550 | * type specified is unknown, it will return an empty list. |
551 | * Note, that the directories are assured to exist beside the save |
552 | * location, which may not exist, but is returned anyway. |
553 | */ |
554 | QStringList resourceDirs(const char *type) const; |
555 | |
556 | /** |
557 | * This function will return a list of all the types that KStandardDirs |
558 | * supports. |
559 | * |
560 | * @return All types that KDE supports |
561 | */ |
562 | QStringList allTypes() const; |
563 | |
564 | /** |
565 | * Finds a location to save files into for the given type |
566 | * in the user's home directory. |
567 | * |
568 | * @param type The type of location to return. |
569 | * @param suffix A subdirectory name. |
570 | * Makes it easier for you to create subdirectories. |
571 | * You can't pass filenames here, you _have_ to pass |
572 | * directory names only and add possible filename in |
573 | * that directory yourself. A directory name always has a |
574 | * trailing slash ('/'). |
575 | * @param create If set, saveLocation() will create the directories |
576 | * needed (including those given by @p suffix). |
577 | * |
578 | * @return A path where resources of the specified type should be |
579 | * saved, or QString() if the resource type is unknown. |
580 | */ |
581 | QString saveLocation(const char *type, |
582 | const QString& suffix = QString(), |
583 | bool create = true) const; |
584 | |
585 | /** |
586 | * Converts an absolute path to a path relative to a certain |
587 | * resource. |
588 | * |
589 | * If "abs = ::locate(resource, rel)" |
590 | * then "rel = relativeLocation(resource, abs)" and vice versa. |
591 | * |
592 | * @param type The type of resource. |
593 | * |
594 | * @param absPath An absolute path to make relative. |
595 | * |
596 | * @return A relative path relative to resource @p type that |
597 | * will find @p absPath. If no such relative path exists, @p absPath |
598 | * will be returned unchanged. |
599 | */ |
600 | QString relativeLocation(const char *type, const QString &absPath); |
601 | |
602 | /** |
603 | * Recursively creates still-missing directories in the given path. |
604 | * |
605 | * The resulting permissions will depend on the current umask setting. |
606 | * <tt>permission = mode & ~umask</tt>. |
607 | * |
608 | * @param dir Absolute path of the directory to be made. |
609 | * @param mode Directory permissions. |
610 | * @return true if successful, false otherwise |
611 | */ |
612 | static bool makeDir(const QString& dir, int mode = 0755); |
613 | |
614 | /** |
615 | * This returns a default relative path for the standard KDE |
616 | * resource types. Below is a list of them so you get an idea |
617 | * of what this is all about. |
618 | * |
619 | * @li @c data - @c share/apps |
620 | * @li @c html - @c share/doc/HTML |
621 | * @li @c icon - @c share/icon |
622 | * @li @c config - @c share/config |
623 | * @li @c pixmap - @c share/pixmaps |
624 | * @li @c apps - @c share/applnk |
625 | * @li @c sound - @c share/sounds |
626 | * @li @c locale - @c share/locale |
627 | * @li @c services - @c share/kde4/services |
628 | * @li @c servicetypes - @c share/kde4/servicetypes |
629 | * @li @c mime - @c share/mimelnk |
630 | * @li @c cgi - @c cgi-bin |
631 | * @li @c wallpaper - @c share/wallpapers |
632 | * @li @c templates - @c share/templates |
633 | * @li @c exe - @c bin |
634 | * @li @c lib - @c lib[suffix] |
635 | * @li @c module - @c lib[suffix]/kde4 |
636 | * @li @c qtplugins - @c lib[suffix]/kde4/plugins |
637 | * @li @c kcfg - @c share/config.kcfg |
638 | * @li @c emoticons - @c share/emoticons |
639 | * @li @c xdgdata-apps - @c applications |
640 | * @li @c xdgdata-icon - @c icons |
641 | * @li @c xdgdata-pixmap - @c pixmaps |
642 | * @li @c xdgdata-dirs - @c desktop-directories |
643 | * @li @c xdgdata-mime - @c mime |
644 | * @li @c xdgconf-menu - @c menus |
645 | * |
646 | * @returns Static default for the specified resource. You |
647 | * should probably be using locate() or locateLocal() |
648 | * instead. |
649 | * @see locate() |
650 | * @see locateLocal() |
651 | */ |
652 | #ifndef KDE_NO_DEPRECATED |
653 | static KDE_DEPRECATED QString kde_default(const char *type); |
654 | #endif |
655 | |
656 | /** |
657 | * @internal (for use by sycoca only) |
658 | */ |
659 | QString kfsstnd_prefixes(); |
660 | |
661 | /** |
662 | * @internal (for use by sycoca only) |
663 | */ |
664 | QString kfsstnd_xdg_conf_prefixes(); |
665 | |
666 | /** |
667 | * @internal (for use by sycoca only) |
668 | */ |
669 | QString kfsstnd_xdg_data_prefixes(); |
670 | |
671 | /** |
672 | * Returns the toplevel directory in which KStandardDirs |
673 | * will store things. Most likely <tt>$HOME/.kde</tt>. |
674 | * Don't use this function if you can use locateLocal() |
675 | * @return the toplevel directory |
676 | */ |
677 | QString localkdedir() const; |
678 | |
679 | /** |
680 | * @return @c $XDG_DATA_HOME |
681 | * See also http://www.freedesktop.org/standards/basedir/draft/basedir-spec/basedir-spec.html |
682 | */ |
683 | QString localxdgdatadir() const; |
684 | |
685 | /** |
686 | * @return @c $XDG_CONFIG_HOME |
687 | * See also http://www.freedesktop.org/standards/basedir/draft/basedir-spec/basedir-spec.html |
688 | */ |
689 | QString localxdgconfdir() const; |
690 | |
691 | /** |
692 | * @return the path where type was installed to by kdelibs. This is an absolute path and only |
693 | * one out of many search paths |
694 | */ |
695 | static QString installPath(const char *type); |
696 | |
697 | /** |
698 | * Checks for existence and accessability of a file or directory. |
699 | * Faster than creating a QFileInfo first. |
700 | * @param fullPath the path to check. IMPORTANT: must end with a slash if expected to be a directory |
701 | * (and no slash for a file, obviously). |
702 | * @return @c true if the directory exists, @c false otherwise |
703 | */ |
704 | static bool exists(const QString &fullPath); |
705 | |
706 | /** |
707 | * Expands all symbolic links and resolves references to |
708 | * '/./', '/../' and extra '/' characters in @p dirname |
709 | * and returns the canonicalized absolute pathname. |
710 | * The resulting path will have no symbolic link, '/./' |
711 | * or '/../' components. |
712 | */ |
713 | static QString realPath(const QString &dirname); |
714 | |
715 | /** |
716 | * Expands all symbolic links and resolves references to |
717 | * '/./', '/../' and extra '/' characters in @p filename |
718 | * and returns the canonicalized absolute pathname. |
719 | * The resulting path will have no symbolic link, '/./' |
720 | * or '/../' components. |
721 | */ |
722 | static QString realFilePath(const QString &filename); |
723 | |
724 | /** |
725 | * This function is just for convenience. It simply calls |
726 | * instance->dirs()->\link KStandardDirs::findResource() findResource\endlink(type, filename). |
727 | * |
728 | * @param type The type of the wanted resource, see KStandardDirs |
729 | * @param filename A relative filename of the resource |
730 | * @param cData The KComponentData object |
731 | * |
732 | * @return A full path to the filename specified in the second |
733 | * argument, or QString() if not found |
734 | **/ |
735 | static QString locate( const char *type, const QString& filename, const KComponentData &cData = KGlobal::mainComponent() ); |
736 | |
737 | /** |
738 | * This function is much like locate. However it returns a |
739 | * filename suitable for writing to. No check is made if the |
740 | * specified @p filename actually exists. Missing directories |
741 | * are created. If @p filename is only a directory, without a |
742 | * specific file, @p filename must have a trailing slash. |
743 | * |
744 | * @param type The type of the wanted resource, see KStandardDirs |
745 | * @param filename A relative filename of the resource |
746 | * @param cData The KComponentData object |
747 | * |
748 | * @return A full path to the filename specified in the second |
749 | * argument, or QString() if not found |
750 | **/ |
751 | static QString locateLocal( const char *type, const QString& filename, const KComponentData &cData = KGlobal::mainComponent() ); |
752 | |
753 | /** |
754 | * This function is much like locate. No check is made if the |
755 | * specified filename actually exists. Missing directories |
756 | * are created if @p createDir is true. If @p filename is only |
757 | * a directory, without a specific file, @p filename must have |
758 | * a trailing slash. |
759 | * |
760 | * @param type The type of the wanted resource, see KStandardDirs |
761 | * @param filename A relative filename of the resource |
762 | * @param createDir If @c true, missing directories are created, |
763 | * if @c false, no directory is created |
764 | * @param cData The KComponentData object |
765 | * |
766 | * @return A full path to the filename specified in the second |
767 | * argument, or QString() if not found |
768 | **/ |
769 | static QString locateLocal( const char *type, const QString& filename, bool createDir, const KComponentData &cData = KGlobal::mainComponent() ); |
770 | |
771 | /** |
772 | * Check, if a file may be accessed in a given mode. |
773 | * This is a wrapper around the access() system call. |
774 | * checkAccess() calls access() with the given parameters. |
775 | * If this is OK, checkAccess() returns true. If not, and W_OK |
776 | * is part of mode, it is checked if there is write access to |
777 | * the directory. If yes, checkAccess() returns true. |
778 | * In all other cases checkAccess() returns false. |
779 | * |
780 | * Other than access() this function EXPLICITLY ignores non-existent |
781 | * files if checking for write access. |
782 | * |
783 | * @param pathname The full path of the file you want to test |
784 | * @param mode The access mode, as in the access() system call. |
785 | * @return Whether the access is allowed, true = Access allowed |
786 | */ |
787 | static bool checkAccess(const QString& pathname, int mode); |
788 | |
789 | private: |
790 | // Disallow assignment and copy-construction |
791 | KStandardDirs( const KStandardDirs& ); |
792 | KStandardDirs& operator= ( const KStandardDirs& ); |
793 | |
794 | class KStandardDirsPrivate; |
795 | KStandardDirsPrivate* const d; |
796 | |
797 | // Like their public counter parts but with an extra priority argument |
798 | // If priority is true, the directory is added directly after |
799 | // $KDEHOME/$XDG_DATA_HOME/$XDG_CONFIG_HOME |
800 | void addPrefix( const QString& dir, bool priority ); |
801 | void addXdgConfigPrefix( const QString& dir, bool priority ); |
802 | void addXdgDataPrefix( const QString& dir, bool priority ); |
803 | void addKDEDefaults(); |
804 | |
805 | void addResourcesFrom_krcdirs(); |
806 | }; |
807 | |
808 | Q_DECLARE_OPERATORS_FOR_FLAGS(KStandardDirs::SearchOptions) |
809 | |
810 | #endif // KSTANDARDDIRS_H |
811 |
Warning: That file was not part of the compilation database. It may have many parsing errors.