kdecore Library API Documentation

KStandardDirs Class Reference

Site-independent access to standard KDE directories. More...

#include <kstandarddirs.h>

Collaboration diagram for KStandardDirs:

Collaboration graph
[legend]
List of all members.

Public Member Functions

 KStandardDirs ()
 KStandardDirs' constructor.

virtual ~KStandardDirs ()
 KStandardDirs' destructor.

void addPrefix (const QString &dir)
 Adds another search dir to front of the fsstnd list.

bool addResourceType (const char *type, const QString &relativename)
 Adds suffixes for types.

bool addResourceDir (const char *type, const QString &absdir)
 Adds absolute path at the end of the search path for particular types (for example in case of icons where the user specifies extra paths).

QString findResource (const char *type, const QString &filename) const
 Tries to find a resource in the following order:
  • All PREFIX/ paths (most recent first).


bool isRestrictedResource (const char *type, const QString &relPath=QString::null) const
 Checks whether a resource is restricted as part of the KIOSK framework.

Q_UINT32 calcResourceHash (const char *type, const QString &filename, bool deep) const
 Returns a number that identifies this version of the resource.

QStringList findDirs (const char *type, const QString &reldir) const
 Tries to find all directories whose names consist of the specified type and a relative path.

QString findResourceDir (const char *type, const QString &filename) const
 Tries to find the directory the file is in.

QStringList findAllResources (const char *type, const QString &filter=QString::null, bool recursive=false, bool uniq=false) const
 Tries to find all resources with the specified type.

QStringList findAllResources (const char *type, const QString &filter, bool recursive, bool uniq, QStringList &relPaths) const
 Tries to find all resources with the specified type.

void addKDEDefaults ()
 This function adds the defaults that are used by the current KDE version.

bool addCustomized (KConfig *config)
 Reads customized entries out of the given config object and add them via addResourceDirs().

QStringList resourceDirs (const char *type) const
 This function is used internally by almost all other function as it serves and fills the directories cache.

QStringList allTypes () const
 This function will return a list of all the types that KStandardDirs supports.

QString saveLocation (const char *type, const QString &suffix=QString::null, bool create=true) const
 Finds a location to save files into for the given type in the user's home directory.

QString relativeLocation (const char *type, const QString &absPath)
 Converts an absolute path to a path relative to a certain resource.

QString kfsstnd_prefixes ()
QString localkdedir () const
 Returns the toplevel directory in which KStandardDirs will store things.


Static Public Member Functions

QString findExe (const QString &appname, const QString &pathstr=QString::null, bool ignoreExecBit=false)
 Finds the executable in the system path.

int findAllExe (QStringList &list, const QString &appname, const QString &pathstr=QString::null, bool ignoreExecBit=false)
 Finds all occurences of an executable in the system path.

bool makeDir (const QString &dir, int mode=0755)
 Recursively creates still-missing directories in the given path.

QString kde_default (const char *type)
 This returns a default relative path for the standard KDE resource types.

bool exists (const QString &fullPath)
 Checks for existence and accessability.

QString realPath (const QString &dirname)
 Expands all symbolic links and resolves references to '/./', '/../' and extra '/' characters in dirname and returns the canonicalized absolute pathname.


Related Functions

(Note that these are not member functions.)

QString locate (const char *type, const QString &filename, const KInstance *instance=KGlobal::instance())
QString locateLocal (const char *type, const QString &filename, const KInstance *instance=KGlobal::instance())

Detailed Description

Site-independent access to standard KDE directories.

Author:
Stephan Kulow <coolo@kde.org> and Sirtaj Singh Kang <taj@kde.org>
Version:
Id
kstandarddirs.h,v 1.100.2.1 2003/01/08 16:15:51 waba Exp
This is one of the most central classes in kdelibs as it provides a basic service: It knows where the files reside on the user's hard disk. And it's meant to be the only one that knows -- to make the real location as transparent as possible to both the user and the applications.

To this end it insulates the application from all information and applications always refer to a file with a resource type (e.g. icon) and a filename (e.g. khexdit.xpm). In an ideal world the application would make no assumption where this file is and leave it up to KStandardDirs::findResource("apps", "Home.desktop") to apply this knowledge to return /opt/kde/share/applnk/Home.desktop or ::locate("data", "kgame/background.jpg") to return /opt/kde/share/apps/kgame/background.jpg

