summaryrefslogtreecommitdiffabout
path: root/microkde/kdecore/kstandarddirs.h
Unidiff
Diffstat (limited to 'microkde/kdecore/kstandarddirs.h') (more/less context) (ignore whitespace changes)
-rw-r--r--microkde/kdecore/kstandarddirs.h681
1 files changed, 681 insertions, 0 deletions
diff --git a/microkde/kdecore/kstandarddirs.h b/microkde/kdecore/kstandarddirs.h
new file mode 100644
index 0000000..c4e1108
--- a/dev/null
+++ b/microkde/kdecore/kstandarddirs.h
@@ -0,0 +1,681 @@
1/*
2 This file is part of the KDE libraries
3 Copyright (C) 1999 Sirtaj Singh Kang <taj@kde.org>
4 Stephan Kulow <coolo@kde.org>
5 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., 59 Temple Place - Suite 330,
20 Boston, MA 02111-1307, USA.
21*/
22
23#ifndef SSK_KSTDDIRS_H
24#define SSK_KSTDDIRS_H
25
26#include <qstring.h>
27#include <qdict.h>
28#include <qstringlist.h>
29#include <kglobal.h>
30
31class KConfig;
32class KStandardDirsPrivate;
33
34
35/**
36 * @short Site-independent access to standard KDE directories.
37 * @author Stephan Kulow <coolo@kde.org> and Sirtaj Singh Kang <taj@kde.org>
38 * @version $Id$
39 *
40 * This is one of the most central classes in kdelibs as
41 * it provides a basic service: It knows where the files
42 * reside on the user's hard disk. And it's meant to be the
43 * only one that knows -- to make the real location as
44 * transparent as possible to both the user and the applications.
45 *
46 * To this end it insulates the application from all information
47 * and applications always refer to a file with a resource type
48 * (e.g. icon) and a filename (e.g. khexdit.xpm). In an ideal world
49 * the application would make no assumption where this file is and
50 * leave it up to @ref KStandardDirs::findResource("apps", "Home.desktop")
51 * to apply this knowledge to return /opt/kde/share/applnk/Home.desktop
52 * or ::locate("data", "kgame/background.jpg") to return
53 * /opt/kde/share/apps/kgame/background.jpg
54 *
55 * The main idea behind KStandardDirs is that there are several
56 * toplevel prefixes below which the files lie. One of these prefixes is
57 * the one where the user installed kdelibs, one is where the
58 * application was installed, and one is $HOME/.kde, but there
59 * may be even more. Under these prefixes there are several well
60 * defined suffixes where specific resource types are to be found.
61 * For example, for the resource type "html" the suffixes could be
62 * share/doc/HTML and share/doc/kde/HTML.
63 * So the search algorithm basicly appends to each prefix each registered
64 * suffix and tries to locate the file there.
65 * To make the thing even more complex, it's also possible to register
66 * absolute paths that KStandardDirs looks up after not finding anything
67 * in the former steps. They can be useful if the user wants to provide
68 * specific directories that aren't in his $HOME/.kde directory for,
69 * for example, icons.
70 *
71 * @sect Standard resources that kdelibs allocates are:
72 *
73 * @li apps - Applications menu (.desktop files).
74 * @li cache - Cached information (e.g. favicons, web-pages)
75 * @li cgi - CGIs to run from kdehelp.
76 * @li config - Configuration files.
77 * @li data - Where applications store data.
78 * @li exe - Executables in $prefix/bin. @ref findExe() for a function that takes $PATH into account.
79 * @li html - HTML documentation.
80 * @li icon - Icons, see @ref KIconLoader.
81 * @li lib - Libraries.
82 * @li locale - Translation files for @ref KLocale.
83 * @li mime - Mime types.
84 * @li module - Module (dynamically loaded library).
85 * @li qtplugins - Qt plugins (dynamically loaded objects for Qt)
86 * @li services - Services.
87 * @li servicetypes - Service types.
88 * @li scripts - Application scripting additions.
89 * @li sound - Application sounds.
90 * @li templates - Templates
91 * @li wallpaper - Wallpapers.
92 * @li tmp - Temporary files (specfic for both current host and current user)
93 * @li socket - UNIX Sockets (specific for both current host and current user)
94 *
95 * A type that is added by the class @ref KApplication if you use it, is
96 * 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 "appname" (as set via KApplication's constructor or KAboutData, if
101 * you use the global KStandardDirs object @ref KGlobal::dirs()).
102 * Please note though that you cannot use the "appdata"
103 * type if you intend to use it in an applet for Kicker because 'appname' would
104 * be "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 * @sect KStandardDirs supports the following environment variables:
108 *
109 * @li KDEDIRS: This may set an additional number of directory prefixes to
110 * search for resources. The directories should be seperated
111 * by ':'. The directories are searched in the order they are
112 * specified.
113 * @li KDEDIR: Used for backwards compatibility. As KDEDIRS but only a single
114 * directory may be specified. If KDEDIRS is set KDEDIR is
115 * ignored.
116 * @li KDEHOME: The directory where changes are saved to. This directory is
117 * used to search for resources first. If KDEHOME is not
118 * specified it defaults to "$HOME/.kde"
119 * @li KDEROOTHOME: Like KDEHOME, but used for the root user.
120 * If KDEROOTHOME is not set it defaults to the .kde directory in the
121 * home directory of root, usually "/root/.kde".
122 * Note that the setting of $HOME is ignored in this case.
123 *
124 * @see KGlobalSettings
125 */
126class KStandardDirs
127{
128public:
129 /**
130 * KStandardDirs' constructor. It just initializes the caches.
131 **/
132 KStandardDirs( );
133
134 /**
135 * KStandardDirs' destructor.
136 */
137 virtual ~KStandardDirs();
138
139 /**
140 * Adds another search dir to front of the @p fsstnd list.
141 *
142 * @li When compiling kdelibs, the prefix is added to this.
143 * @li KDEDIRS or KDEDIR is taking into account
144 * @li Additional dirs may be loaded from kdeglobals.
145 *
146 * @param dir The directory to append relative paths to.
147 */
148 void addPrefix( const QString& dir );
149
150 /**
151 * Adds another search dir to front of the XDG_CONFIG_XXX list
152 * of prefixes.
153 * This prefix is only used for resources that start with "xdgconf-"
154 *
155 * @param dir The directory to append relative paths to.
156 */
157 void addXdgConfigPrefix( const QString& dir );
158
159 /**
160 * Adds another search dir to front of the XDG_DATA_XXX list
161 * of prefixes.
162 * This prefix is only used for resources that start with "xdgdata-"
163 *
164 * @param dir The directory to append relative paths to.
165 */
166 void addXdgDataPrefix( const QString& dir );
167
168 /**
169 * Adds suffixes for types.
170 *
171 * You may add as many as you need, but it is advised that there
172 * is exactly one to make writing definite.
173 * All basic types (@ref kde_default) are added by @ref addKDEDefaults(),
174 * but for those you can add more relative paths as well.
175 *
176 * The later a suffix is added, the higher its priority. Note, that the
177 * suffix should end with / but doesn't have to start with one (as prefixes
178 * should end with one). So adding a suffix for app_pics would look
179 * like KGlobal::dirs()->addResourceType("app_pics", "share/app/pics");
180 *
181 * @param type Specifies a short descriptive string to access
182 * files of this type.
183 * @param relativename Specifies a directory relative to the root
184 * of the KFSSTND.
185 * @return true if successful, false otherwise.
186 */
187 bool addResourceType( const char *type,
188 const QString& relativename );
189
190 /**
191 * Adds absolute path at the end of the search path for
192 * particular types (for example in case of icons where
193 * the user specifies extra paths).
194 *
195 * You shouldn't need this
196 * function in 99% of all cases besides adding user-given
197 * paths.
198 *
199 * @param type Specifies a short descriptive string to access files
200 * of this type.
201 * @param absdir Points to directory where to look for this specific
202 * type. Non-existant directories may be saved but pruned.
203 * @return true if successful, false otherwise.
204 */
205 bool addResourceDir( const char *type,
206 const QString& absdir);
207
208 /**
209 * Tries to find a resource in the following order:
210 * @li All PREFIX/\<relativename> paths (most recent first).
211 * @li All absolute paths (most recent first).
212 *
213 * The filename should be a filename relative to the base dir
214 * for resources. So is a way to get the path to libkdecore.la
215 * to findResource("lib", "libkdecore.la"). KStandardDirs will
216 * then look into the subdir lib of all elements of all prefixes
217 * ($KDEDIRS) for a file libkdecore.la and return the path to
218 * the first one it finds (e.g. /opt/kde/lib/libkdecore.la)
219 *
220 * @param type The type of the wanted resource
221 * @param filename A relative filename of the resource.
222 *
223 * @return A full path to the filename specified in the second
224 * argument, or QString::null if not found.
225 */
226 QString findResource( const char *type,
227 const QString& filename ) const;
228
229 /**
230 * Checks whether a resource is restricted as part of the KIOSK
231 * framework. When a resource is restricted it means that user-
232 * specific files in the resource are ignored.
233 *
234 * E.g. by restricting the "wallpaper" resource, only system-wide
235 * installed wallpapers will be found by this class. Wallpapers
236 * installed under the $KDEHOME directory will be ignored.
237 *
238 * @param type The type of the resource to check
239 * @param relPath A relative path in the resource.
240 *
241 * @return True if the resource is restricted.
242 * @since 3.1
243 */
244 bool isRestrictedResource( const char *type,
245 const QString& relPath=QString::null ) const;
246
247 /**
248 * Returns a number that identifies this version of the resource.
249 * When a change is made to the resource this number will change.
250 *
251 * @param type The type of the wanted resource
252 * @param filename A relative filename of the resource.
253 * @param deep If true, all resources are taken into account
254 * otherwise only the one returned by findResource().
255 *
256 * @return A number identifying the current version of the
257 * resource.
258 */
259/*US
260 Q_UINT32 calcResourceHash( const char *type,
261 const QString& filename, bool deep) const;
262*/
263 /**
264 * Tries to find all directories whose names consist of the
265 * specified type and a relative path. So would
266 * findDirs("apps", "Settings") return
267 * @li /opt/kde/share/applnk/Settings/
268 * @li /home/joe/.kde/share/applnk/Settings/
269 *
270 * Note that it appends / to the end of the directories,
271 * so you can use this right away as directory names.
272 *
273 * @param type The type of the base directory.
274 * @param reldir Relative directory.
275 *
276 * @return A list of matching directories, or an empty
277 * list if the resource specified is not found.
278 */
279 QStringList findDirs( const char *type,
280 const QString& reldir ) const;
281
282 /**
283 * Tries to find the directory the file is in.
284 * It works the same as @ref findResource(), but it doesn't
285 * return the filename but the name of the directory.
286 *
287 * This way the application can access a couple of files
288 * that have been installed into the same directory without
289 * having to look for each file.
290 *
291 * findResourceDir("lib", "libkdecore.la") would return the
292 * path of the subdir libkdecore.la is found first in
293 * (e.g. /opt/kde/lib/)
294 *
295 * @param type The type of the wanted resource
296 * @param filename A relative filename of the resource.
297 * @return The directory where the file specified in the second
298 * argument is located, or QString::null if the type
299 * of resource specified is unknown or the resource
300 * cannot be found.
301 */
302 QString findResourceDir( const char *type,
303 const QString& filename) const;
304
305
306 /**
307 * Tries to find all resources with the specified type.
308 *
309 * The function will look into all specified directories
310 * and return all filenames in these directories.
311 *
312 * @param type The type of resource to locate directories for.
313 * @param filter Only accept filenames that fit to filter. The filter
314 * may consist of an optional directory and a @ref QRegExp
315 * wildcard expression. E.g. "images\*.jpg". Use QString::null
316 * if you do not want a filter.
317 * @param recursive Specifies if the function should decend
318 * into subdirectories.
319 * @param uniq If specified, only return items which have
320 * unique suffixes - suppressing duplicated filenames.
321 *
322 * @return A list of directories matching the resource specified,
323 * or an empty list if the resource type is unknown.
324 */
325 QStringList findAllResources( const char *type,
326 const QString& filter = QString::null,
327 bool recursive = false,
328 bool uniq = false) const;
329
330 /**
331 * Tries to find all resources with the specified type.
332 *
333 * The function will look into all specified directories
334 * and return all filenames (full and relative paths) in
335 * these directories.
336 *
337 * @param type The type of resource to locate directories for.
338 * @param filter Only accept filenames that fit to filter. The filter
339 * may consist of an optional directory and a @ref QRegExp
340 * wildcard expression. E.g. "images\*.jpg". Use QString::null
341 * if you do not want a filter.
342 * @param recursive Specifies if the function should decend
343 * into subdirectories.
344 * @param uniq If specified, only return items which have
345 * unique suffixes.
346 * @param list Of relative paths for the given type.
347 * @param relPaths The list to store the relative paths into
348 * These can be used later to ::locate() the file
349 *
350 * @return A list of directories matching the resource specified,
351 * or an empty list if the resource type is unknown.
352 */
353 QStringList findAllResources( const char *type,
354 const QString& filter,
355 bool recursive,
356 bool uniq,
357 QStringList &relPaths) const;
358
359 /**
360 * Finds the executable in the system path.
361 *
362 * A valid executable must
363 * be a file and have its executable bit set.
364 *
365 * @param appname The name of the executable file for which to search.
366 * @param pathstr The path which will be searched. If this is
367 * null (default), the $PATH environment variable will
368 * be searched.
369 * @param ignoreExecBitIf true, an existing file will be returned
370 * even if its executable bit is not set.
371 *
372 * @return The path of the executable. If it was not found,
373 * it will return QString::null.
374 * @see findAllExe()
375 */
376/*US
377 static QString findExe( const QString& appname,
378 const QString& pathstr=QString::null,
379 bool ignoreExecBit=false );
380*/
381
382 /**
383 * Finds all occurences of an executable in the system path.
384 *
385 * @param listWill be filled with the pathnames of all the
386 * executables found. Will be empty if the executable
387 * was not found.
388 * @param appnameThe name of the executable for which to
389 * search.
390 * @param pathstrThe path list which will be searched. If this
391 * is 0 (default), the $PATH environment variable will
392 * be searched.
393 * @param ignoreExecBit If true, an existing file will be returned
394 * even if its executable bit is not set.
395 *
396 * @return The number of executables found, 0 if none were found.
397 *
398 * @seefindExe()
399 */
400 static int findAllExe( QStringList& list, const QString& appname,
401 const QString& pathstr=QString::null,
402 bool ignoreExecBit=false );
403
404 /**
405 * This function adds the defaults that are used by the current
406 * KDE version.
407 *
408 * It's a series of @ref addResourceTypes()
409 * and @ref addPrefix() calls.
410 * You normally wouldn't call this function because it's called
411 * for you from @ref KGlobal.
412 */
413 void addKDEDefaults();
414
415 /**
416 * Reads customized entries out of the given config object and add
417 * them via @ref addResourceDirs().
418 *
419 * @param config The object the entries are read from. This should
420 * contain global config files
421 * @return true if new config paths have been added
422 * from @p config.
423 **/
424 bool addCustomized(KConfig *config);
425
426 /**
427 * This function is used internally by almost all other function as
428 * it serves and fills the directories cache.
429 *
430 * @param type The type of resource
431 * @return The list of possible directories for the specified @p type.
432 * The function updates the cache if possible. If the resource
433 * type specified is unknown, it will return an empty list.
434 * Note, that the directories are assured to exist beside the save
435 * location, which may not exist, but is returned anyway.
436 */
437 QStringList resourceDirs(const char *type) const;
438
439 /**
440 * This function will return a list of all the types that KStandardDirs
441 * supports.
442 *
443 * @return All types that KDE supports
444 */
445 QStringList allTypes() const;
446
447 /**
448 * Finds a location to save files into for the given type
449 * in the user's home directory.
450 *
451 * @param type The type of location to return.
452 * @param suffix A subdirectory name.
453 * Makes it easier for you to create subdirectories.
454 * You can't pass filenames here, you _have_ to pass
455 * directory names only and add possible filename in
456 * that directory yourself. A directory name always has a
457 * trailing slash ('/').
458 * @param create If set, saveLocation() will create the directories
459 * needed (including those given by @p suffix).
460 *
461 * @return A path where resources of the specified type should be
462 * saved, or QString::null if the resource type is unknown.
463 */
464 QString saveLocation(const char *type,
465 const QString& suffix = QString::null,
466 bool create = true) const;
467
468 /**
469 * Converts an absolute path to a path relative to a certain
470 * resource.
471 *
472 * If "abs = ::locate(resource, rel)"
473 * then "rel = relativeLocation(resource, abs)" and vice versa.
474 *
475 * @param type The type of resource.
476 *
477 * @param absPath An absolute path to make relative.
478 *
479 * @return A relative path relative to resource @p type that
480 * will find @p absPath. If no such relative path exists, absPath
481 * will be returned unchanged.
482 */
483 QString relativeLocation(const char *type, const QString &absPath);
484
485 /**
486 * Recursively creates still-missing directories in the given path.
487 *
488 * The resulting permissions will depend on the current umask setting.
489 * permission = mode & ~umask.
490 *
491 * @param dir Absolute path of the directory to be made.
492 * @param mode Directory permissions.
493 * @return true if successful, false otherwise
494 */
495 static bool makeDir(const QString& dir, int mode = 0755);
496
497 /**
498 * This returns a default relative path for the standard KDE
499 * resource types. Below is a list of them so you get an idea
500 * of what this is all about.
501 *
502 * @li data - share/apps
503 * @li html - share/doc/HTML
504 * @li icon - share/icon
505 * @li config - share/config
506 * @li pixmap - share/pixmaps
507 * @li apps - share/applnk
508 * @li sound - share/sounds
509 * @li locale - share/locale
510 * @li services - share/services
511 * @li servicetypes - share/servicetypes
512 * @li mime - share/mimelnk
513 * @li wallpaper - share/wallpapers
514 * @li templates - share/templates
515 * @li exe - bin
516 * @li lib - lib
517 *
518 * @returns Static default for the specified resource. You
519 * should probably be using locate() or locateLocal()
520 * instead.
521 * @see locate()
522 * @see locateLocal()
523 */
524 static QString kde_default(const char *type);
525
526 /**
527 * @internal (for use by sycoca only)
528 */
529 QString kfsstnd_prefixes();
530
531 /**
532 * Returns the toplevel directory in which KStandardDirs
533 * will store things. Most likely $HOME/.kde
534 * Don't use this function if you can use locateLocal
535 * @return the toplevel directory
536 */
537 QString localkdedir() const;
538
539 /**
540 * @return $XDG_DATA_HOME
541 * See also http://www.freedesktop.org/standards/basedir/draft/basedir-spec/basedir-spec.html
542 */
543 QString localxdgdatadir() const;
544
545 /**
546 * @return $XDG_CONFIG_HOME
547 * See also http://www.freedesktop.org/standards/basedir/draft/basedir-spec/basedir-spec.html
548 */
549 QString localxdgconfdir() const;
550
551 /**
552 * Checks for existence and accessability.
553 * Faster than creating a QFileInfo first.
554 * @param fullPath the path to check
555 * @return true if the directory exists
556 */
557 static bool exists(const QString &fullPath);
558
559 /**
560 * Expands all symbolic links and resolves references to
561 * '/./', '/../' and extra '/' characters in @p dirname
562 * and returns the canonicalized absolute pathname.
563 * The resulting path will have no symbolic link, '/./'
564 * or '/../' components.
565 * @since 3.1
566 */
567 static QString realPath(const QString &dirname);
568
569 static void setAppDir( const QString & );
570 static QString appDir();
571
572 private:
573
574 QStringList prefixes;
575
576 // Directory dictionaries
577 QDict<QStringList> absolutes;
578 QDict<QStringList> relatives;
579
580 mutable QDict<QStringList> dircache;
581 mutable QDict<QString> savelocations;
582
583 // Disallow assignment and copy-construction
584 KStandardDirs( const KStandardDirs& );
585 KStandardDirs& operator= ( const KStandardDirs& );
586
587 bool addedCustoms;
588
589 class KStandardDirsPrivate;
590 KStandardDirsPrivate *d;
591//US
592 static QString mAppDir;
593
594 void checkConfig() const;
595 void applyDataRestrictions(const QString &) const;
596 //US void createSpecialResource(const char*);
597};
598
599/**
600 * \addtogroup locates Locate Functions
601 * @{
602 * On The Usage Of 'locate' and 'locateLocal'
603 *
604 * Typical KDE applications use resource files in one out of
605 * three ways:
606 *
607 * 1) A resource file is read but is never written. A system
608 * default is supplied but the user can override this
609 * default in his local .kde directory:
610 *
611 * \code
612 * // Code example
613 * myFile = locate("appdata", "groups.lst");
614 * myData = myReadGroups(myFile); // myFile may be null
615 * \endcode
616 *
617 * 2) A resource file is read and written. If the user has no
618 * local version of the file the system default is used.
619 * The resource file is always written to the users local
620 * .kde directory.
621 *
622 * \code
623 * // Code example
624 * myFile = locate("appdata", "groups.lst")
625 * myData = myReadGroups(myFile);
626 * ...
627 * doSomething(myData);
628 * ...
629 * myFile = locateLocal("appdata", "groups.lst");
630 * myWriteGroups(myFile, myData);
631 * \endcode
632 *
633 * 3) A resource file is read and written. No system default
634 * is used if the user has no local version of the file.
635 * The resource file is always written to the users local
636 * .kde directory.
637 *
638 * \code
639 * // Code example
640 * myFile = locateLocal("appdata", "groups.lst");
641 * myData = myReadGroups(myFile);
642 * ...
643 * doSomething(myData);
644 * ...
645 * myFile = locateLocal("appdata", "groups.lst");
646 * myWriteGroups(myFile, myData);
647 * \endcode
648 **/
649
650/*!
651 * \relates KStandardDirs
652 * This function is just for convenience. It simply calls
653 *instance->dirs()->\link KStandardDirs::findResource() findResource\endlink(type, filename).
654 **/
655QString locate( const char *type, const QString& filename /*US , const KInstance* instance = KGlobal::instance()*/ );
656
657/*!
658 * \relates KStandardDirs
659 * This function is much like locate. However it returns a
660 * filename suitable for writing to. No check is made if the
661 * specified filename actually exists. Missing directories
662 * are created. If filename is only a directory, without a
663 * specific file, filename must have a trailing slash.
664 *
665 **/
666QString locateLocal( const char *type, const QString& filename /*US , const KInstance* instance = KGlobal::instance() */ );
667
668/*!
669 * \relates KStandardDirs
670 * This function is much like locate. No check is made if the
671 * specified filename actually exists. Missing directories
672 * are created if @p createDir is true. If filename is only
673 * a directory, without a specific file,
674 * filename must have a trailing slash.
675 *
676 **/
677QString locateLocal( const char *type, const QString& filename, bool createDir /*US , const KInstance* instance = KGlobal::instance() */);
678
679/*! @} */
680
681#endif // SSK_KSTDDIRS_H