class KStandardDirs |
|
Site-independent access to standard KDE directories.
Author Stephan Kulow 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
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 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); |
|
KStandardDirs' constructor. It just initializes the caches. |
|
|
Reads customized entries out of the given config object and add
them via addResourceDirs().
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. |
|
Adds another search dir to front of the fsstnd list.
dir - The directory to append relative paths to. |
|
Adds absolute path at the beginning 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. type - Specifies a short descriptive string to access files of this type. absdir - Points to directory where to look for this specific type. Non-existent directories may be saved but pruned. priority - if true, the directory is added before any other, otherwise after Returns true if successful, false otherwise. |
|
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 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", "data" ,"app/pics"); type - Specifies a short descriptive string to access files of this type. relativename - Specifies a directory relative to the root of the KFSSTND. priority - if true, the directory is added before any other, otherwise after Returns true if successful, false otherwise. Deprecated |
|
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 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", "data", "app/pics"); type - Specifies a short descriptive string to access files of this type. basetype - Specifies an already known type, or 0 if none relativename - Specifies a directory relative to the basetype priority - if true, the directory is added before any other, otherwise after Returns true if successful, false otherwise. |
|
Internal - just to avoid unwanted overload |
|
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-"
dir - The directory to append relative paths to. |
|
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-"
dir - The directory to append relative paths to. |
|
This function will return a list of all the types that KStandardDirs
supports.
Returns All types that KDE supports |
|
Returns a number that identifies this version of the resource.
When a change is made to the resource this number will change.
type - The type of the wanted resource filename - A relative filename of the resource. options - If the flags includes Recursive, all resources are taken into account otherwise only the one returned by findResource(). Returns A number identifying the current version of the resource. |
|
Check, if a file may be accessed in a given mode.
This is a wrapper around the access() system call.
checkAccess() calls access() with the given parameters.
If this is OK, checkAccess() returns true. If not, and W_OK
is part of mode, it is checked if there is write access to
the directory. If yes, checkAccess() returns true.
In all other cases checkAccess() returns false.
Other than access() this function EXPLICITLY ignores non-existent files if checking for write access. pathname - The full path of the file you want to test mode - The access mode, as in the access() system call. Returns Whether the access is allowed, true = Access allowed |
|
Checks for existence and accessability of a file or directory.
Faster than creating a QFileInfo first.
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, false otherwise |
|
Finds all occurrences of an executable in the system path.
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. options - if the flags passed include IgnoreExecBit the path returned may not have the executable bit set. Returns The number of executables found, 0 if none were found. See also findExe() |
|
Tries to find all resources with the specified type.
The function will look into all specified directories and return all filenames in these directories. 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() if you do not want a filter. options - if the flags passed include Recursive, subdirectories will also be search; if NoDuplicates is passed then only entries with unique filenames will be returned eliminating duplicates. Returns List of all the files whose filename matches the specified filter. |
|
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. 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() if you do not want a filter. options - if the flags passed include Recursive, subdirectories will also be search; if NoDuplicates is passed then only entries with unique filenames will be returned eliminating duplicates. 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. |
|
Tries to find all directories whose names consist of the
specified type and a relative path. So would
findDirs("apps", "Settings") return
Note that it appends / to the end of the directories, so you can use this right away as directory names. 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. |
|
Finds the executable in the system path.
A valid executable must be a file and have its executable bit set. appname - The name of the executable file for which to search. if this contains a path separator, it will be resolved according to the current working directory (shell-like behaviour). pathstr - The path which will be searched. If this is null (default), the $PATH environment variable will be searched. options - if the flags passed include IgnoreExecBit the path returned may not have the executable bit set. Returns The path of the executable. If it was not found, it will return QString(). See also findAllExe() |
|
Tries to find a resource in the following order:
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) 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() if not found. |
|
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/) 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() if the type of resource specified is unknown or the resource cannot be found. |
|
Returns the path where type was installed to by kdelibs. This is an absolute path and only one out of many search paths |
|
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. type - The type of the resource to check relPath - A relative path in the resource. Returns True if the resource is restricted. |
|
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.
Returns Static default for the specified resource. You should probably be using locate() or locateLocal() instead. See also locate() See also locateLocal() |
|
Internal (for use by sycoca only) |
|
Internal (for use by sycoca only) |
|
Internal (for use by sycoca only) |
|
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 |
|
Returns $XDG_CONFIG_HOME See also http://www.freedesktop.org/standards/basedir/draft/basedir-spec/basedir-spec.html |
|
Returns $XDG_DATA_HOME See also http://www.freedesktop.org/standards/basedir/draft/basedir-spec/basedir-spec.html |
|
This function is just for convenience. It simply calls
instance->dirs()->\link KStandardDirs.findResource() findResource\endlink(type, filename).
type - The type of the wanted resource, see KStandardDirs filename - A relative filename of the resource cData - The KComponentData object Returns A full path to the filename specified in the second argument, or QString() if not found |
|
This function is much like locate. However it returns a
filename suitable for writing to. No check is made if the
specified filename actually exists. Missing directories
are created. If filename is only a directory, without a
specific file, filename must have a trailing slash.
type - The type of the wanted resource, see KStandardDirs filename - A relative filename of the resource cData - The KComponentData object Returns A full path to the filename specified in the second argument, or QString() if not found |
|
This function is much like locate. No check is made if the
specified filename actually exists. Missing directories
are created if createDir is true. If filename is only
a directory, without a specific file, filename must have
a trailing slash.
type - The type of the wanted resource, see KStandardDirs filename - A relative filename of the resource createDir - If true, missing directories are created, if false, no directory is created cData - The KComponentData object Returns A full path to the filename specified in the second argument, or QString() if not found |
|
Recursively creates still-missing directories in the given path.
The resulting permissions will depend on the current umask setting. permission = mode & ~umask. dir - Absolute path of the directory to be made. mode - Directory permissions. Returns true if successful, false otherwise |
|
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. |
|
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. |
|
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. 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. |
|
This function is used internally by almost all other function as
it serves and fills the directories cache.
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. |
|
Finds a location to save files into for the given type
in the user's home directory.
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() if the resource type is unknown. |
|
Returns a QStringList list of pathnames in the system path.
pstr - The path which will be searched. If this is null (default), the $PATH environment variable will be searched. Returns a QStringList list of pathnames in the system path. |
NoSearchOptions | - 0 | - | ||
Recursive | - 1 | - | ||
NoDuplicates | - 2 | - | ||
IgnoreExecBit | - 4 | - |