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.h10
1 files changed, 5 insertions, 5 deletions
diff --git a/microkde/kdecore/kstandarddirs.h b/microkde/kdecore/kstandarddirs.h
index 901384e..f0e28fc 100644
--- a/microkde/kdecore/kstandarddirs.h
+++ b/microkde/kdecore/kstandarddirs.h
@@ -1,123 +1,123 @@
1/* 1/*
2 This file is part of the KDE libraries 2 This file is part of the KDE libraries
3 Copyright (C) 1999 Sirtaj Singh Kang <taj@kde.org> 3 Copyright (C) 1999 Sirtaj Singh Kang <taj@kde.org>
4 Stephan Kulow <coolo@kde.org> 4 Stephan Kulow <coolo@kde.org>
5 Waldo Bastian <bastian@kde.org> 5 Waldo Bastian <bastian@kde.org>
6 6
7 This library is free software; you can redistribute it and/or 7 This library is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Library General Public 8 modify it under the terms of the GNU Library General Public
9 License as published by the Free Software Foundation; either 9 License as published by the Free Software Foundation; either
10 version 2 of the License, or (at your option) any later version. 10 version 2 of the License, or (at your option) any later version.
11 11
12 This library is distributed in the hope that it will be useful, 12 This library is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of 13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Library General Public License for more details. 15 Library General Public License for more details.
16 16
17 You should have received a copy of the GNU Library General Public License 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 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, 19 the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20 Boston, MA 02111-1307, USA. 20 Boston, MA 02111-1307, USA.
21*/ 21*/
22 22
23#ifndef SSK_KSTDDIRS_H 23#ifndef SSK_KSTDDIRS_H
24#define SSK_KSTDDIRS_H 24#define SSK_KSTDDIRS_H
25 25
26#include <qstring.h> 26#include <qstring.h>
27#include <qdict.h> 27#include <q3dict.h>
28#include <qstringlist.h> 28#include <qstringlist.h>
29#include <kglobal.h> 29#include <kglobal.h>
30 30
31class KConfig; 31class KConfig;
32class KStandardDirsPrivate; 32class KStandardDirsPrivate;
33 33
34 34
35/** 35/**
36 * @short Site-independent access to standard KDE directories. 36 * @short Site-independent access to standard KDE directories.
37 * @author Stephan Kulow <coolo@kde.org> and Sirtaj Singh Kang <taj@kde.org> 37 * @author Stephan Kulow <coolo@kde.org> and Sirtaj Singh Kang <taj@kde.org>
38 * @version $Id$ 38 * @version $Id$
39 * 39 *
40 * This is one of the most central classes in kdelibs as 40 * This is one of the most central classes in kdelibs as
41 * it provides a basic service: It knows where the files 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 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 43 * only one that knows -- to make the real location as
44 * transparent as possible to both the user and the applications. 44 * transparent as possible to both the user and the applications.
45 * 45 *
46 * To this end it insulates the application from all information 46 * To this end it insulates the application from all information
47 * and applications always refer to a file with a resource type 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 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 49 * the application would make no assumption where this file is and
50 * leave it up to @ref KStandardDirs::findResource("apps", "Home.desktop") 50 * leave it up to @ref KStandardDirs::findResource("apps", "Home.desktop")
51 * to apply this knowledge to return /opt/kde/share/applnk/Home.desktop 51 * to apply this knowledge to return /opt/kde/share/applnk/Home.desktop
52 * or ::locate("data", "kgame/background.jpg") to return 52 * or ::locate("data", "kgame/background.jpg") to return
53 * /opt/kde/share/apps/kgame/background.jpg 53 * /opt/kde/share/apps/kgame/background.jpg
54 * 54 *
55 * The main idea behind KStandardDirs is that there are several 55 * The main idea behind KStandardDirs is that there are several
56 * toplevel prefixes below which the files lie. One of these prefixes is 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 57 * the one where the user installed kdelibs, one is where the
58 * application was installed, and one is $HOME/.kde, but there 58 * application was installed, and one is $HOME/.kde, but there
59 * may be even more. Under these prefixes there are several well 59 * may be even more. Under these prefixes there are several well
60 * defined suffixes where specific resource types are to be found. 60 * defined suffixes where specific resource types are to be found.
61 * For example, for the resource type "html" the suffixes could be 61 * For example, for the resource type "html" the suffixes could be
62 * share/doc/HTML and share/doc/kde/HTML. 62 * share/doc/HTML and share/doc/kde/HTML.
63 * So the search algorithm basicly appends to each prefix each registered 63 * So the search algorithm basicly appends to each prefix each registered
64 * suffix and tries to locate the file there. 64 * suffix and tries to locate the file there.
65 * To make the thing even more complex, it's also possible to register 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 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 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, 68 * specific directories that aren't in his $HOME/.kde directory for,
69 * for example, icons. 69 * for example, icons.
70 * 70 *
71 * @sect Standard resources that kdelibs allocates are: 71 * @sect Standard resources that kdelibs allocates are:
72 * 72 *
73 * @li apps - Applications menu (.desktop files). 73 * @li apps - Applications menu (.desktop files).
74 * @li cache - Cached information (e.g. favicons, web-pages) 74 * @li cache - Cached information (e.g. favicons, web-pages)
75 * @li cgi - CGIs to run from kdehelp. 75 * @li cgi - CGIs to run from kdehelp.
76 * @li config - Configuration files. 76 * @li config - Configuration files.
77 * @li data - Where applications store data. 77 * @li data - Where applications store data.
78 * @li exe - Executables in $prefix/bin. @ref findExe() for a function that takes $PATH into account. 78 * @li exe - Executables in $prefix/bin. @ref findExe() for a function that takes $PATH into account.
79 * @li html - HTML documentation. 79 * @li html - HTML documentation.
80 * @li icon - Icons, see @ref KIconLoader. 80 * @li icon - Icons, see @ref KIconLoader.
81 * @li lib - Libraries. 81 * @li lib - Libraries.
82 * @li locale - Translation files for @ref KLocale. 82 * @li locale - Translation files for @ref KLocale.
83 * @li mime - Mime types. 83 * @li mime - Mime types.
84 * @li module - Module (dynamically loaded library). 84 * @li module - Module (dynamically loaded library).
85 * @li qtplugins - Qt plugins (dynamically loaded objects for Qt) 85 * @li qtplugins - Qt plugins (dynamically loaded objects for Qt)
86 * @li services - Services. 86 * @li services - Services.
87 * @li servicetypes - Service types. 87 * @li servicetypes - Service types.
88 * @li scripts - Application scripting additions. 88 * @li scripts - Application scripting additions.
89 * @li sound - Application sounds. 89 * @li sound - Application sounds.
90 * @li templates - Templates 90 * @li templates - Templates
91 * @li wallpaper - Wallpapers. 91 * @li wallpaper - Wallpapers.
92 * @li tmp - Temporary files (specfic for both current host and current user) 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) 93 * @li socket - UNIX Sockets (specific for both current host and current user)
94 * 94 *
95 * A type that is added by the class @ref KApplication if you use it, is 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 96 * appdata. This one makes the use of the type data a bit easier as it
97 * appends the name of the application. 97 * appends the name of the application.
98 * So while you had to ::locate("data", "appname/filename") so you can 98 * So while you had to ::locate("data", "appname/filename") so you can
99 * also write ::locate("appdata", "filename") if your KApplication instance 99 * also write ::locate("appdata", "filename") if your KApplication instance
100 * is called "appname" (as set via KApplication's constructor or KAboutData, if 100 * is called "appname" (as set via KApplication's constructor or KAboutData, if
101 * you use the global KStandardDirs object @ref KGlobal::dirs()). 101 * you use the global KStandardDirs object @ref KGlobal::dirs()).
102 * Please note though that you cannot use the "appdata" 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 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 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"). 105 * to work around this by using ::locate("data", "appletname/filename").
106 * 106 *
107 * @sect KStandardDirs supports the following environment variables: 107 * @sect KStandardDirs supports the following environment variables:
108 * 108 *
109 * @li KDEDIRS: This may set an additional number of directory prefixes to 109 * @li KDEDIRS: This may set an additional number of directory prefixes to
110 * search for resources. The directories should be seperated 110 * search for resources. The directories should be seperated
111 * by ':'. The directories are searched in the order they are 111 * by ':'. The directories are searched in the order they are
112 * specified. 112 * specified.
113 * @li KDEDIR: Used for backwards compatibility. As KDEDIRS but only a single 113 * @li KDEDIR: Used for backwards compatibility. As KDEDIRS but only a single
114 * directory may be specified. If KDEDIRS is set KDEDIR is 114 * directory may be specified. If KDEDIRS is set KDEDIR is
115 * ignored. 115 * ignored.
116 * @li KDEHOME: The directory where changes are saved to. This directory is 116 * @li KDEHOME: The directory where changes are saved to. This directory is
117 * used to search for resources first. If KDEHOME is not 117 * used to search for resources first. If KDEHOME is not
118 * specified it defaults to "$HOME/.kde" 118 * specified it defaults to "$HOME/.kde"
119 * @li KDEROOTHOME: Like KDEHOME, but used for the root user. 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 120 * If KDEROOTHOME is not set it defaults to the .kde directory in the
121 * home directory of root, usually "/root/.kde". 121 * home directory of root, usually "/root/.kde".
122 * Note that the setting of $HOME is ignored in this case. 122 * Note that the setting of $HOME is ignored in this case.
123 * 123 *
@@ -481,197 +481,197 @@ public:
481 * will be returned unchanged. 481 * will be returned unchanged.
482 */ 482 */
483 QString relativeLocation(const char *type, const QString &absPath); 483 QString relativeLocation(const char *type, const QString &absPath);
484 484
485 /** 485 /**
486 * Recursively creates still-missing directories in the given path. 486 * Recursively creates still-missing directories in the given path.
487 * 487 *
488 * The resulting permissions will depend on the current umask setting. 488 * The resulting permissions will depend on the current umask setting.
489 * permission = mode & ~umask. 489 * permission = mode & ~umask.
490 * 490 *
491 * @param dir Absolute path of the directory to be made. 491 * @param dir Absolute path of the directory to be made.
492 * @param mode Directory permissions. 492 * @param mode Directory permissions.
493 * @return true if successful, false otherwise 493 * @return true if successful, false otherwise
494 */ 494 */
495 static bool makeDir(const QString& dir, int mode = 0755); 495 static bool makeDir(const QString& dir, int mode = 0755);
496 496
497 /** 497 /**
498 * This returns a default relative path for the standard KDE 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 499 * resource types. Below is a list of them so you get an idea
500 * of what this is all about. 500 * of what this is all about.
501 * 501 *
502 * @li data - share/apps 502 * @li data - share/apps
503 * @li html - share/doc/HTML 503 * @li html - share/doc/HTML
504 * @li icon - share/icon 504 * @li icon - share/icon
505 * @li config - share/config 505 * @li config - share/config
506 * @li pixmap - share/pixmaps 506 * @li pixmap - share/pixmaps
507 * @li apps - share/applnk 507 * @li apps - share/applnk
508 * @li sound - share/sounds 508 * @li sound - share/sounds
509 * @li locale - share/locale 509 * @li locale - share/locale
510 * @li services - share/services 510 * @li services - share/services
511 * @li servicetypes - share/servicetypes 511 * @li servicetypes - share/servicetypes
512 * @li mime - share/mimelnk 512 * @li mime - share/mimelnk
513 * @li wallpaper - share/wallpapers 513 * @li wallpaper - share/wallpapers
514 * @li templates - share/templates 514 * @li templates - share/templates
515 * @li exe - bin 515 * @li exe - bin
516 * @li lib - lib 516 * @li lib - lib
517 * 517 *
518 * @returns Static default for the specified resource. You 518 * @returns Static default for the specified resource. You
519 * should probably be using locate() or locateLocal() 519 * should probably be using locate() or locateLocal()
520 * instead. 520 * instead.
521 * @see locate() 521 * @see locate()
522 * @see locateLocal() 522 * @see locateLocal()
523 */ 523 */
524 static QString kde_default(const char *type); 524 static QString kde_default(const char *type);
525 525
526 /** 526 /**
527 * @internal (for use by sycoca only) 527 * @internal (for use by sycoca only)
528 */ 528 */
529 QString kfsstnd_prefixes(); 529 QString kfsstnd_prefixes();
530 530
531 /** 531 /**
532 * Returns the toplevel directory in which KStandardDirs 532 * Returns the toplevel directory in which KStandardDirs
533 * will store things. Most likely $HOME/.kde 533 * will store things. Most likely $HOME/.kde
534 * Don't use this function if you can use locateLocal 534 * Don't use this function if you can use locateLocal
535 * @return the toplevel directory 535 * @return the toplevel directory
536 */ 536 */
537 QString localkdedir() const; 537 QString localkdedir() const;
538 538
539 /** 539 /**
540 * @return $XDG_DATA_HOME 540 * @return $XDG_DATA_HOME
541 * See also http://www.freedesktop.org/standards/basedir/draft/basedir-spec/basedir-spec.html 541 * See also http://www.freedesktop.org/standards/basedir/draft/basedir-spec/basedir-spec.html
542 */ 542 */
543 QString localxdgdatadir() const; 543 QString localxdgdatadir() const;
544 544
545 /** 545 /**
546 * @return $XDG_CONFIG_HOME 546 * @return $XDG_CONFIG_HOME
547 * See also http://www.freedesktop.org/standards/basedir/draft/basedir-spec/basedir-spec.html 547 * See also http://www.freedesktop.org/standards/basedir/draft/basedir-spec/basedir-spec.html
548 */ 548 */
549 QString localxdgconfdir() const; 549 QString localxdgconfdir() const;
550 550
551 /** 551 /**
552 * Checks for existence and accessability. 552 * Checks for existence and accessability.
553 * Faster than creating a QFileInfo first. 553 * Faster than creating a QFileInfo first.
554 * @param fullPath the path to check 554 * @param fullPath the path to check
555 * @return true if the directory exists 555 * @return true if the directory exists
556 */ 556 */
557 static bool exists(const QString &fullPath); 557 static bool exists(const QString &fullPath);
558 558
559 /** 559 /**
560 * Expands all symbolic links and resolves references to 560 * Expands all symbolic links and resolves references to
561 * '/./', '/../' and extra '/' characters in @p dirname 561 * '/./', '/../' and extra '/' characters in @p dirname
562 * and returns the canonicalized absolute pathname. 562 * and returns the canonicalized absolute pathname.
563 * The resulting path will have no symbolic link, '/./' 563 * The resulting path will have no symbolic link, '/./'
564 * or '/../' components. 564 * or '/../' components.
565 * @since 3.1 565 * @since 3.1
566 */ 566 */
567 static QString realPath(const QString &dirname); 567 static QString realPath(const QString &dirname);
568 568
569 static void setAppDir( const QString & ); 569 static void setAppDir( const QString & );
570 static QString appDir(); 570 static QString appDir();
571 571
572 private: 572 private:
573 573
574 QStringList prefixes; 574 QStringList prefixes;
575 575
576 // Directory dictionaries 576 // Directory dictionaries
577 QDict<QStringList> absolutes; 577 Q3Dict<QStringList> absolutes;
578 QDict<QStringList> relatives; 578 Q3Dict<QStringList> relatives;
579 579
580 mutable QDict<QStringList> dircache; 580 mutable Q3Dict<QStringList> dircache;
581 mutable QDict<QString> savelocations; 581 mutable Q3Dict<QString> savelocations;
582 582
583 // Disallow assignment and copy-construction 583 // Disallow assignment and copy-construction
584 KStandardDirs( const KStandardDirs& ); 584 KStandardDirs( const KStandardDirs& );
585 KStandardDirs& operator= ( const KStandardDirs& ); 585 KStandardDirs& operator= ( const KStandardDirs& );
586 586
587 bool addedCustoms; 587 bool addedCustoms;
588 588
589 class KStandardDirsPrivate; 589 class KStandardDirsPrivate;
590 KStandardDirsPrivate *d; 590 KStandardDirsPrivate *d;
591//US 591//US
592 static QString mAppDir; 592 static QString mAppDir;
593 593
594 void checkConfig() const; 594 void checkConfig() const;
595 void applyDataRestrictions(const QString &) const; 595 void applyDataRestrictions(const QString &) const;
596 //US void createSpecialResource(const char*); 596 //US void createSpecialResource(const char*);
597}; 597};
598 598
599/** 599/**
600 * \addtogroup locates Locate Functions 600 * \addtogroup locates Locate Functions
601 * @{ 601 * @{
602 * On The Usage Of 'locate' and 'locateLocal' 602 * On The Usage Of 'locate' and 'locateLocal'
603 * 603 *
604 * Typical KDE applications use resource files in one out of 604 * Typical KDE applications use resource files in one out of
605 * three ways: 605 * three ways:
606 * 606 *
607 * 1) A resource file is read but is never written. A system 607 * 1) A resource file is read but is never written. A system
608 * default is supplied but the user can override this 608 * default is supplied but the user can override this
609 * default in his local .kde directory: 609 * default in his local .kde directory:
610 * 610 *
611 * \code 611 * \code
612 * // Code example 612 * // Code example
613 * myFile = locate("appdata", "groups.lst"); 613 * myFile = locate("appdata", "groups.lst");
614 * myData = myReadGroups(myFile); // myFile may be null 614 * myData = myReadGroups(myFile); // myFile may be null
615 * \endcode 615 * \endcode
616 * 616 *
617 * 2) A resource file is read and written. If the user has no 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. 618 * local version of the file the system default is used.
619 * The resource file is always written to the users local 619 * The resource file is always written to the users local
620 * .kde directory. 620 * .kde directory.
621 * 621 *
622 * \code 622 * \code
623 * // Code example 623 * // Code example
624 * myFile = locate("appdata", "groups.lst") 624 * myFile = locate("appdata", "groups.lst")
625 * myData = myReadGroups(myFile); 625 * myData = myReadGroups(myFile);
626 * ... 626 * ...
627 * doSomething(myData); 627 * doSomething(myData);
628 * ... 628 * ...
629 * myFile = locateLocal("appdata", "groups.lst"); 629 * myFile = locateLocal("appdata", "groups.lst");
630 * myWriteGroups(myFile, myData); 630 * myWriteGroups(myFile, myData);
631 * \endcode 631 * \endcode
632 * 632 *
633 * 3) A resource file is read and written. No system default 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. 634 * is used if the user has no local version of the file.
635 * The resource file is always written to the users local 635 * The resource file is always written to the users local
636 * .kde directory. 636 * .kde directory.
637 * 637 *
638 * \code 638 * \code
639 * // Code example 639 * // Code example
640 * myFile = locateLocal("appdata", "groups.lst"); 640 * myFile = locateLocal("appdata", "groups.lst");
641 * myData = myReadGroups(myFile); 641 * myData = myReadGroups(myFile);
642 * ... 642 * ...
643 * doSomething(myData); 643 * doSomething(myData);
644 * ... 644 * ...
645 * myFile = locateLocal("appdata", "groups.lst"); 645 * myFile = locateLocal("appdata", "groups.lst");
646 * myWriteGroups(myFile, myData); 646 * myWriteGroups(myFile, myData);
647 * \endcode 647 * \endcode
648 **/ 648 **/
649 649
650 650
651/*! 651/*!
652 * \relates KStandardDirs 652 * \relates KStandardDirs
653 * This function is just for convenience. It simply calls 653 * This function is just for convenience. It simply calls
654 *instance->dirs()->\link KStandardDirs::findResource() findResource\endlink(type, filename). 654 *instance->dirs()->\link KStandardDirs::findResource() findResource\endlink(type, filename).
655 **/ 655 **/
656QString locate( const char *type, const QString& filename /*US , const KInstance* instance = KGlobal::instance()*/ ); 656QString locate( const char *type, const QString& filename /*US , const KInstance* instance = KGlobal::instance()*/ );
657 657
658/*! 658/*!
659 * \relates KStandardDirs 659 * \relates KStandardDirs
660 * This function is much like locate. However it returns a 660 * This function is much like locate. However it returns a
661 * filename suitable for writing to. No check is made if the 661 * filename suitable for writing to. No check is made if the
662 * specified filename actually exists. Missing directories 662 * specified filename actually exists. Missing directories
663 * are created. If filename is only a directory, without a 663 * are created. If filename is only a directory, without a
664 * specific file, filename must have a trailing slash. 664 * specific file, filename must have a trailing slash.
665 * 665 *
666 **/ 666 **/
667QString locateLocal( const char *type, const QString& filename /*US , const KInstance* instance = KGlobal::instance() */ ); 667QString locateLocal( const char *type, const QString& filename /*US , const KInstance* instance = KGlobal::instance() */ );
668 668
669/*! 669/*!
670 * \relates KStandardDirs 670 * \relates KStandardDirs
671 * This function is much like locate. No check is made if the 671 * This function is much like locate. No check is made if the
672 * specified filename actually exists. Missing directories 672 * specified filename actually exists. Missing directories
673 * are created if @p createDir is true. If filename is only 673 * are created if @p createDir is true. If filename is only
674 * a directory, without a specific file, 674 * a directory, without a specific file,
675 * filename must have a trailing slash. 675 * filename must have a trailing slash.
676 * 676 *
677 **/ 677 **/