This paper will introduce you to the main concepts of the KDE next generation configuration framework and will show you how to efficiently use it in your application.
This tutorial assumes that reader has already developed a KDE application and is familiar with KConfig. Basic understanding of XML and concepts behind DTD's is also required.
In this tutorial the more advanced and optional features of KConfig XT and their descriptions are marked by italic text. If you'll decide to skip them during the first reading, make sure you'll come back to them at some point.
The main idea behind KConfig XT is to make the life of application developers easier while making the administration of large KDE installations more manageable.
The four basic parts of the new framework are:
The structure of the .kcfg file is described by its DTD (kcfg.dtd - available from here (please note that browsers do not display DTD's in a visual form, download the dtd directly and view it like a text file) or the kdecore library). Please go through it before you go any further.
Lets create a simple kcfg file. Please reference the code below as we go through each step.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kcfg SYSTEM "http://www.kde.org/standards/kcfg/1.0/kcfg.dtd">
<kcfg>
<kcfgfile name="kjotsrc"/>
<group name="kjots">
<entry name="SplitterSizes" type="IntList">
<label>How the main window is divided.</label>
</entry>
<entry name="Width" type="Int">
<label>Width of the main window.</label>
<default>600</default>
</entry>
<entry name="Height" type="Int">
<label>Height of the main window.</label>
<default>400</default>
</entry>
<entry name="OpenBooks" type="StringList">
<label>All books that are opened.</label>
</entry>
<entry name="CurrentBook" type="String">
<label>The book currently opened.</label>
</entry>
<entry name="Font" type="Font">
<label>The font used to display the contents of books.</label>
<default code="true">KGlobalSettings::generalFont()</default>
</entry>
</group>
</kcfg>
An entry can optionally have a default value which is used as default when the value isn't specified in any config file. Default values are interpreted as literal constant values. If a default value needs to be computed or if it needs to be obtained from a function call, the <default> tag should contain the code="true" attribute. The contents of the <default> tag is then considered to be a C++ expression.
Additional code for computing default values can be provided via the <code> tag. The contents of the <code> tag is inserted as-is. A typical use for this is to compute a common default value which can then be referenced by multiple entries that follow.
After creating a .kcfg file create a .kcfgc file which describes the C++ file generation options. The .kcfgc file is a simple ini file with the typical "entry=value" format. To create a simple .kcfgc file follow these steps:
After creating the .kcfg and .kcfgc files the next step is to adjust the Makefile.am to let kconfig_compiler generate the required class at compile time.
Fortunately those changes are trivial and require only two steps:
The first assures that the configuration class is properly generated the second that the .kcfg is actually being installed and can be used by tools like the KConfigEditor.
After making all of the above changes you're ready to use KConfig XT. The kconfig_compiler generated header file will have the name equal to the value you've specified in the kcfgc ClassName attribute plus the ".h" extension. Simply include that file whereever you want to access your configuration options.
The use will depend on whether you have added the "Singleton=true" entry to your kcfgc file.
One the nicest features of the KConfig XT is its seemless integration with the Qt Designer generated dialogs. You can do that by using KConfigDialog. The steps to do that are as follows:
KConfigDialog* dialog = new KConfigDialog( this, "settings", YourAppSettings::self() );assuming that YourAppSettings is the value of the ClassName variable from the kcfgc file and the settings class is a singelton.
Here's an example usage of KConfig XT for the application named Example. With the following example.kcfg file:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kcfg SYSTEM"http://www.kde.org/standards/kcfg/1.0/kcfg.dtd">
<kcfg> <kcfgfile name="examplerc"/>
<group name="network">
<entry name="ServerName" type="String">
<label>Defines the sample server.</label>
</entry>
<entry name="Port" type="Int">
<label>Defines the server port</label>
<default>21</default>
</entry>
</group>
</kcfg>
File=example.kcfg ClassName=ExampleSettings Singleton=true Mutators=true
...
#include <ExampleSettings.h>
...
void ExampleClass::readConfig() {
m_server = ExampleSettings::serverName();
m_port = ExampleSettings::port();
}
void ExampleClass:saveSettings() {
ExampleSettings::setServerName( m_server );
ExampleSettings::setPort( m_port );
ExampleSettings::writeConfig();
}
To add a dialog you need to create a Qt Designer widget with the widget names corresponding to the names of the options they should edit and prefixed with "kcfg_". It could be something along the lines of :
And you can use the dialog with the following code:
//An instance of your dialog could be already created and could be cached,
//in which case you want to display the cached dialog instead of creating
//another one
if ( KConfigDialog::showDialog( "settings" ) )
return;
//KConfigDialog didn't find an instance of this dialog, so lets create it :
KConfigDialog* dialog = new KConfigDialog( this, "settings",
ExampleSettings::self() );
ExampleDesignerWidget* confWdg =
new ExampleDesignerWidget( 0, "Example" );
dialog->addPage( confWdg, i18n("Example"), "example" );
//User edited the configuration - update your local copies of the
//configuration data
connect( dialog, SIGNAL(settingsChanged()),
this, SLOT(updateConfiguration()) );
dialog->show();