Overview

KDE offers several ways to access the files that your application
installed on your user's hard disc while making it transparent
to you where the data really are. To allow the user (or adminstrator
in most cases) to move files where he sees them fit best, KDE offers
a list of different resource types for which a different search path
is assigned to. You may have heard of the environment variable PATH
to lookup executables or MANPATH for looking up man pages. You wouldn't
expect man to lookup man pages in PATH.

Similiar to that concept KDE seperates search paths for different
things to make it simpler to add paths for a specific resource without
making a lookup for another resource unnecessary slower and without
requiring you to put everything into one directory.

For all of them exist also Makefile aliases that configures created by the development
tools provided for KDE (e.g. kdevelop) will know about.

KStandardDirs

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

For this it encapsulates all informations from the application
and applications always refer to a file with a resource type
(e.g. apps) and a filename (e.g. Home.desktop). In an ideal world
the application would make no assumption where this file is and
leaves it up to KStandardDirs::findResource("apps", "Home.desktop")
to apply this knowledge.

The main idea behind KStandardDirs is that there are several
toplevel prefixes where files are below. One of this prefixes is
the one where the user installed kdelibs into, one where the
application has been installed to 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 toolbar icons that is share/toolbar and
share/apps/<appname>/pics.

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 as
example for icons.

On the usage of locate and locateLocal

locate and locateLocal are both convenient functions that make the use of
KStandardDirs as simple as possible. You have however the possibility to
use the full power of KStandardDirs without them.

Typical KDE applications use resource files in one out of three ways:

A resource file is read but is never written. A system default is supplied but the user can override this default in his local .kde directory: