Standard Resources (KDE3 Architecture)

Trinity 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 they see them fit best, TDE 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 TDE separates 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.

Information found here might be outdated!

This page or section has been marked as having outdated and/or no more relevant information. Please regard information in this page with extra caution.
This warning was placed on 2022/04/21. (Reason: Might need to be updated according to docs.)

The types of resources TDE offers are

• apps - applications menu (.desktop files)
• cgi - CGIs to run from khelpcenter
• config - configuration files
• data - where applications store data
• exe - executables installed privatly for use by the desktop environment
• html - HTML documentation
• icon - application icons to appear in the window manager or the panel
• lib - libraries and to be dlopened modules
• locale - translation files for TDELocale
• mime - mime types
• sound - application sounds
• toolbar - toolbar pictures
• wallpaper - wallpapers

TDEStandardDirs

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.

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 TDEStandardDirs::findResource("apps", "Home.desktop") to apply this knowledge.

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

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 their $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 TDEStandardDirs as simple as possible. You have however the possibility to use the full power of TDEStandardDirs without them.

Typical TDE 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 their local .trinity directory:

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

• 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 .trinity directory.

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

• 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 .trinity directory.

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

Initial Author: Stephan Kulow (coolo@kde.org)