docs.kde.org
Configuration Files
Prev
Next

Configuration Files

KDE uses a simple text-based file format for all its configuration files. It consists of key-value pairs that are placed in groups. All KDE configuration files use UTF-8 encoding for text outside the ASCII range.

The start of a group is indicated by a group name that is placed in square brackets. All the key-value entries that follow belong to the group. The group ends when either another group starts or when the end of the file is reached. Entries at the top of the file that are not preceded by a group name belong to the default group.

The following example shows a configuration file that consists of two groups. The first group contains the keys LargeCursor and SingleClick, the second group contains the keys Show hidden files and Sort by:

[KDE]
LargeCursor=false
SingleClick=true
[KFileDialog Settings]
Show hidden files=false
Sort by=Name

Entries in a group consist of a key and value separated by an equals sign. The key can contain spaces and may be followed by options placed in square brackets. The part after the equals sign is the value of the entry. Any white space surrounding the equals sign is ignored, as is any trailing white space. Put more concisely, the format is:

entry=value

If a value is supposed to include a space at the begin or end then this can be achieved by using a backslash followed by an “s”.

There are several other backslash codes; here is a complete list:

In the following example the value of the Caption entry starts with two spaces while the Description entry contains three lines of text. Linefeeds in backslash notation are used to separate the different lines.

[Preview Image]
Caption=\s My Caption
Description=This is\na very long\ndescription.

Empty lines in configuration files are ignored, as are lines that start with a hash mark (“#”). The hash mark can be used to add comments to configuration files. It should be noted that when a KDE application updates a configuration file the comments are not preserved.

There can be multiple configuration files with the same name in the share/config sub-directory of the various KDE directory trees. In this case the information of all these configuration files is combined on a key-by-key basis. If the same key within a certain group is defined in more than one place, the key value read from the directory tree with the highest precedence will be used. Configuration files under $KDEHOME always have the highest precedence. If a key in a certain group is defined multiple times in a single file, the value of the last entry is used.

If $HOME/.kde/share/config/foobar contains:

[MyGroup]
Color=red
Shape=circle

and /etc/opt/kde3/share/config/foobar contains

[MyGroup]
Color=blue
Position=10,10

the result will be:

[MyGroup]
Color=red
Shape=circle
Position=10,10

If $HOME/.kde/share/config/foobar contains

[MyGroup]
Color=red
Shape=circle
[MyGroup]
Color=green

and /opt/kde_staff/share/config/foobar contains

[MyGroup]
Color=purple
Position=20,20

and /etc/opt/kde3/share/config/foobar contains

[MyGroup]
Color=blue
Position=10,10

the result will be:

[MyGroup]
Color=green
Shape=circle
Position=20,20

To prevent users being able to override default settings, settings can be marked immutable. Settings can be made immutable individually, per group or per file. An individual entry can be locked down by adding [$i] behind the key, e.g.:

Color[$i]=blue

A group of entries can be locked down by placing [$i] behind the group name, e.g.:

[MyGroup][$i]

To lock down the entire file, start the file with [$i] on a single line, i.e.:

[$i]

If $HOME/.kde/share/config/foobar contains:

[MyGroup]
Color=red
Shape=circle

and /etc/opt/kde3/share/config/foobar contains:

[MyGroup][$i]
Color=blue
Position=10,10

the result will be:

[MyGroup]
Color=blue
Position=10,10

If $HOME/.kde/share/config/foobar contains:

[MyGroup]
Color=red
Shape=circle

and /opt/kde_staff/share/config/foobar contains

[MyGroup]
Color=purple
Shape=rectangle

and /etc/opt/kde3/share/config/foobar contains

[MyGroup][$i]
Color=blue
Position=10,10

the result will be

[MyGroup]
Color=purple
Shape=rectangle
Position=10,10

So-called “Shell Expansion” can be used to provide more dynamic default values. With shell expansion the value of a configuration key can be constructed from the value of an environment variable or from the output of a shell command. To enable shell expansion for a configuration entry, the key must be followed by [$e]. Normally the expanded form is written into the user's configuration file after first use. To prevent that, it is recommend to lock the configuration entry down by using [$ie]. The user can't change it then of course.

In the following example the value for the Host entry is determined by the output of the hostname program. This setting is also locked down to ensure that the value is always determined dynamically.

The value for the Email entry is determined by filling in the values of the $USER and $HOST environment variables. When joe is logged in on joes_host this will result in a value equal to joe@joes_host. The setting is not locked down.

[Mail Settings] 
Host[$ie]=$(hostname)
Email[$e]=${USER}@${HOST}

Most configuration entries can be indexed with a language code. In this case, the language that the user has selected for use on the desktop is used to look up the key value. If the default language (American English) has been selected or if there is no index that corresponds to the selected language, the key entry without index is used.

In the following example the value of the Caption entry depends on the language. If the user has selected French as language (language code fr) the value of the entry will be “Ma Légende”. In all other cases the value “My Caption” will be used.

[Preview Image]
Caption=My Caption
Caption[fr]=Ma Légende

In this example the value of the Caption entry depends on the language. If the user has selected French as language (language code fr) the value of the entry will be “Ma Légende.” In all other cases the value “My Caption” will be used.

[Preview Image]
Caption=My Caption
Caption[fr]=Ma Légende

In general the entries that can appear in a configuration file are not documented. With KDE 3.2 a start has been made to change this. In $KDEDIR/share/config.kcfg, files can be found that provide a formal description of the possible entries in a configuration file. These are used by the new KDE Configuration Editor when available.

Here is an example XML configuration file:


<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kcfg SYSTEM "http://www.kde.org/standards/kcfg/1.0/kcfg.dtd">
<kcfg>
    <kcfgfile name="korganizerrc"/>
    <group name="General">
         <entry type="Bool" key="Auto Save">
             <label>Enable automatic saving of calendar</label>
             <default>true</default>
         </entry>
         <entry type="Int" key="Auto Save Interval">
             <default>10</default>
         </entry>
    </group>
</kcfg>

It has the same effect as:

[General]
Auto Save=false
Auto Save Interval=25

Prev
Next
Home


docs.kde.org