kdm themes are XML files with the <greeter> tag at their root. The toplevel node is an item node of type rect with an implicit fixed layout.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE greeter SYSTEM "greeter.dtd">
<greeter>
[...]
</greeter>

Contained within the greeter tag can be the nodes described in the next sections of this document. Some of these nodes are containers (layout nodes, item nodes) which can contain other nodes again.

A kdm theme is created by specifying a hierarchy of item and layout nodes. Item nodes can have the following value for the type attribute:

For example:

<item type="label">

An item that acts as a button:

 <item type="rect" id="disconnect_button" button="true">.

By default, the kdm login screen will disappear after authentication. This can result in flicker between the login screen and the session. The background attribute allows users to specify what elements of the theme are the background image. When used, this will cause kdm to remove all non-background items from the display and render the remaining background items to the root window. This can be used to create a smooth transition between the login screen and the session:

<item type="rect" background="true">
  <normal file="background.svg"/>
  <pos x="0" y="0" width="100%" height="-75"/>
</item>

To use a different background for login transition than the one used for login, the theme should specify two item nodes (which could contain pixmaps or svg images, for example). The item which corresponds to the greeter background should not have the background property while the item which corresponds to the transition background should have the background property. For instance :

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE greeter SYSTEM "greeter.dtd">
<greeter>
  <item type="rect" background="true">
    <normal file="background_for_login.svg" element="background"/>
    <pos x="0" y="0" width="100%" height="100%"/>
  </item>
  <item type="rect">
    <normal file="background_for_greeter.svg"/>
    <pos x="0" y="0" width="100%" height="100%"/>
  </item>
  [...]
</greeter>

In multi-screen setups, themes may also specify the look of other screens than the one the greeter is on - but typically only background items will appear there. To specify which screen(s) an item should appear on, the screen attribute can be used with the value being one of greeter, other or all, meaning the screen the greeter is on, all screens the greeter is not on and all screens, resp.

Layout nodes appear inside item nodes and contain item nodes again. The type of the layout node determines the arrangement of its child nodes. An item node can contain one layout node of each type.

<box orientation="alignment" min-width="num" min-height="num"
    xpadding="num" ypadding="num" spacing="num"
    homogeneous="bool">

<fixed>

Each item can specify its position and size via the pos node. For example:

<pos x="0" y="4" width="100%" height="100%"/>

If the size is not specified, it will be the item's “natural” size, called the size hint. Note that not all items have a useful size hint.

Both position and size can be given in percent and will be calculated relative to the size of the enclosing container in this case. For toplevel items it is the percentage of the whole screen. By appending circumflexes (^) to the size specification it is possible to modify it to be relative to the size of the enclosing item's enclosing item and so on.

If the item contains a box, width and height can be specified to be box to mean that they are supposed to be the width and height of the box, that is the items in the box plus the padding.

One of width and height can be specified to be scale to mean that it should be scaled according to the other dimension's scale relative to its size hint. Use this to preserve the aspect ratio of scaled images automatically.

If the expand attribute is specified and true, this item will be expanded in the enclosing box as much as possible (that is it will be given more space if available).

If width or height is a plain number, a negative value represents an offset from the enclosing container's size. Note that it is possible to specify a positive offset by writing two minus signs.

In either case it is possible to constrain the final size with the min-width, min-height, max-width and max-height attributes which can be specified in the same ways as width and height.

If x or y is a plain number, a negative value represents an offset from the right resp. bottom edge, unlike the default which is the left resp. top edge.

It is also possible to specify which point within the item the position refers to. This is called the anchor and can be either c for center or one of n, ne, e, se, s, sw, w and nw which stand for the different edges/corners corresponding the directions on a topographical map. The default is nw, which is the upper left corner. For example:

<pos x="10%" y="50%" anchor="w" width="80%" height="95"/>

You can specify the type attribute to indicate that certain items should only be displayed if the type is set. Prefixing the type with an exclamation mark (!) reverses the condition. Valid values include the following:

For example:

<show type="chooser"/>

Alternatively, you can specify a min-screen-width or min-screen-height value to indicate that certain items should be displayed only if the screen resolution is the at least the specified size. For example:

<show min-screen-height="768"/>

The look of most item types can be parametrized via the following tags:

This tag makes it possible to change the appearance of labels and Qt widgets embedded into the theme, e.g., line edits, buttons or the user list. The style settings are inherited by child items, but can be overridden individually. The defaults are taken from kdmrc.

The font attribute defines the font for all widgets. For widgets with an input function it can be overridden with the edit-font attribute. Fonts are specified the same way as in normal/active/prelight nodes.

Usually, the theming engine tries hard to remove any frames from Qt widgets, so they melt into the theme seamlessly. In cases where this is not desired, the frame attribute can be set to true.

It is possible to specify almost the entire palette for the widgets as documented at Trolltech's site. Attribute names are composed from a scope, a color role and a suffix. Possible scopes are - in order of increasing precedence - all- for all color groups, no scope for the active and inactive color groups and active-, inactive- and disabled- for the respective color group. Supported color roles are window, window-text, base, alternate-base, text, bright-text, highlight, highlighted-text, button and button-text. The suffix can be -color or -alpha with the respective meaning as in normal/active/prelight nodes.

Example:

<style edit-font="Comic 16" text-color="#dddddd" frame="true"/>

Color nodes permit overriding the background color of the items in the face browser. labelcolor and altlabelcolor are essentially equivalent to all-base-color resp. all-alternate-base-color in style nodes. If only labelcolor is specified, alternating item backgrounds are disabled.

<color labelcolor="#80ffffff" altlabelcolor="#80f0f0f0"/>

Text tags are used by labels. They can be used to display localized text as follows (if the xml:lang attribute is omitted, the POSIX locale is assumed):

<text xml:lang="fr">Option</text>

Text nodes can contain the following special character sequences which will be translated as follows:

%t and %u are intended to be used only internally to display the timed-label message, which is automatically updated every second.

Certain common localized labels can be specified via the stock tags. The text tag is ignored if the stock tag is used. You really should use the stock labels rather than just putting all the translations into the themes. This yields faster load times and likely better translations. The following values are valid:

For example:

<stock type="welcome-label"/>

Items which do not directly cause an action can be assigned a buddy. The buddy is given input focus when the item is activated (clicked or a label's accelerator pressed).

The buddy is referenced by id with the idref attribute. Obviously, it must be given an id. Example:

<item type="label">
  <stock type="username-label"/>
  <buddy idref="user-entry"/>
  [...]
</item>
[...]
<item type="entry" id="user-entry">
  [...]
</item>