The main idea behind KStandardDirs is that there are several toplevel prefixes below which the files lie. One of these prefixes is the one where the user installed kdelibs, one is where the application was installed, and one is $HOME/.kde, but there may be even more. Under these prefixes there are several well defined suffixes where specific resource types are to be found. For example, for the resource type "html" the suffixes could be share/doc/HTML and share/doc/kde/HTML. So the search algorithm basicly appends to each prefix each registered suffix and tries to locate the file there. To make the thing even more complex, it's also possible to register absolute paths that KStandardDirs looks up after not finding anything in the former steps. They can be useful if the user wants to provide specific directories that aren't in his $HOME/.kde directory for, for example, icons.

Standard resources that kdelibs allocates are:

A type that is added by the class KApplication if you use it, is appdata. This one makes the use of the type data a bit easier as it appends the name of the application. So while you had to ::locate("data", "appname/filename") so you can also write ::locate("appdata", "filename") if your KApplication instance is called "appname" (as set via KApplication's constructor or KAboutData, if you use the global KStandardDirs object KGlobal::dirs()). Please note though that you cannot use the "appdata" type if you intend to use it in an applet for Kicker because 'appname' would be "Kicker" instead of the applet's name. Therefore, for applets, you've got to work around this by using ::locate("data", "appletname/filename").

KStandardDirs supports the following environment variables:

See also:
KGlobalSettings

Definition at line 125 of file kstandarddirs.h.


Constructor & Destructor Documentation

KStandardDirs::KStandardDirs  ) 
 

KStandardDirs' constructor.

It just initializes the caches.

Definition at line 77 of file kstandarddirs.cpp.

References addKDEDefaults(), QDict< QString >::setAutoDelete(), and QDict< QStringList >::setAutoDelete().

KStandardDirs::~KStandardDirs  )  [virtual]
 

KStandardDirs' destructor.

Definition at line 86 of file kstandarddirs.cpp.


Member Function Documentation

void KStandardDirs::addPrefix const QString dir  ) 
 

Adds another search dir to front of the fsstnd list.

  • When compiling kdelibs, the prefix is added to this.
  • KDEDIRS or KDEDIR is taking into account
  • Additional dirs may be loaded from kdeglobals.
Parameters:
dir The directory to append relative paths to.

Definition at line 134 of file kstandarddirs.cpp.

References QString::at(), QDict< QStringList >::clear(), QString::isNull(), and QString::length().

Referenced by addCustomized(), and addKDEDefaults().

bool KStandardDirs::addResourceType const char *  type,
const QString relativename
 

Adds suffixes for types.

You may add as many as you need, but it is advised that there is exactly one to make writing definite. All basic types (kde_default) are added by addKDEDefaults(), but for those you can add more relative paths as well.

The later a suffix is added, the higher its priority. Note, that the suffix should end with / but doesn't have to start with one (as prefixes should end with one). So adding a suffix for app_pics would look like KGlobal::dirs()->addResourceType("app_pics", "share/app/pics");

Parameters:
type Specifies a short descriptive string to access files of this type.
relativename Specifies a directory relative to the root of the KFSSTND.
Returns:
true if successful, false otherwise.

Definition at line 154 of file kstandarddirs.cpp.

References KStdAction::copy(), QDict< QStringList >::find(), QDict< QStringList >::insert(), QString::isNull(), and QDict< QStringList >::remove().

Referenced by addKDEDefaults().

bool KStandardDirs::addResourceDir const char *  type,
const QString absdir
 

Adds absolute path at the end of the search path for particular types (for example in case of icons where the user specifies extra paths).

You shouldn't need this function in 99% of all cases besides adding user-given paths.

Parameters:
type Specifies a short descriptive string to access files of this type.
absdir Points to directory where to look for this specific type. Non-existant directories may be saved but pruned.
Returns:
true if successful, false otherwise.

Definition at line 176 of file kstandarddirs.cpp.

References KStdAction::copy(), QDict< QStringList >::find(), QDict< QStringList >::insert(), and QDict< QStringList >::remove().

Referenced by addCustomized(), and addKDEDefaults().

QString KStandardDirs::findResource const char *  type,
const QString filename
const
 

Tries to find a resource in the following order:

  • All PREFIX/ paths (most recent first).

  • All absolute paths (most recent first).
The filename should be a filename relative to the base dir for resources. So is a way to get the path to libkdecore.la to findResource("lib", "libkdecore.la"). KStandardDirs will then look into the subdir lib of all elements of all prefixes ($KDEDIRS) for a file libkdecore.la and return the path to the first one it finds (e.g. /opt/kde/lib/libkdecore.la)

