Das K Desktop Environment

14.2. KApplication Methods

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 )
The methods are generally used with the 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();
This example stores the path of the KDE sounddirectory under a 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:

  1. $KDEDIR,

  2. $KDEPATH,

  3. "&[;KDE Setup&];:Path=" entry in a config file.

If the file is not found, the QString method isEmpty() will return True