class KStandardDirs


Module kdecore
Namespace
Class KStandardDirs
Inherits
Site-independent access to standard KDE directories. Author Stephan Kulow and Sirtaj Singh Kang

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 basically 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:\n

  • apps - Applications menu (.desktop files).
  • cache - Cached information (e.g. favicons, web-pages)
  • cgi - CGIs to run from kdehelp.
  • config - Configuration files.
  • data - Where applications store data.
  • emoticons - Emoticons themes
  • exe - Executables in $prefix/bin. findExe() for a function that takes $PATH into account.
  • html - HTML documentation.
  • icon - Icons, see KIconLoader.
  • kcfg - KConfigXT config files.
  • lib - Libraries.
  • locale - Translation files for KLocale.
  • mime - Mime types defined by KDE-specific .desktop files.
  • module - Module (dynamically loaded library).
  • qtplugins - Qt plugins (dynamically loaded objects for Qt)
  • services - Services.
  • servicetypes - Service types.
  • sound - Application sounds.
  • templates - Templates for the "Create new file" functionality.
  • wallpaper - Wallpapers.
  • tmp - Temporary files (specific for both current host and current user)
  • socket - UNIX Sockets (specific for both current host and current user)
  • xdgconf-menu - Freedesktop.org standard location for menu layout (.menu) files.
  • xdgdata-apps - Freedesktop.org standard location for application desktop files.
  • xdgdata-dirs - Freedesktop.org standard location for menu descriptions (.directory files).
  • xdgdata-mime - Freedesktop.org standard location for MIME type definitions.
  • xdgdata-icon - Freedesktop.org standard location for icons.
  • xdgdata-pixmap - Gnome-compatibility location for pixmaps.
  • 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:

  • KDEDIRS - This may set an additional number of directory prefixes to
  • search for resources. The directories should be separated by ':'. The directories are searched in the order they are specified.
  • 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"
  • KDEROOTHOME - Like KDEHOME, but used for the root user.
  • If KDEROOTHOME is not set it defaults to the .kde directory in the home directory of root, usually "/root/.kde". Note that the setting of $HOME is ignored in this case.

    See also KGlobalSettings

    On The Usage Of 'locate' and 'locateLocal'

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

    1) 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:

    // Code example
    myFile = KStandardDirs.locate("appdata", "groups.lst");
    myData = myReadGroups(myFile); // myFile may be null
    

    2) A resource file is read and written. If the user has no local version of the file the system default is used. The resource file is always written to the users local .kde directory.

    // Code example
    myFile = KStandardDirs.locate("appdata", "groups.lst")
    myData = myReadGroups(myFile);
    ...
    doSomething(myData);
    ...
    myFile = KStandardDirs.locateLocal("appdata", "groups.lst");
    myWriteGroups(myFile, myData);
    

    3) A resource file is read and written. No system default is used if the user has no local version of the file. The resource file is always written to the users local .kde directory.

    // Code example
    myFile = KStandardDirs.locateLocal("appdata", "groups.lst");
    myData = myReadGroups(myFile);
    ...
    doSomething(myData);
    ...
    myFile = KStandardDirs.locateLocal("appdata", "groups.lst");
    myWriteGroups(myFile, myData);
    


    enums

    enum details

    methods