Parameters:
type The type of the wanted resource
filename A relative filename of the resource.
Returns:
A full path to the filename specified in the second argument, or QString::null if not found.

Definition at line 196 of file kstandarddirs.cpp.

References QString::at(), findResourceDir(), and QString::isNull().

Referenced by KLibLoader::findLibrary(), and locate().

bool KStandardDirs::isRestrictedResource const char *  type,
const QString relPath = QString::null
const
 

Checks whether a resource is restricted as part of the KIOSK framework.

When a resource is restricted it means that user- specific files in the resource are ignored.

E.g. by restricting the "wallpaper" resource, only system-wide installed wallpapers will be found by this class. Wallpapers installed under the $KDEHOME directory will be ignored.

Parameters:
type The type of the resource to check
relPath A relative path in the resource.
Returns:
True if the resource is restricted.
Since:
3.1

Definition at line 92 of file kstandarddirs.cpp.

Referenced by KConfigINIBackEnd::parseConfigFiles().

Q_UINT32 KStandardDirs::calcResourceHash const char *  type,
const QString filename,
bool  deep
const
 

Returns a number that identifies this version of the resource.

When a change is made to the resource this number will change.

Parameters:
type The type of the wanted resource
filename A relative filename of the resource.
deep If true, all resources are taken into account otherwise only the one returned by findResource().
Returns:
A number identifying the current version of the resource.

Definition at line 231 of file kstandarddirs.cpp.

References QString::at(), and resourceDirs().

QStringList KStandardDirs::findDirs const char *  type,
const QString reldir
const
 

Tries to find all directories whose names consist of the specified type and a relative path.

So would findDirs("apps", "Settings") return

  • /opt/kde/share/applnk/Settings/
  • /home/joe/.kde/share/applnk/Settings/
Note that it appends / to the end of the directories, so you can use this right away as directory names.

Parameters:
type The type of the base directory.
reldir Relative directory.
Returns:
A list of matching directories, or an empty list if the resource specified is not found.

Definition at line 257 of file kstandarddirs.cpp.

References QDir::absPath(), QDir::exists(), resourceDirs(), and QDir::setPath().

QString KStandardDirs::findResourceDir const char *  type,
const QString filename
const
 

Tries to find the directory the file is in.

It works the same as findResource(), but it doesn't return the filename but the name of the directory.

This way the application can access a couple of files that have been installed into the same directory without having to look for each file.

findResourceDir("lib", "libkdecore.la") would return the path of the subdir libkdecore.la is found first in (e.g. /opt/kde/lib/)

Parameters:
type The type of the wanted resource
filename A relative filename of the resource.
Returns:
The directory where the file specified in the second argument is located, or QString::null if the type of resource specified is unknown or the resource cannot be found.

Definition at line 279 of file kstandarddirs.cpp.

References exists(), QString::isEmpty(), and resourceDirs().

Referenced by findResource().

QStringList KStandardDirs::findAllResources const char *  type,
const QString filter = QString::null,
bool  recursive = false,
bool  uniq = false
const
 

Tries to find all resources with the specified type.

The function will look into all specified directories and return all filenames in these directories.

Parameters:
type The type of resource to locate directories for.
filter Only accept filenames that fit to filter. The filter may consist of an optional directory and a QRegExp wildcard expression. E.g. "images\*.jpg". Use QString::null if you do not want a filter.
recursive Specifies if the function should decend into subdirectories.
uniq If specified, only return items which have unique suffixes - suppressing duplicated filenames.
Returns:
A list of directories matching the resource specified, or an empty list if the resource type is unknown.

Definition at line 513 of file kstandarddirs.cpp.

Referenced by KLocale::allCountriesTwoAlpha(), and KPalette::getPaletteList().

QStringList KStandardDirs::findAllResources const char *  type,
const QString filter,
bool  recursive,
bool  uniq,
QStringList relPaths
const
 

Tries to find all resources with the specified type.

The function will look into all specified directories and return all filenames (full and relative paths) in these directories.

Parameters:
type The type of resource to locate directories for.
filter Only accept filenames that fit to filter. The filter may consist of an optional directory and a QRegExp wildcard expression. E.g. "images\*.jpg". Use QString::null if you do not want a filter.
recursive Specifies if the function should decend into subdirectories.
uniq If specified, only return items which have unique suffixes.
list Of relative paths for the given type.
relPaths The list to store the relative paths into These can be used later to locate() the file
Returns:
A list of directories matching the resource specified, or an empty list if the resource type is unknown.

