org.kde.koala

Class KStandardDirs

public class KStandardDirs extends Object implements QtSupport

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:
  • 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.
  • exe - Executables in $prefix/bin. findExe() for a function that takes $PATH into account.
  • html - HTML documentation.
  • icon - Icons, see KIconLoader.
  • lib - Libraries.
  • locale - Translation files for KLocale.
  • mime - Mime types.
  • module - Module (dynamically loaded library).
  • qtplugins - Qt plugins (dynamically loaded objects for Qt)
  • services - Services.
  • servicetypes - Service types.
  • scripts - Application scripting additions.
  • sound - Application sounds.
  • templates - Templates
  • wallpaper - Wallpapers.
  • tmp - Temporary files (specific for both current host and current user)
  • socket - UNIX Sockets (specific for both current host and current user)
  • emoticons - Emoticons themes (Since KDE 3.4)
  • 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.
  • 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"
  • 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.
  • Author: Stephan Kulow and Sirtaj Singh Kang

    See Also: KGlobalSettings

    UNKNOWN: Site-independent access to standard KDE directories.

    Constructor Summary
    protected KStandardDirs(Class dummy)
    KStandardDirs()
    KStandardDirs' constructor.
    Method Summary
    booleanaddCustomized(KConfig config)
    Reads customized entries out of the given config object and add them via addResourceDirs().
    voidaddKDEDefaults()
    This function adds the defaults that are used by the current KDE version.
    voidaddPrefix(String dir)
    Adds another search dir to front of the fsstnd list.
    booleanaddResourceDir(String type, String 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).
    booleanaddResourceType(String type, String relativename)
    Adds suffixes for types.
    voidaddXdgConfigPrefix(String dir)
    Adds another search dir to front of the XDG_CONFIG_XXX list of prefixes.
    voidaddXdgDataPrefix(String dir)
    Adds another search dir to front of the XDG_DATA_XXX list of prefixes.
    ArrayListallTypes()
    This function will return a list of all the types that KStandardDirs supports.
    intcalcResourceHash(String type, String filename, boolean deep)
    Returns a number that identifies this version of the resource.
    voiddispose()
    Delete the wrapped C++ instance ahead of finalize()
    static booleanexists(String fullPath)
    Checks for existence and accessability of a file or directory.
    protected voidfinalize()
    Deletes the wrapped C++ instance
    static intfindAllExe(String[] list, String appname, String pathstr, boolean ignoreExecBit)
    Finds all occurrences of an executable in the system path.
    static intfindAllExe(String[] list, String appname, String pathstr)
    static intfindAllExe(String[] list, String appname)
    ArrayListfindAllResources(String type, String filter, boolean recursive, boolean unique)
    Tries to find all resources with the specified type.
    ArrayListfindAllResources(String type, String filter, boolean recursive)
    ArrayListfindAllResources(String type, String filter)
    ArrayListfindAllResources(String type)
    ArrayListfindAllResources(String type, String filter, boolean recursive, boolean unique, String[] relPaths)
    Tries to find all resources with the specified type.
    ArrayListfindDirs(String type, String reldir)
    Tries to find all directories whose names consist of the specified type and a relative path.
    static StringfindExe(String appname, String pathstr, boolean ignoreExecBit)
    Finds the executable in the system path.
    static StringfindExe(String appname, String pathstr)
    static StringfindExe(String appname)
    StringfindResource(String type, String filename)
    Tries to find a resource in the following order:
  • All PREFIX/\ paths (most recent first).
  • StringfindResourceDir(String type, String filename)
    Tries to find the directory the file is in.
    booleanisDisposed()
    Has the wrapped C++ instance been deleted?
    booleanisRestrictedResource(String type, String relPath)
    Checks whether a resource is restricted as part of the KIOSK framework.
    booleanisRestrictedResource(String type)
    static Stringkde_default(String type)
    This returns a default relative path for the standard KDE resource types.
    static Stringkfsstnd_defaultbindir()
    Returns the default bin directory in which KDE executables are stored.
    static Stringkfsstnd_defaultprefix()
    Returns the default toplevel directory where KDE is installed.
    Stringkfsstnd_prefixes()
    Stringkfsstnd_xdg_conf_prefixes()
    Stringkfsstnd_xdg_data_prefixes()
    Stringlocalkdedir()
    Returns the toplevel directory in which KStandardDirs will store things.
    Stringlocalxdgconfdir()
    Stringlocalxdgdatadir()
    static booleanmakeDir(String dir, int mode)
    Recursively creates still-missing directories in the given path.
    static booleanmakeDir(String dir)
    static StringrealFilePath(String filename)
    Expands all symbolic links and resolves references to '/./', '/../' and extra '/' characters in filename and returns the canonicalized absolute pathname.
    static StringrealPath(String dirname)
    Expands all symbolic links and resolves references to '/./', '/../' and extra '/' characters in dirname and returns the canonicalized absolute pathname.
    StringrelativeLocation(String type, String absPath)
    Converts an absolute path to a path relative to a certain resource.
    ArrayListresourceDirs(String type)
    This function is used internally by almost all other function as it serves and fills the directories cache.
    StringsaveLocation(String type, String suffix, boolean create)
    Finds a location to save files into for the given type in the user's home directory.
    StringsaveLocation(String type, String suffix)
    StringsaveLocation(String type)
    static ArrayListsystemPaths(String pstr)
    Returns an ArrayList list of pathnames in the system path.
    static ArrayListsystemPaths()

    Constructor Detail

    KStandardDirs

    protected KStandardDirs(Class dummy)

    KStandardDirs

    public KStandardDirs()
    KStandardDirs' constructor. It just initializes the caches.

    UNKNOWN: KStandardDirs' constructor.

    Method Detail

    addCustomized

    public boolean 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.

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

    addKDEDefaults

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

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

    addPrefix

    public void addPrefix(String 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.

    UNKNOWN: Adds another search dir to front of the fsstnd list.

    addResourceDir

    public boolean addResourceDir(String type, String 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.

    UNKNOWN: 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).

    addResourceType

    public boolean addResourceType(String type, String 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.

    UNKNOWN: Adds suffixes for types.

    addXdgConfigPrefix

    public void addXdgConfigPrefix(String dir)
    Adds another search dir to front of the XDG_CONFIG_XXX list of prefixes. This prefix is only used for resources that start with "xdgconf-"

    Parameters: dir The directory to append relative paths to.

    UNKNOWN: Adds another search dir to front of the XDG_CONFIG_XXX list of prefixes.

    addXdgDataPrefix

    public void addXdgDataPrefix(String dir)
    Adds another search dir to front of the XDG_DATA_XXX list of prefixes. This prefix is only used for resources that start with "xdgdata-"

    Parameters: dir The directory to append relative paths to.

    UNKNOWN: Adds another search dir to front of the XDG_DATA_XXX list of prefixes.

    allTypes

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

    Returns: All types that KDE supports

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

    calcResourceHash

    public int calcResourceHash(String type, String filename, boolean deep)
    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.

    UNKNOWN: Returns a number that identifies this version of the resource.

    dispose

    public void dispose()
    Delete the wrapped C++ instance ahead of finalize()

    exists

    public static boolean exists(String fullPath)
    Checks for existence and accessability of a file or directory. Faster than creating a QFileInfo first.

    Parameters: fullPath the path to check. IMPORTANT: must end with a slash if expected to be a directory (and no slash for a file, obviously).

    Returns: true if the directory exists

    UNKNOWN: Checks for existence and accessability of a file or directory.

    finalize

    protected void finalize()
    Deletes the wrapped C++ instance

    findAllExe

    public static int findAllExe(String[] list, String appname, String pathstr, boolean ignoreExecBit)
    Finds all occurrences 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: KStandardDirs

    UNKNOWN: Finds all occurrences of an executable in the system path.

    findAllExe

    public static int findAllExe(String[] list, String appname, String pathstr)

    findAllExe

    public static int findAllExe(String[] list, String appname)

    findAllResources

    public ArrayList findAllResources(String type, String filter, boolean recursive, boolean unique)
    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 null if you do not want a filter. recursive Specifies if the function should decend into subdirectories. unique If specified, only return items which have unique suffixes - suppressing duplicated filenames.

    Returns: List of all the files whose filename matches the specified filter.

    UNKNOWN: Tries to find all resources with the specified type.

    findAllResources

    public ArrayList findAllResources(String type, String filter, boolean recursive)

    findAllResources

    public ArrayList findAllResources(String type, String filter)

    findAllResources

    public ArrayList findAllResources(String type)

    findAllResources

    public ArrayList findAllResources(String type, String filter, boolean recursive, boolean unique, String[] relPaths)
    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 null if you do not want a filter. recursive Specifies if the function should decend into subdirectories. unique If specified, only return items which have unique suffixes. relPaths The list to store the relative paths into These can be used later to .locate() the file

    Returns: List of all the files whose filename matches the specified filter.

    UNKNOWN: Tries to find all resources with the specified type.

    findDirs

    public ArrayList findDirs(String type, String reldir)
    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.

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

    findExe

    public static String findExe(String appname, String pathstr, boolean ignoreExecBit)
    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 null.

    See Also: KStandardDirs

    UNKNOWN: Finds the executable in the system path.

    findExe

    public static String findExe(String appname, String pathstr)

    findExe

    public static String findExe(String appname)

    findResource

    public String findResource(String type, String filename)
    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 null if not found.

    UNKNOWN: Tries to find a resource in the following order:

    findResourceDir

    public String findResourceDir(String type, String filename)
    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 null if the type of resource specified is unknown or the resource cannot be found.

    UNKNOWN: Tries to find the directory the file is in.

    isDisposed

    public boolean isDisposed()
    Has the wrapped C++ instance been deleted?

    isRestrictedResource

    public boolean isRestrictedResource(String type, String relPath)
    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.

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

    isRestrictedResource

    public boolean isRestrictedResource(String type)

    kde_default

    public static String kde_default(String type)
    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: KStandardDirs KStandardDirs

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

    kfsstnd_defaultbindir

    public static String kfsstnd_defaultbindir()
    Returns the default bin directory in which KDE executables are stored.

    UNKNOWN:

    kfsstnd_defaultprefix

    public static String kfsstnd_defaultprefix()
    Returns the default toplevel directory where KDE is installed.

    UNKNOWN:

    kfsstnd_prefixes

    public String kfsstnd_prefixes()

    UNKNOWN:

    kfsstnd_xdg_conf_prefixes

    public String kfsstnd_xdg_conf_prefixes()

    UNKNOWN:

    kfsstnd_xdg_data_prefixes

    public String kfsstnd_xdg_data_prefixes()

    UNKNOWN:

    localkdedir

    public String localkdedir()
    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

    UNKNOWN: Returns the toplevel directory in which KStandardDirs will store things.

    localxdgconfdir

    public String localxdgconfdir()

    Returns: $XDG_CONFIG_HOME See also http://www.freedesktop.org/standards/basedir/draft/basedir-spec/basedir-spec.html

    UNKNOWN:

    localxdgdatadir

    public String localxdgdatadir()

    Returns: $XDG_DATA_HOME See also http://www.freedesktop.org/standards/basedir/draft/basedir-spec/basedir-spec.html

    UNKNOWN:

    makeDir

    public static boolean makeDir(String dir, int mode)
    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

    UNKNOWN: Recursively creates still-missing directories in the given path.

    makeDir

    public static boolean makeDir(String dir)

    realFilePath

    public static String realFilePath(String filename)
    Expands all symbolic links and resolves references to '/./', '/../' and extra '/' characters in filename and returns the canonicalized absolute pathname. The resulting path will have no symbolic link, '/./' or '/../' components.

    UNKNOWN: Expands all symbolic links and resolves references to '/.

    realPath

    public static String realPath(String dirname)
    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.

    UNKNOWN: Expands all symbolic links and resolves references to '/.

    relativeLocation

    public String relativeLocation(String type, String 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.

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

    resourceDirs

    public ArrayList resourceDirs(String type)
    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.

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

    saveLocation

    public String saveLocation(String type, String suffix, boolean create)
    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 null if the resource type is unknown.

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

    saveLocation

    public String saveLocation(String type, String suffix)

    saveLocation

    public String saveLocation(String type)

    systemPaths

    public static ArrayList systemPaths(String pstr)
    Returns an ArrayList list of pathnames in the system path.

    Parameters: pstr The path which will be searched. If this is null (default), the $PATH environment variable will be searched.

    Returns: an ArrayList list of pathnames in the system path.

    UNKNOWN: Returns an ArrayList list of pathnames in the system path.

    systemPaths

    public static ArrayList systemPaths()