class KStandardDirs

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

Definition#include <kstddirs.h>
List of all Methods
Annotated List
Files
Globals
Hierarchy
Index

Public Methods

Public Static Methods


Detailed Description

This is one of the most central classes in kdelibs as it provides a basic service: Tt 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.

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 resourcet type "icon" the suffixes are be share/icons and share/apps/<appname>/icons, but also share/icons/large if the user prefers large icons. 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:

KStandardDirs supports the following environment variables:

KDEDIRS: This may set an additional number of directories to search for resources. The directories should be seperated by ':'. The directories are searched in the order they are specified. KDEDIR: Used for backwards compatibility. As KDEDIRS but only a single directory may be specified. If KDEDIRS is set KDEDIR is ignored. KDEHOME: The directory where changes are saved to. This directory is used to search for resources first. If KDEHOME is not specified it defaults to "$HOME/.kde"

KStandardDirs ( )

KStandardDirs constructor. It just initializes the cache.

~KStandardDirs ()
[virtual]

KStandardDirs destructor.

void addPrefix ( QString dir )

Add another search dir to front of the fsstnd list.

Parameters:
dirThe directory to append relative paths to.

bool addResourceType ( const char *type, const QString& relativename )

Add 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.

Parameters:
typeSpecifies a short descriptive string to access files of this type.
relativenameSpecifies a directory relative to the root of the KFSSTND.

bool addResourceDir ( const char *type, const QString& absdir)

Add 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:
typeSpecifies a short descriptive string to access files of this type.
absdirSoints to directory where to look for this specific type. Non-existant directories may be saved but pruned.

QString findResource ( const char *type, const QString& filename )
[const]

Try to find resource in the following order:

Returns: A full path to the filename specified in the second argument, or QString::null if not found.

QStringList findDirs ( const char *type, const QString& reldir )
[const]

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

Parameters:
typeThe type of the base directory.
reldirRelative directory.

Returns: A list of matching directories, or an empty list if the resource specified is not found.

QString findResourceDir ( const char *type, const QString& filename)
[const]

Try 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.

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.

QStringList findAllResources ( const char *type, const QString& filter = QString::null, bool recursive = false, bool uniq = false)
[const]

Try to find all resources with the specified type.

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

Parameters:
typeThe type of resource to locate directories for.
filterOnly accept filenames that fit to filter. The filter may consist of an optional directory and a QRexExp wildcard expression. E.g. "images\*.jpg"
recursiveSpecifies if the function should decend into subdirectories.
uniqIf specified, only return items which have unique suffixes.

Returns: A list of directories matching the resource specified, or an empty list if the resource type is unknown.

QStringList findAllResources ( const char *type, const QString& filter, bool recursive, bool uniq, QStringList &relPaths)
[const]

Try 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:
typeThe type of resource to locate directories for.
filterOnly accept filenames that fit to filter. The filter may consist of an optional directory and a QRexExp wildcard expression. E.g. "images\*.jpg"
recursiveSpecifies if the function should decend into subdirectories.
uniqIf specified, only return items which have unique suffixes.
listOf relative paths for the given type.

Returns: A list of directories matching the resource specified, or an empty list if the resource type is unknown.

QString findExe ( const QString& appname, const QString& pathstr=QString::null, bool ignoreExecBit=false )
[static]

Find the executable in the system path.

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

Parameters:
appnameThe name of the executable file for which to search.
pathstrThe path which will be searched. If this is 0 (default), the $PATH environment variable will be searched.
ignoreExecBitIf 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.

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

Find all occurences of an executable in the system path.

Parameters:
listWill be filled with the pathnames of all the executables found. Will be empty if the executable was not found.
appnameThe name of the executable for which to search.
pathstrThe path list which will be searched. If this is 0 (default), the $PATH environment variable will be searched.
ignoreExecBitIf 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.

void 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.

bool addCustomized (KConfig *config)

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

Parameters:
configThe object the entries are read from. This should contain global config files

Returns: @true if new config paths have been added from config.

QStringList resourceDirs (const char *type)
[const]

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.

QString saveLocation (const char *type, const QString& suffix = QString::null, bool create = true)
[const]

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

Parameters:
suffixA 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.
createIf 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.

bool makeDir (const QString& dir, int mode = 0755)
[static]

Recursively create still-missing directories in the given path.

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

Parameters:
dirAbsolute path of the directory to be made.
modeDirectory permissions.

QString kde_default (const char *type)
[static]

Returns: Static default for the specified resource. You should probably be using locate() or locateLocal() instead.

See also: locate(), locateLocal()

QString kfsstnd_prefixes ()