Definition at line 465 of file kstandarddirs.cpp.

References QString::at(), QString::findRev(), QString::isEmpty(), QString::left(), QString::length(), QString::mid(), and resourceDirs().

QString KStandardDirs::findExe const QString appname,
const QString pathstr = QString::null,
bool  ignoreExecBit = false
[static]
 

Finds the executable in the system path.

A valid executable must be a file and have its executable bit set.

Parameters:
appname The name of the executable file for which to search.
pathstr The path which will be searched. If this is null (default), the $PATH environment variable will be searched.
ignoreExecBit If true, an existing file will be returned even if its executable bit is not set.
Returns:
The path of the executable. If it was not found, it will return QString::null.
See also:
findAllExe()

Definition at line 672 of file kstandarddirs.cpp.

References QString::arg(), QFileInfo::exists(), QString::find(), QString::fromLatin1(), QString::fromLocal8Bit(), QDir::homeDirPath(), QFileInfo::isExecutable(), QFileInfo::isFile(), QFileInfo::isSymLink(), QString::length(), QString::local8Bit(), QString::mid(), QString::replace(), QFileInfo::setFile(), and QString::startsWith().

Referenced by resourceDirs().

int KStandardDirs::findAllExe QStringList list,
const QString appname,
const QString pathstr = QString::null,
bool  ignoreExecBit = false
[static]
 

Finds all occurences of an executable in the system path.

Parameters:
list Will be filled with the pathnames of all the executables found. Will be empty if the executable was not found.
appname The name of the executable for which to search.
pathstr The path list which will be searched. If this is 0 (default), the $PATH environment variable will be searched.
ignoreExecBit If true, an existing file will be returned even if its executable bit is not set.
Returns:
The number of executables found, 0 if none were found.
See also:
findExe()

Definition at line 742 of file kstandarddirs.cpp.

References QFileInfo::exists(), QFileInfo::isExecutable(), QFileInfo::isFile(), and QFileInfo::setFile().

void KStandardDirs::addKDEDefaults  ) 
 

This function adds the defaults that are used by the current KDE version.

It's a series of addResourceTypes() and addPrefix() calls. You normally wouldn't call this function because it's called for you from KGlobal.

Definition at line 966 of file kstandarddirs.cpp.

References addPrefix(), addResourceDir(), addResourceType(), QFile::decodeName(), QDir::homeDirPath(), QString::isEmpty(), kde_default(), and QString::length().

Referenced by KStandardDirs().

bool KStandardDirs::addCustomized KConfig config  ) 
 

Reads customized entries out of the given config object and add them via addResourceDirs().

Parameters:
config The object the entries are read from. This should contain global config files
Returns:
true if new config paths have been added from config.

Definition at line 1056 of file kstandarddirs.cpp.

References addPrefix(), addResourceDir(), QMap::begin(), QMap::end(), KConfig::entryMap(), KConfigBase::group(), KStdAccel::key(), QString::latin1(), KConfigBase::readBoolEntry(), KConfigBase::readListEntry(), QDict< QStringList >::remove(), resourceDirs(), KConfigBase::setGroup(), and QStringList::split().

Referenced by KInstance::config(), KInstance::dirs(), and KConfig::KConfig().

QStringList KStandardDirs::resourceDirs const char *  type  )  const
 

This function is used internally by almost all other function as it serves and fills the directories cache.

Parameters:
type The type of resource
Returns:
The list of possible directories for the specified type. The function updates the cache if possible. If the resource type specified is unknown, it will return an empty list. Note, that the directories are assured to exist beside the save location, which may not exist, but is returned anyway.

Definition at line 540 of file kstandarddirs.cpp.

References QDir::cleanDirPath(), QFile::decodeName(), QFile::encodeName(), QDir::exists(), QDict< QStringList >::find(), findExe(), QString::fromLatin1(), QDict< QStringList >::insert(), QString::isEmpty(), localkdedir(), realPath(), and QDir::setPath().

Referenced by addCustomized(), KIconLoader::addExtraDesktopThemes(), calcResourceHash(), findAllResources(), findDirs(), findResourceDir(), KIconTheme::KIconTheme(), KLocale::langLookup(), KIconTheme::list(), relativeLocation(), and saveLocation().

QStringList KStandardDirs::allTypes  )  const
 

This function will return a list of all the types that KStandardDirs supports.

Returns:
All types that KDE supports

Definition at line 126 of file kstandarddirs.cpp.

References QString::fromLatin1().

