| Tutorial Series | KConfig |
| Previous | Introduction to KConfig Introduction to CMake |
| What's Next | None |
| Further Reading | The KDE Configuration Compiler (KDE 4) The KDE Configuration Compiler (KDE 3) |
Original Author: Zack Rusin <zack@kde.org>
This tutorial introduces the main concepts of the KconfigXT configuration framework and shows how to efficiently use it in applications. It assumes that the reader has already developed a KDE application and is familiar with KConfig. A basic understanding of XML and concepts behind XML Schema is also required.
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:
| Note |
|---|
| In this tutorial more advanced and optional features of KConfig XT and their descriptions are marked by italic text. If you decide to skip them during the first reading, be sure to come back to them at some point. |
The structure of the .kcfg file is described by its XML Schema (kcfg.xsd - available from here or from 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.
KDE TechBase <?xml version="1.0" encoding="UTF-8"?>
<kcfg xmlns="http://www.kde.org/standards/kcfg/1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.kde.org/standards/kcfg/1.0
http://www.kde.org/standards/kcfg/1.0/kcfg.xsd" >
<include>kglobalsettings.h</include>
<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>
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:
For details see the description of kconfig_compiler: [1]
After creating the .kcfg and .kcfgc files the next step is to adjust the build to let kconfig_compiler generate the required class at compile time. For in-source builds, doing this is trivial and requires only one step, adding this two lines to the CMakeLists.txt file example (asuming your files are named settings.kcfg and settings.kcfgc):
kde4_add_kcfg_files(<project name>_SRCS settings.kcfgc)
install(FILES settings.kcfg DESTINATION ${KCFG_INSTALL_DIR})
Alternatively, if a .moc file needs to be generated before compiling the generated source code, use
kde4_add_kcfg_files(<project name>_SRCS GENERATE_MOC settings.kcfgc)
install(FILES settings.kcfg DESTINATION ${KCFG_INSTALL_DIR})
This assures that the configuration class is properly generated (kde4_add_kcfg_files) and that the .kcfg is installed so it can be used by tools like the KConfigEditor (install).
Out-of-source builds require one more step.
The problem: In out-of-source builds, the code that is generated by kconfig_compiler is saved in the build tree. So how can we still include the header generated by kconfig_compiler with a simple #include "settings.h"?
The solution: Probably you have yet a line similar to the following line in your CMakeLists.txt:
include_directories(${QT_INCLUDE} ${KDE4_INCLUDES})
Add the variable CMAKE_CURRENT_BINARY_DIR, so that you get something like this:
include_directories(${QT_INCLUDE} ${KDE4_INCLUDES} ${CMAKE_CURRENT_BINARY_DIR})
Notice that you should call include_directories only once in your project. (When you call include_directories in your base source directory, but than call it another time in a subdirectory (added by add_subdirectory), then the second call will be ignored.)
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 name of the .kcfg file but with a ".h" extension. Simply include that file wherever 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 of the nicest features of the KConfig XT is its seamless 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.
While KConfigDialog provide a convenient way of binding KConfig XT based settings with dialogs, some use case require manual binding. A common one is heavy and slow loading KConfigDialog being replaced with lazy loaded containers. Another one is where is when multiple instances KConfigSkeleton based object exist. Finally, this can also be used to load a set of values used outside of a config dialog. Here is a basic example of manual binding:
KConfigDialogManager* manager = new KConfigDialogManager(this, YourAppSettings::self());
connect(this, SIGNAL(okClicked()), manager, SLOT(updateSettings()));
connect(this, SIGNAL(applyClicked()), manager, SLOT(updateSettings()));
connect(this, SIGNAL(cancelClicked()), manager, SLOT(updateWidgets()));
connect(this, SIGNAL(defaultClicked()), manager, SLOT(updateWidgetsDefault()));
connect(manager, SIGNAL(settingsChanged()), this, SLOT(updateButtons()));
connect(manager, SIGNAL(widgetModified()), this, SLOT(updateButtons()));
manager->addWidget(myConfigWidget);
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"?>
<kcfg xmlns="http://www.kde.org/standards/kcfg/1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.kde.org/standards/kcfg/1.0
http://www.kde.org/standards/kcfg/1.0/kcfg.xsd" >
<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>
<min>20</min>
<max>990</max>
</entry>
</group>
</kcfg>
And here's how to actually use the generated class for the given kcfgc file.
File=example.kcfg
ClassName=ExampleSettings
Singleton=true
Mutators=true
The header files wouldn't change, but the cpp files must now contain the following code to access and store the configuration data :
...
#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::self()->writeConfig();
}
self() returns the current instance of the object. You need to call writeConfig() this way, since it's a virtual method.
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();
And that's all it takes. You can have a look at KReversi and KMines code in the kdegames module to see a live example of KConfig XT!
