#include <kstandarddirs.h>

Public Member Functions
	TDEStandardDirs ()

virtual	~TDEStandardDirs ()

void	addPrefix (const TQString &dir)

void	addXdgConfigPrefix (const TQString &dir)

void	addXdgDataPrefix (const TQString &dir)

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

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

TQString	findResource (const char *type, const TQString &filename) const

bool	isRestrictedResource (const char *type, const TQString &relPath=TQString::null) const

TQ_UINT32	calcResourceHash (const char *type, const TQString &filename, bool deep) const

TQStringList	findDirs (const char *type, const TQString &reldir) const

TQString	findResourceDir (const char *type, const TQString &filename) const

TQStringList	findAllResources (const char *type, const TQString &filter=TQString::null, bool recursive=false, bool unique=false) const

TQStringList	findAllResources (const char *type, const TQString &filter, bool recursive, bool unique, TQStringList &relPaths) const

void	addKDEDefaults ()

bool	addCustomized (TDEConfig *config)

TQStringList	resourceDirs (const char *type) const

TQStringList	allTypes () const

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

TQString	relativeLocation (const char *type, const TQString &absPath)

TQString	kfsstnd_prefixes ()

TQString	kfsstnd_xdg_conf_prefixes ()

TQString	kfsstnd_xdg_data_prefixes ()

TQString	localtdedir () const

TQString	localxdgdatadir () const

TQString	localxdgconfdir () const

Static Public Member Functions
static TQStringList	systemPaths (const TQString &pstr=TQString::null)

static TQString	findExe (const TQString &appname, const TQString &pathstr=TQString::null, bool ignoreExecBit=false)

static int	findAllExe (TQStringList &list, const TQString &appname, const TQString &pathstr=TQString::null, bool ignoreExecBit=false)

static bool	makeDir (const TQString &dir, int mode=0755)

static TQString	kde_default (const char *type)

static TQString	kfsstnd_defaultprefix ()

static TQString	kfsstnd_defaultbindir ()

static bool	exists (const TQString &fullPath)

static TQString	realPath (const TQString &dirname)

static TQString	realFilePath (const TQString &filename)

Related Functions
(Note that these are not member functions.)
TQString	locate (const char type, const TQString &filename, const TDEInstance instance=TDEGlobal::instance())

TQString	locateLocal (const char type, const TQString &filename, const TDEInstance instance=TDEGlobal::instance())

TQString	locateLocal (const char type, const TQString &filename, bool createDir, const TDEInstance instance=TDEGlobal::instance())

Detailed Description

Site-independent access to standard KDE directories.

Author: Stephan Kulow coolo.nosp@m.@kde.nosp@m..org and Sirtaj Singh Kang taj@k.nosp@m.de.o.nosp@m.rg

This is one of the most central classes in tdelibs 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 TDEStandardDirs::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 TDEStandardDirs is that there are several toplevel prefixes below which the files lie. One of these prefixes is the one where the user installed tdelibs, one is where the application was installed, and one is $HOME/.trinity, 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/tde/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 TDEStandardDirs 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/.trinity directory for, for example, icons.