QString KStandardDirs::saveLocation const char *  type,
const QString suffix = QString::null,
bool  create = true
const
 

Finds a location to save files into for the given type in the user's home directory.

Parameters:
type The type of location to return.
suffix A subdirectory name. Makes it easier for you to create subdirectories. You can't pass filenames here, you _have_ to pass directory names only and add possible filename in that directory yourself. A directory name always has a trailing slash ('/').
create If set, saveLocation() will create the directories needed (including those given by suffix).
Returns:
A path where resources of the specified type should be saved, or QString::null if the resource type is unknown.

Definition at line 840 of file kstandarddirs.cpp.

References KStdAction::create(), QFile::encodeName(), QDict< QStringList >::find(), QDict< QString >::find(), QDict< QString >::insert(), localkdedir(), makeDir(), realPath(), QDict< QStringList >::remove(), and resourceDirs().

Referenced by KConfigBackEnd::changeFileName(), and locateLocal().

QString KStandardDirs::relativeLocation const char *  type,
const QString absPath
 

Converts an absolute path to a path relative to a certain resource.

If "abs = ::locate(resource, rel)" then "rel = relativeLocation(resource, abs)" and vice versa.

Parameters:
type The type of resource.
absPath An absolute path to make relative.
Returns:
A relative path relative to resource type that will find absPath. If no such relative path exists, absPath will be returned unchanged.

Definition at line 888 of file kstandarddirs.cpp.

References QString::findRev(), QString::left(), QString::mid(), realPath(), resourceDirs(), and QString::startsWith().

Referenced by KDesktopFile::isAuthorizedDesktopFile().

bool KStandardDirs::makeDir const QString dir,
int  mode = 0755
[static]
 

Recursively creates still-missing directories in the given path.

The resulting permissions will depend on the current umask setting. permission = mode & ~umask.

Parameters:
dir Absolute path of the directory to be made.
mode Directory permissions.
Returns:
true if successful, false otherwise

Definition at line 910 of file kstandarddirs.cpp.

References QString::at(), QFile::encodeName(), QString::find(), QString::length(), and QString::mid().

Referenced by KConfigINIBackEnd::parseConfigFiles(), saveLocation(), and KConfigINIBackEnd::sync().

QString KStandardDirs::kde_default const char *  type  )  [static]
 

This returns a default relative path for the standard KDE resource types.

Below is a list of them so you get an idea of what this is all about.

  • data - share/apps
  • html - share/doc/HTML
  • icon - share/icon
  • config - share/config
  • pixmap - share/pixmaps
  • apps - share/applnk
  • sound - share/sounds
  • locale - share/locale
  • services - share/services
  • servicetypes - share/servicetypes
  • mime - share/mimelnk
  • wallpaper - share/wallpapers
  • templates - share/templates
  • exe - bin
  • lib - lib
Returns:
Static default for the specified resource. You should probably be using locate() or locateLocal() instead.
See also:
locate()

locateLocal()

Definition at line 799 of file kstandarddirs.cpp.

Referenced by KIconLoader::addAppDir(), and addKDEDefaults().

QString KStandardDirs::localkdedir  )  const
 

Returns the toplevel directory in which KStandardDirs will store things.

Most likely $HOME/.kde Don't use this function if you can use locateLocal

Returns:
the toplevel directory

Definition at line 1121 of file kstandarddirs.cpp.

Referenced by resourceDirs(), and saveLocation().

bool KStandardDirs::exists const QString fullPath  )  [static]
 

Checks for existence and accessability.

Faster than creating a QFileInfo first.

Parameters:
fullPath the path to check
Returns:
true if the directory exists

Definition at line 307 of file kstandarddirs.cpp.

References QFile::encodeName().

Referenced by KIconLoader::addExtraDesktopThemes(), findResourceDir(), KIconTheme::KIconTheme(), and KIconTheme::list().

QString KStandardDirs::realPath const QString dirname  )  [static]
 

Expands all symbolic links and resolves references to '/./', '/../' and extra '/' characters in dirname and returns the canonicalized absolute pathname.

The resulting path will have no symbolic link, '/./' or '/../' components.

Since:
3.1

Definition at line 523 of file kstandarddirs.cpp.

References QFile::decodeName(), and QFile::encodeName().

Referenced by relativeLocation(), resourceDirs(), and saveLocation().


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kdelibs Version 3.1.5.
Documentation copyright © 1996-2002 the KDE developers.
Generated on Wed Jan 28 12:51:41 2004 by doxygen 1.3.4 written by Dimitri van Heesch, © 1997-2001