Next Previous Table of Contents
As the last chapter covered the KDE File System Standard, this chapter deals with what you have to do to use the file system. A KDE project uses the file system at least for installation routines; therefore we will discuss setting installation properties for your project files. Your application may make use of files that are installed afterwards, where it is important to know how to get the relative pathname by the standard. This enables your application to work wherever the KDE file system may be and prevents hard-coding any file information.
After the installation of your project by end-users, your application may require file information during runtime. During the
development process, you will experience at least one error which is caused when running your application within the KDevelop IDE and
requiring the application manual by "Help"-"Contents" or pressing the F1 key. This will result in a message box, saying that the
index.html file could not be found- if you haven't installed your application on your local KDE file system. Your application asks
KDEHelp to open your index page with detecting the installation directory first through KApplication's methods to access the file
system, therefore, we will have a look at what KApplication offers and make some example usage. Also other classes of
KDE-Core make use of the KDE File System like KIconLoader and KLocale, which will be reviewed afterwards.
The KApplication class offers the following methods to access the KDE File System:
void invokeHTMLHelp ( QString aFilename, QString aTopic ) const
static const QString& kde_htmldir ()
static const QString& kde_appsdir ()
static const QString& kde_icondir ()
static const QString& kde_datadir ()
static const QString& kde_localedir ()
static const QString& kde_cgidir ()
static const QString& kde_sounddir ()
static const QString& kde_toolbardir ()
static const QString& kde_wallpaperdir ()
static const QString& kde_bindir ()
static const QString& kde_configdir ()
static const QString& kde_mimedir ()
static QString localkdedir ()
static QString localconfigdir ()
static QString findFile ( const char *file )
KApplication object of your application, where KApplication offers the macro
kapp to receive the pointer:
#define kapp KApplication::getKApplication()
Therefore, the methods are generally used like this:
QString sounddir=kapp->kde_sounddir();
QString, where you would append e.g. the sound filename. Then you
can process this information and play a sound file that is located there. You should always test for the existence of a file by using
QFileInfo's exists() method.
Within these methods,
void invokeHTMLHelp( QString aFilename, QString aTopic ) const [public]
takes a special position to invoke the KDE help. Generally, you should use it everywhere a user needs to access information, e.g. when
he is presented a modal dialog. The F1 key will not work to invoke the help contents, also the user should be presented the according
help page. To make a good use of it, add a "Help" button to your dialog and create a slot that is used to connect on signal
pressed(). In this method, use invokeHTMLHelp() with the according page and subject; in case your application's documentation
isn't written completely yet, leave this open to complete it after the documentation is in sync with the application.
The documentation of KApplication says:
Invoke the kdehelp HTML help viewer.
Parameters: aTopic This allows context-sensitive help. Its value will be appended to the filename, prefixed with a "#" (hash) character.
aFilename: The filename that is to be loaded. Its location is computed automatically according to the KFSSTND. If aFilename is empty, the logical appname with .html appended to it is used.
The methods of KApplication will retrieve the following path's.
kde_htmldir() kdedir()/share/doc/HTML Returns the directory where KDE stores
its HTML documentation
kde_appsdir() kdedir()/share/applnk Returns the directory where KDE applications
store their .kdelnk file
kde_icondir() kdedir()/share/icons Returns the directory where KDE icons are stored
kde_datadir() kdedir()/share/apps Returns the directory where KDE applications
store their specific data
kde_localedir() kdedir()/share/locale Returns the directory where locale-specific
information (like translated on-screen messages) are stored
kde_cgidir() kdedir()/cgi-bin Returns the directory where cgi scripts are stored
kde_sounddir() kdedir()/share/sounds Returns the directory where sound data are stored.
This directory is for KDE specific sounds.
Sound data of Applications should go
into kde_datadir()
kde_toolbardir() kdedir()/share/toolbar Returns the directory where toolbar icons are stored
kde_wallpaperdir() kdedir()/share/wallpapers Returns the directory where KDE wallpaper files are stored
kde_bindir() kdedir()/bin Returns the directory where KDE application binaries are stored
kde_configdir() kdedir()/share/config Returns the directory where config files are stored
kde_mimedir() kdedir()/share/mimelnk Returns the directory where mimetypes are stored
localkdedir() $HOME/.kde Get the local KDE base dir
localconfigdir() $HOME/.kde/share/config Get the local KDE config dir
To search for a specific file, use findFile(const char *file) which will search several path's of the KDE File System:
If the file is not found, the QString method isEmpty() will return True
QPixmap loadIcon ( const QString &name, int w = 0, int h = 0 )
QPixmap reloadIcon ( const QString &name, int w = 0, int h = 0)
QPixmap loadMiniIcon ( const QString &name , int w = 0, int h = 0 )
QPixmap loadApplicationIcon ( const QString &name, int w = 0, int h = 0 )
QPixmap loadApplicationMiniIcon ( const QString &name, int w = 0, int h = 0 )
bool insertDirectory ( int index, const QString &dir_name )
As the above explained where KDE applications should place their files and how to access them at runtime, the following will explain how to set the file properties correctly to ensure the files get installed at the right place. The Makefiles support a set of macros to install your files into the KDE File System and which have to be used for setting the file installation properties.
To set the properties, open your project and select "Project"-"File Properties" which opens the File Properties dialog. The file properties are displayed if you select a filename currently included in the project. First of all, a file has a type property, which can be one of the following:
Further, a file is included in the project, if "Include in Distribution" is checked. This ensures that the file is included in the distribution tarball or package.
If a file has to be installed, you have to enable "Install". This will allow setting the Installation path for the selected file, where the filename is already inserted.
Now, as said above, the Makefile already is capable of a set of macros for the KDE File System Standard. These are used to set the installation path and ensure that the files actually will land in the KDE file system and not somewhere else. Macros that can be used, have to be embraced in round brackets and are marked with the dollar sign in front of the macro. When configure builds the Makefiles on the end-user's system, it will determine values for these macros that match the real directory name and will expand the Makefile.am macro towards the actual destination.
When looking a standard KDE application project, you will see on the file property of your index.html file that it already uses a
macro to determine where it should go:
$(kde_htmldir)/en/kscribble/index.html
This says, that make should install the file index.html in the kde-html directory, subdirectory en for English, the application subdirectory and the filename. You could as well use another filename if you like to rename the file on the installation destination.
For the destination of your binary you currently have to edit the project's Makefile.am if your destination should be different form the "Applications" section of kpanel:
APPSDIR = $(kde_appsdir)/Applications
Possible values are (as the KDE-File System Standard says):
Setting no directory will end your applnk directly in kpanel's root.
The following list contains the macros that can be used in the installation setup for files:
kde_htmldir Where your docs should go to. (contains lang subdirs)
kde_appsdir Where your application file (.kdelnk) should go to.
kde_icondir Where your icon should go to.
kde_minidir Where your mini icon should go to.
kde_datadir Where you install application data. (Use a subdir)
kde_locale Where translation files should go to.(contains lang subdirs)
kde_cgidir Where cgi-bin executables should go to.
kde_confdir Where config files should go to.
kde_mimedir Where mimetypes should go to.
kde_toolbardir Where general toolbar icons should go to.
kde_wallpaperdir Where general wallpapers should go to.
Use these macros in conjunction with the according necessary subdirectories and the filename for setting the installation properties. By default, the currently created HTML documentation files, the kdelnk file, Icon, Miniicon and the translation files (also newly create ones) are already set up for their destination; therefore you don't have to make any changes for your default installation routine that has been set up by the application wizard of KDevelop.
Another issue in creating projects often appears to the programmer if he has or wants to include additional data that have to be installed with the project. You already know where to install it, but what about organizing it in the source tree ?
A good advice here may be to collect all data in directories that more or less match the KDE File System Standard, e.g. your
application needs additional toolbar icons. Creating these icons in the main project directory is potentially not a good idea as they
will be difficult to locate in the real file viewer and a removal will result in much work for each icon. Therefore, create your icon
with "File"- "New" and choose a subdirectory toolbar; if it doesn't exist, it can be easily created with the "select directory"
dialog. Existing icons can be copied and included into the project with "Project"-"Add existing file(s)", where you have to choose the
files and the destination. When selecting the destination directory, you can create the toolbar subdirectory first within the
selection dialog. After being finished, press OK and the files will be copied as well as included in the project.
As an example, a toolbar icon should go to the following:
$(kde_datadir)/<appname>/toolbar/<youricon>.xpm
Pictures or additional icons that are not used as toolbar icons should go to a subdirectory pics instead of toolbar.
kdelnk File
The <appname>.kdelnk file currently included in your project will install itself in KDE's kpanel structure. You should think it is already created and complete, therefore shouldn't require any further notification. Despite of KDevelop's advanced qualities to help you with creating, programming and designing applications, it cannot determine the exact purpose of your application- and that is the information you have to add to the kdelnk file. As this is a text file, select it from the RFV or the LFV; it will be opened in the Header/Resource window.
The sample kdelnk file would look like this:
# KDE Config File
[KDE Desktop Entry]
Type=Application
Exec=kscribble
Icon=kscribble.xpm
DocPath=kscribble/index.html
Comment=
Comment[de]=
Terminal=0
Name=kscribble
Name[de]=kscribble
This already contains the basic configuration for the application specific data such as the icon, binary name, application name etc. You see that the section Comment is still empty. There you have to insert the Quick-Tip that will be displayed when the mouse cursor moves over the kdelnk file icon on the desktop or in kpanel. If scribble would be a small drawing program, you would enter e.g.
Comment=A simple drawing program
Each comment line afterwards will contain the same description translated in the language the brackets symbolize. Ask translators to insert a good translation in their native language or include the kdelnk file when asking for translating the application's po file; the same applies to the name of the application set in the Name lines.
for more information about the purpose of the .kdelnk file, especially its use for commandline processing, see The KDE Library Reference Guide
Next Previous Table of Contents