This paper will introduce you to the main concepts of the KDE next generation

+

This paper will introduce you to the main concepts of the KconfigXT

configuration framework and will show you how to efficiently use it in your

configuration framework and will show you how to efficiently use it in your

application.

application.

Line 9:

Line 9:

is familiar with KConfig. Basic understanding of XML and concepts behind DTD's

is familiar with KConfig. Basic understanding of XML and concepts behind DTD's

is also required.

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

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.

easier while making the administration of large KDE installations more manageable.

Line 22:

Line 18:

* An ini like file which provides the code generation options (the {{path|.kcfgc}} file)

* An ini like file which provides the code generation options (the {{path|.kcfgc}} file)

* kconfig_compiler - which generates C++ source code from {{path|.kcfg}} and {{path|.kcfgs}} files. The generated class is based on KConfigSkeleton and provides an API for the application to access its configuration data.

* kconfig_compiler - which generates C++ source code from {{path|.kcfg}} and {{path|.kcfgs}} files. The generated class is based on KConfigSkeleton and provides an API for the application to access its configuration data.

+

+

{{note|In this tutorial the 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. }}

Contents

Using KConfig XT

This paper will introduce you to the main concepts of the KconfigXT
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.

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:

KConfigSkeleton - a class in the libkdecore library which grants a more flexible access to the configuration options,

An ini like file which provides the code generation options (the .kcfgc file)

kconfig_compiler - which generates C++ source code from .kcfg and .kcfgs files. The generated class is based on KConfigSkeleton and provides an API for the application to access its configuration data.

Note

In this tutorial the 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.

.kcfg DTD Structure

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.

Use your favorite code editor to open a your_application_name .kcfg file (of course replacing your_application_name with the name of the application you want to convert to KConfig XT).

Start that file by opening the <kcfgfile> tag which contains the "name" attribute with the value corresponding to the actual KConfig file which it describes. (The actual KConfig file are the rc files).

Add the optional <include> tags which may contain C++ header files that are needed to compile the code required to compute the default values.

The remaining entries in the XML file are grouped by the tag <group> which describes the corresponding groups in the configuration file.

The individual entries must have at least a name or a key. The name is used to create accessor and modifier functions. It's also used as the key in the config file. If <key> is given, but not <name>, the name is constructed by removing all spaces from the <key> contents.

Always add a label or a whatsthis tags to your application in which you describe the configuration options. The label tag is used for short descriptions of the entry, while whatsthis contains more verbose documentation. It's important for tools like KConfigEditor which can be used by systems administrators to setup machines over on the network.

An entry must also have a type. The list of allowable types is specified in the DTD and loosely follows the list of types supported by the QVariant with exception of the clearly binary types (e.g. Pixmap, Image...) which are not supported. Besides those basic type the following special types are supported and include:

Path - This is a string that is specially treated as a file-path. In particular paths in the home directory are prefixed with $HOME when being stored in the configuration file.

Enum - This indicates an enumeration. The possible enum values should be provided via the <choices> tag. Enum values are accessed as integers by the application but stored as string in the configuration file. This makes it possible to add more values at a later date without breaking compatibility.

IntList - This indicates a list of integers. This information is provided to the application as QValueList<int>. Useful for storing QSplitter geometries.

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.

.kcfgc files

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:

Open a new file in your favorite text editor.

Start it with the "File=your_application_name.kcfg" entry which specifies where the configuration options for your application are stored.

Add the "ClassName=YourConfigClassName" entry which specifies the name of the class that will be generated from the .kcfg file. Remember that the generated class will be derived from KConfigSkeleton. PLease make sure that YourConfigClassName is not a class name already used in your application. Save this file under yourconfigclassname.kcfgc. This will ensure the generation of the yourconfigclassname.{h,cpp} files where your configuration class will reside.

NameSpace - specifies the namespace in which the generated config class should reside,

Inherits - if you need the generated class to inherit your custom class,

Singleton - if the configuration class should be a singleton,

MemberVariables - specifies the access to the member variables, default is private,

ItemAccessors - relates to the above item, if member variables are public then it might make little sense to generate accessors. By default they are generated,

Mutators - similar to the above one, but applies to the mutator methods,

GlobalEnums - specifies whether the enums should be class wide of whether they should be always explicitly prefixed with their type name,

Adjusting the CMakeLists.txt file

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. Fortunately doing this is trivial and requires only one step, adding this line to the CMakeLists.txt file example:

kde4_add_kcfg_files(<project name>_SRCS .kcfgc)

This assures that the configuration class is properly generated and that the .kcfg is installed so it can be used by tools like
the KConfigEditor.

Use and Dialogs

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:

Create the KConfigDialog and pass the instance of your configuration data as one of the arguments. The construct would look like the following example:

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: