|
|
| (14 intermediate revisions by 8 users not shown) |
| Line 1: |
Line 1: |
| == File Format ==
| | {{Moved To Userbase}} |
| 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.
| |
| | |
| ==== Example: A Simple Config File ====
| |
| The following example shows a configuration file that consists of two groups.
| |
| The first group contains the keys "<tt>LargeCursor</tt>" and
| |
| "<tt>SingleClick</tt>", the second group contains the keys
| |
| "<tt>Show hidden files</tt>" and "<tt>Sort by</tt>".
| |
| <code>
| |
| [KDE]
| |
| LargeCursor=false
| |
| SingleClick=true
| |
| | |
| [KFileDialog Settings]
| |
| Show hidden files=false
| |
| Sort by=Name
| |
| </code>
| |
| | |
| Entries in a group consists of a key and value seperated by an equal sign.
| |
| The key can contain spaces and may be followed by options placed in
| |
| square brackets.
| |
| | |
| The part after the equal sign is the value of the entry. Any white space
| |
| surrounding the equal sign is ignored, as is any trailing white space.
| |
| | |
| 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 complete list:
| |
| | |
| * "<tt>\s</tt>" can be used as space
| |
| * "<tt>\t</tt>" can be used to include a tab
| |
| * "<tt>\r</tt>" for a carriage return character
| |
| * "<tt>\n</tt>" for a linefeed character (new line)
| |
| * "<tt>\\</tt>" to include the backslash itself
| |
| | |
| ==== Example: Whitespace ====
| |
| The following config file fragment is equivalent to the one in the
| |
| previous example. Whitespace surrounding the key and value is ignored.
| |
| <code>
| |
| [KDE]
| |
| LargeCursor= false
| |
| SingleClick = true
| |
| | |
| [KFileDialog Settings]
| |
| Show hidden files = false
| |
| Sort by =Name
| |
| </code>
| |
| | |
| ==== Example: Preserving Whitespace ====
| |
| In the following example the value of the "<tt>Caption</tt>" entry starts
| |
| with two spaces while the "<tt>Description</tt>" entry contains three lines
| |
| of text. Linefeeds in backslash notation are used to seperate the different lines.
| |
| <code>
| |
| [Preview Image]
| |
| Caption=\s My Caption
| |
| Description=This is\na very long\ndescription.
| |
| </code>
| |
| | |
| Empty lines in configuration files are ignored, just as lines that
| |
| start with a hash mark '#'. The hash mark can be used to add comments to
| |
| configuration files but it should be noted that when a KDE application
| |
| updates a configuration file the comments are not
| |
| preserved.
| |
| | |
| == Configuration ==
| |
| There can be multiple configuration files with the same name in the
| |
| share/config sub-directory of the various
| |
| [fsh.php#dir_location KDE Directory Trees].
| |
| In that 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.
| |
| | |
| KDE's cascading configuration scheme can be used to provide users with
| |
| system or organisation wide default settings while it still allows the users
| |
| to make individual changes to these settings. KDE will not write entries to
| |
| the users configuration file under $KDEHOME that match any default settings
| |
| provided this way. This way changes made to the default settings will
| |
| immediately be propagated to the user. Note that differs from the traditional
| |
| way of providing default settings for users through the use of /etc/skel,
| |
| changes to /etc/skel will only be propagated when creating a new user account.
| |
| | |
| When it is undesirable that individual users can make changes to default
| |
| settings, the default setting can be locked down.
| |
| | |
| == Shell Expansion ==
| |
| | |
| 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 <tt>[$e]</tt>. Normally the expanded form is written into the users
| |
| configuration file after first use. To prevent that, it is recommend to lock
| |
| the configuration entry down by using <tt>[$ie]</tt>.
| |
| | |
| ==== Example: Dynamic Entries ====
| |
| In the following example the value for the "<tt>Host</tt>" 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 "<tt>Email</tt>" 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
| |
| "<tt>joe@joes_host</tt>". The setting is not locked down.
| |
| | |
| <code>
| |
| [Mail Settings]
| |
| Host[$ie]=$(hostname)
| |
| Email[$e]=${USER}@${HOST}
| |
| </code>
| |
| | |
| == Localisation ==
| |
| | |
| All 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.
| |
| | |
| ==== Example: UTF8 In Keys ====
| |
| In the following example the value of the "<tt>Caption</tt>" entry
| |
| depends on the language. If the user has selected french as language (language
| |
| code <tt>fr</tt>) the value of the entry will be "<tt>Ma Légende</tt>".
| |
| In all other cases the value "<tt>My Caption</tt>" will be used.
| |
| <code>
| |
| [Preview Image]
| |
| Caption=My Caption
| |
| Caption[fr]=Ma Légende
| |
| </code>
| |
| | |
| == Lock Down ==
| |
| | |
| To prevent that users can override default settings, you can lock
| |
| these settings down. Settings can be locked down individually, per group
| |
| or per file. An individual entry can be locked down by adding <tt>[$i]</tt>
| |
| behind the key. A group of entries can be locked down by placing
| |
| <tt>[$i]</tt> behind the group name. To lock down the entire file, start
| |
| the file with <tt>[$i]</tt> on a single line.
| |
| | |
| ==== Example: Using [$i] ====
| |
| In the following example the "<tt>Caption</tt>" entry has been locked
| |
| down. All entries in the "<tt>Mail Settings</tt>" group have been
| |
| locked down as well.
| |
| <code>
| |
| [Preview Image]
| |
| Caption[$i]=My Caption
| |
| | |
| [Mail Settings][$i]
| |
| Host[$e]=$(hostname)
| |
| Email=waldo@kde.org
| |
| </code>
| |
| | |
| If an entry has been locked down, entries that would otherwise take
| |
| precedent over the default setting will now be ignored.
| |
| | |
| Any changes that applications make to settings that have been locked
| |
| down will be silently dropped. It depends on the application
| |
| how it responds to locked down settings. Some applications
| |
| recognize it when a setting has been locked down and will remove those
| |
| elements from its user interface that would otherwise allow the user
| |
| to make changes to these settings. Other applications will continue
| |
| to offer these options in their user interface even though the option
| |
| does not have any effect any more. It is also possible that it is actually
| |
| still possible to change the setting in the running program. In that case the
| |
| changed setting will be effective for the time the program remains running.
| |
| When the program is restarted it will then return to the locked down default
| |
| settings.
| |
| | |
| == Editors ==
| |
| If you do not want to use a text editor then
| |
| [http://extragear.kde.org/apps/kconfigeditor/ KConfigEditor]
| |
| offers a convenient way to edit KDE configuration files.
| |
| | |
| For scripts or modifying files from the command line, the command line app <tt>kwriteconfig</tt> is very useful. <tt>kwriteconfig</tt> expects a configuration file name, a group, a key, an optional type and a value, such as:
| |
| | |
| <code>kwriteconfig --file kickerrc \
| |
| --group General \
| |
| --key AutoHidePanel \
| |
| --type bool \
| |
| true</code>
| |
