7.2. Application Configuration Information

Configuration information for KDE applications is stored in human-readable text files in a standard format. An example is shown in Listing 7.7. Applications generally store user settings, such as the name of a mail server or the number of times to try connecting to a site before giving up and user preferences for things such as UI layout and colors. The files are stored as human-readable text so that users and administrators can read and modify these files with any text editor. These files offer advantages over the binary-format configuration files used on some other systems:

  • You can automate configuration and reconfiguration (from scripts, for example).

  • The files are safer from corruption. Having a few small errors in a file such as the one in Listing 7.7 is unlikely to make it unreadable to a human. The human can correct these errors so that the application can read the file. Small errors in a compact, binary format may destroy information and make the file unusable by the application.

KDE configuration files store information as Key, Value pairs as shown in Listing 7.7 One pair appears per line.

Example 7.7. A Sample KDE Application Configuration File

   2 1: #KDE Config File
   3 2: DefaultHeight=300
   4 3: [Options]
   5 4: BackgroundColor=255,255,255
   6 5: ForegroundColor=100,100,255

The pairs can be grouped to help organize the information for the application or to make the file more readable. Group names appear in brackets alone on a line preceding the group they label (line 3).

The files can also include comments. Comments appear on lines starting with a # (line 1).

KDE configuration files are stored in .kde/share/config in the user's home directory. Each application creates a configuration file called kappnamerc, where kappname is the name of the application. For example, knotes creates knotesrc.

7.2.1. Accessing Configuration Files

Configuration files are read and written with the KConfig class. The default configuration file, kappnamerc, can be accessed with the KConfig object returned by the method KApplication::config(). You typically access this object with kapp->config(). (kapp is a macro defined in kapp.h that returns a pointer to the current KApplication object. A KDE application uses only one KApplication object; therefore, kapp can reliably be used from any source-code file that is part of your application.)

Listings 7.8 and 7.9 show the code for KConfigDemo, a widget that demonstrates the use of KConfig.

Example 7.8. kconfigdemo.h: Class Declaration for KConfigDemo, a widget that demonstrates KConfig

   2  1: #ifndef __KCONFIGDEMO_H__
   3  2: #define __KCONFIGDEMO_H__
   4  3:
   5  4: #include <qlineedit.h>
   6  5:
   7  6: /**
   8  7:  * KConfigDemo
   9  8:  * Show how to access KDE configuration files with KConfig.
  10  9:  **/
  11 10: class KConfigDemo : public QLineEdit
  12 11: {
  13 12:  public:
  14 13:   KConfigDemo ();
  15 14:
  16 15:  protected:
  17 16:   void closeEvent (QCloseEvent *qcloseevent);
  18 17:
  19 18: };
  20 19:
  21 20: #endif

KConfigDemo is a line editor widget that saves its text in a configuration file when the user closes the window, and it reloads it the next time the program is run.

KConfigDemo is subclassed from QLineEdit, which does most of the work for you. You just need to add the configuration file access.

Example 7.9. kconfigdemo.cpp: Class Definition for KConfigDemo

   2  1: #include <kapp.h>
   3  2: #include <kconfig.h>
   4  3:
   5  4: #include "kconfigdemo.h"
   6  5:
   7  6: KConfigDemo::KConfigDemo () : QLineEdit (0)
   8  7: {
   9  8:   kapp->config()->setGroup ("LineEditor");
  10  9:   setText (kapp->config()->readEntry ("Text", "Hello"));
  11 10: }
  12 11:
  13 12: void
  14 13: KConfigDemo::closeEvent (QCloseEvent *qcloseevent)
  15 14: {
  16 15:   kapp->config()->setGroup ("LineEditor");
  17 16:   kapp->config()->writeEntry ("Text", text());
  18 17:   kapp->config()->sync();
  19 18:
  20 19:   qcloseevent->accept();
  21 20: }

In the constructor, you look in the group LineEditor (line 8) for the key Text (line 9). (Note: If you had not specified a group with setGroup(), the Key, Value pair would have been written to the default, unnamed group.) readEntry() returns the value found to the right of Text= in the configuration file as a QString. In the event that the key Text does not appear at all—as is the case when the program is run for the first time—readEntry() returns Hello, the value specified as the default (line 9).

You want to save the text when the user closes the window. To do this, reimplement the virtual method closeEvent(). This method is called when a close request is made, but before the window is actually closed. In this method, place the text of the widget (returned by text()) to the configuration file into the group LineEditor. The call on line 17 is very important. This call actually writes the new configuration information to disk.


KConfig caches the information in memory until the method KConfig::sync() is called, so be sure to call it before your application exits or else your settings will be lost.

Finally, call qcloseevent->accept(), which lets Qt know that the widget is willing to grant the user's request and be closed.

Listing 7.10 is for a main() function that you can use to test KConfigDemo. Figure 7.3 shows the program that is created—kconfigdemotest—running.

Example 7.10. main.cpp: A main() Function Suitable for Testing KConfigDemo

   2  1: #include <kapp.h>
   3  2:
   4  3: #include "kconfigdemo.h"
   5  4:
   6  5: int
   7  6: main (int argc, char *argv[])
   8  7: {
   9  8:   KApplication kapplication (argc, argv, "kconfigdemotest");
  10  9:
  11 10:   KConfigDemo *kconfigdemo = new KConfigDemo;
  12 11:
  13 12:   kapplication.setMainWidget (kconfigdemo);
  14 13:
  15 14:   kconfigdemo->show();
  16 15:   return kapplication.exec();
  17 16: } 

KConfig can read and write many types of data, not just strings. For example, in the next section you read and write a QFont. The supported types are listed in the documentation (and header file) for KConfigBase.

Figure 7.3. KConfigDemo saves the text you enter in its configuration file.