Standard resources that tdelibs 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 TDEIconLoader.
lib - Libraries.
locale - Translation files for TDELocale.
mime - Mime types.
module - Module (dynamically loaded library).
tqtplugins - TQt plugins (dynamically loaded objects for TQt)
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 TDEApplication 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 TDEApplication instance is called "appname" (as set via TDEApplication's constructor or TDEAboutData, if you use the global TDEStandardDirs object TDEGlobal::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").

TDEStandardDirs supports the following environment variables:

TDEDIRS: 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.
TDEDIR: Used for backwards compatibility. As TDEDIRS but only a single directory may be specified. If TDEDIRS is set TDEDIR is ignored.
TDEHOME: The directory where changes are saved to. This directory is used to search for resources first. If TDEHOME is not specified it defaults to "$HOME/.trinity"
TDEROOTHOME: Like TDEHOME, but used for the root user. If TDEROOTHOME is not set it defaults to the .kde directory in the home directory of root, usually "/root/.trinity". Note that the setting of $HOME is ignored in this case.

See also: TDEGlobalSettings

Definition at line 125 of file kstandarddirs.h.

Constructor & Destructor Documentation

◆ TDEStandardDirs()

TDEStandardDirs::TDEStandardDirs ( )

TDEStandardDirs' constructor.

It just initializes the caches.

Definition at line 108 of file kstandarddirs.cpp.

◆ ~TDEStandardDirs()

TDEStandardDirs::~TDEStandardDirs ( )

virtual

TDEStandardDirs' destructor.

Definition at line 118 of file kstandarddirs.cpp.

Member Function Documentation

◆ addCustomized()

bool TDEStandardDirs::addCustomized ( TDEConfig * 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.

Definition at line 1537 of file kstandarddirs.cpp.

◆ addKDEDefaults()

void TDEStandardDirs::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 TDEGlobal.

Definition at line 1295 of file kstandarddirs.cpp.

◆ addPrefix()

void TDEStandardDirs::addPrefix ( const TQString & dir )

Adds another search dir to front of the fsstnd list.

When compiling tdelibs, the prefix is added to this.
TDEDIRS or TDEDIR is taking into account
Additional dirs may be loaded from kdeglobals.

Parameters

dir	The directory to append relative paths to.

Definition at line 180 of file kstandarddirs.cpp.

◆ addResourceDir()

bool TDEStandardDirs::addResourceDir	(	const char *	type,
		const TQString &	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.

Definition at line 286 of file kstandarddirs.cpp.

◆ addResourceType()

bool TDEStandardDirs::addResourceType	(	const char *	type,
		const TQString &	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 TDEGlobal::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.

Definition at line 255 of file kstandarddirs.cpp.

◆ addXdgConfigPrefix()

void TDEStandardDirs::addXdgConfigPrefix ( const TQString & 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.

Definition at line 200 of file kstandarddirs.cpp.

◆ addXdgDataPrefix()

void TDEStandardDirs::addXdgDataPrefix ( const TQString & 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.

Definition at line 220 of file kstandarddirs.cpp.

◆ allTypes()

TQStringList TDEStandardDirs::allTypes ( ) const

This function will return a list of all the types that TDEStandardDirs supports.

Returns: All types that KDE supports

Definition at line 157 of file kstandarddirs.cpp.

◆ calcResourceHash()

TQ_UINT32 TDEStandardDirs::calcResourceHash	(	const char *	type,
		const TQString &	filename,
		bool	deep
	)		const

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.

Definition at line 352 of file kstandarddirs.cpp.

◆ exists()

bool TDEStandardDirs::exists ( const TQString & fullPath )

static

Checks for existence and accessability of a file or directory.

Faster than creating a TQFileInfo 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

Definition at line 450 of file kstandarddirs.cpp.

◆ findAllExe()

int TDEStandardDirs::findAllExe	(	TQStringList &	list,
		const TQString &	appname,
		const TQString &	pathstr = `TQString::null`,
		bool	ignoreExecBit = `false`
	)

static

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: findExe()

Definition at line 981 of file kstandarddirs.cpp.

◆ findAllResources() [1/2]

TQStringList TDEStandardDirs::findAllResources	(	const char *	type,
		const TQString &	filter,
		bool	recursive,
		bool	unique,
		TQStringList &	relPaths
	)		const

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 TQString::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.

Definition at line 623 of file kstandarddirs.cpp.

◆ findAllResources() [2/2]

TQStringList TDEStandardDirs::findAllResources	(	const char *	type,
		const TQString &	filter = `TQString::null`,
		bool	recursive = `false`,
		bool	unique = `false`
	)		const

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 TQString::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.

Definition at line 679 of file kstandarddirs.cpp.

◆ findDirs()

TQStringList TDEStandardDirs::findDirs	(	const char *	type,
		const TQString &	reldir
	)		const

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/.trinity/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.

Definition at line 378 of file kstandarddirs.cpp.

◆ findExe()

TQString TDEStandardDirs::findExe	(	const TQString &	appname,
		const TQString &	pathstr = `TQString::null`,
		bool	ignoreExecBit = `false`
	)

static

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 TQString::null.

See also: findAllExe()

Definition at line 932 of file kstandarddirs.cpp.

◆ findResource()

TQString TDEStandardDirs::findResource	(	const char *	type,
		const TQString &	filename
	)		const

Tries to find a resource in the following order:

All PREFIX/<relativename> 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 libtdecore.la to findResource("lib", "libtdecore.la"). TDEStandardDirs will then look into the subdir lib of all elements of all prefixes ($TDEDIRS) for a file libtdecore.la and return the path to the first one it finds (e.g. /opt/kde/lib/libtdecore.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 TQString::null if not found.

Definition at line 317 of file kstandarddirs.cpp.

◆ findResourceDir()

TQString TDEStandardDirs::findResourceDir	(	const char *	type,
		const TQString &	filename
	)		const

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", "libtdecore.la") would return the path of the subdir libtdecore.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 TQString::null if the type of resource specified is unknown or the resource cannot be found.

Definition at line 412 of file kstandarddirs.cpp.

◆ isRestrictedResource()

bool TDEStandardDirs::isRestrictedResource	(	const char *	type,
		const TQString &	relPath = `TQString::null`
	)		const

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 $TDEHOME 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.

Since: 3.1

Definition at line 123 of file kstandarddirs.cpp.

◆ kde_default()

TQString TDEStandardDirs::kde_default ( const char * type )

static

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/tde/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: locate(); locateLocal()

Definition at line 1036 of file kstandarddirs.cpp.

◆ localtdedir()

TQString TDEStandardDirs::localtdedir ( ) const

Returns the toplevel directory in which TDEStandardDirs will store things.

Most likely $HOME/.trinity Don't use this function if you can use locateLocal

Returns: the toplevel directory

Definition at line 1669 of file kstandarddirs.cpp.

◆ localxdgconfdir()

TQString TDEStandardDirs::localxdgconfdir ( ) const

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

Definition at line 1681 of file kstandarddirs.cpp.

◆ localxdgdatadir()

TQString TDEStandardDirs::localxdgdatadir ( ) const

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

Definition at line 1675 of file kstandarddirs.cpp.

◆ makeDir()

bool TDEStandardDirs::makeDir	(	const TQString &	dir,
		int	mode = `0755`
	)

static

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

Definition at line 1176 of file kstandarddirs.cpp.

◆ realFilePath()

TQString TDEStandardDirs::realFilePath ( const TQString & filename )

static

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.

Since: 3.4

Definition at line 707 of file kstandarddirs.cpp.

◆ realPath()

TQString TDEStandardDirs::realPath ( const TQString & dirname )

static

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.

Since: 3.1

Definition at line 689 of file kstandarddirs.cpp.

◆ relativeLocation()

TQString TDEStandardDirs::relativeLocation	(	const char *	type,
		const TQString &	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.

Definition at line 1154 of file kstandarddirs.cpp.

◆ resourceDirs()

TQStringList TDEStandardDirs::resourceDirs ( const char * type ) const

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.

Definition at line 795 of file kstandarddirs.cpp.

◆ saveLocation()

TQString TDEStandardDirs::saveLocation	(	const char *	type,
		const TQString &	suffix = `TQString::null`,
		bool	create = `true`
	)		const

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 TQString::null if the resource type is unknown.

Definition at line 1099 of file kstandarddirs.cpp.

◆ systemPaths()

TQStringList TDEStandardDirs::systemPaths ( const TQString & pstr = TQString::null )

static

Returns a TQStringList 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: a TQStringList list of pathnames in the system path.

Definition at line 886 of file kstandarddirs.cpp.

The documentation for this class was generated from the following files:

tdecore

Public Member Functions

Static Public Member Functions

Related Functions

Detailed Description

Constructor & Destructor Documentation

◆ TDEStandardDirs()

◆ ~TDEStandardDirs()

Member Function Documentation

◆ addCustomized()

◆ addKDEDefaults()

◆ addPrefix()

◆ addResourceDir()

◆ addResourceType()

◆ addXdgConfigPrefix()

◆ addXdgDataPrefix()

◆ allTypes()

◆ calcResourceHash()

◆ exists()

◆ findAllExe()

◆ findAllResources() [1/2]

◆ findAllResources() [2/2]

◆ findDirs()

◆ findExe()

◆ findResource()

◆ findResourceDir()

◆ isRestrictedResource()

◆ kde_default()

◆ localtdedir()

◆ localxdgconfdir()

◆ localxdgdatadir()

◆ makeDir()

◆ realFilePath()

◆ realPath()

◆ relativeLocation()

◆ resourceDirs()

◆ saveLocation()

◆ systemPaths()

tdecore

tdecore