<?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
A button field. This field uses a Qt button.
It is also possible to make any other item act like a button by setting its
true. However, it is better to use Qt buttons in kdm themes since these are accessible to users with disabilities.
An input widget like a line edit or combo box. Note that this is merely a placeholder for Qt widgets.
A face browser widget.
A raster image in a format that Qt supports, e.g. PNG, JPEG, Tiff, etc.
A plain rectangle.
A vector image in SVG format.
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.
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
all, meaning the screen the greeter is on, all
screens the greeter is not on and all screens, resp.
Each item can be given a name via the
attribute. Certain ids are recognized by kdm to give those
items a special function:
buttonitems and items with the
Buttons typically trigger certain actions. Addionally, kdm will hide buttons whose actions are not available for some reason.
Id Action chooser_button Runs the XDMCP chooser. disconnect_button Disconnect from remote session. session_button Open the session type selection menu. system_button Open a catch-all menu with various options and actions, depending on the configuration.
kdm will show/hide these labels and set their text depending on the state of the login dialog.
Id Function pam-error This displays the Login failed. message.
- Widget embedding items
kdm will embed particular Qt widgets into these items.
Id Function user-entry Entry field for username entry. pw-entry Entry field for password entry. domain-entry Some “conversation” plugins use this field to query a domain name. If this field is present, the related enclosing items should have show nodes with the type
talker This item should be of type
rect. It represents the “hot” area of the greeter: it contains the
entryitems which concern the authentication process. If a given “conversation” plugin cannot match the existing items with its needs, it tries to embed a complex widget with an own layout into this item, thus completely overriding the theme's “talker”. Strictily speaking, kdm themes do not need to provide own “talker” designs at all, as all kdm authentication plugins are able make use of the
userlist This item must be of type
list. If the user list feature is enabled, kdm will embed the user list widget here. Otherwise, this item is hidden.
xconsole This item should be of type
rect. If the built-in xconsole feature is compiled in and enabled, kdm will embed the console log widget here. Otherwise, this item is hidden.
- Other items
kdm will show/hide these items depending on the configuration and the current state of the greeter. kdm does not impose type requirements on them, but they usually lend themselves to a particular type.
Id Shown only when ... timed-label ... timed login is in progress. caps-lock-warning ... Caps Lock is active. xauth-warning ... the X-Server requires no X authorization to connect. userlist-rect ... the user list is enabled. By nesting the
userlistitem into this one, it is possible to create something like a frame around the list and have it shown only when the user list itself if shown.
xconsole-rect ... the built-in xconsole is enabled. Analogous to
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 nodes automatically arrange their children in a row. They are specified as follows:
num means number of pixels and
bool means either
alignment value can be either
If you leave any attribute off, it will default to zero for numbers,
false for bools and
for the orientation.
The spacing is the distance between neighboring child items. The padding is the box' outer margin. If the box is homogeneous, the same amount of space is allocated to each child item.
Each item can specify its position and size via the
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,
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.
be specified to be
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.
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).
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
attributes which can be specified in the same ways as
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
c for center or one of
which stand for the different edges/corners corresponding the
directions on a topographical map.
The default is
nw, which is the upper left corner.
<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:
|Type||Display if ...|
|switching to remote login is permitted.|
|system shutdown is permitted.|
|no condition (always set in kdm).|
|the “conversation” plugin provides a corresponding input field.|
Alternatively, you can specify a
min-screen-height value to indicate that certain
items should be displayed only if the screen resolution is the
at least the specified size.
The look of most item types can be parametrized via the following tags:
When the mouse is hovering over the item.
When a mouse button is clicked on the item.
The exact set of available attributes depends on the item type:
<normal color="#000000" alpha="0.0"/>
Either of the attributes may be omitted, in which case the default is used (the example represents the defaults).
alphais a floating point number between zero (transparent) and one (opaque).
coloris a hashmark followed by a six-digit hex number; the format is “
colormay be specified as an eight-digit hex number, in which case the first two digits are the alpha value.
<normal color="#ffffff" alpha="1.0" font="Sans 14"/>
colorare specified like in “rect” items.
fontfollows the format “
size”. Each part is optional.
family-listis a comma-separated list of font families like “helvetica”, “monospace”, etc.
style-optionsis a space-delimited list of keywords from the categories style, weight and stretch; from each category at most one. The style can be
oblique. Weight can be
heavy. Allowable stretches comprise
sizeis either a floating point number representing the size in points (1/72 inch) or an integer followed by
pxrepresenting the size in pixels. Point sizes are preferable, as they are independent from the display resolution.
If either attribute is left out, the values from the style node are used. If this yields no window-text color specification, white is used. The default font is the one configured in
<normal file="picture.png" tint="#dddddd" alpha="1.0"/>
filespecifies the file containing the image. Relative pathnames are relative to the theme's directory.
wallpapercan be used instead of
fileto have kdm look for images in the usual locations for KDE wallpapers. Plasma wallpaper packages are supported.
elementspecifies the element id of a SVG file. If empty, the whole SVG image will be rendered.
pixmapnodes, it is possible to provide multiple images, so the best-quality image for a given resolution can be used. Size-tagged file names have the format
extension. If the not size-tagged file exists and it is no Plasma wallpaper package, kdm will accept only a perfect match for a given size and otherwise fall back to the original file. Otherwise it will try to find an image whose dimensions come closest to the required size if no perfect match is found.
scalemodespecifies how to adjust the size of images which do not match the element's size.
free(the default) means to simply scale the image to the right size, possibly distorting its aspect ratio. The other two modes maintain the image's aspect ratio:
fitmeans to zoom the image to the maximal size which fits into the element's geometry. The image will be centered. The remaining area will not be painted by this element, so it should be placed on top of a solid-filled
cropmeans to zoom the image to the minimal size which completely fills the element's geometry. The image will be clipped symmetrically.
alphaform a color specification like in
rectitems. Each pixel of the image is multiplied with this color component-wise.
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
font attribute defines the font for all widgets.
For widgets with an input function it can be overridden with the
Fonts are specified the same way as in
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
guistyle attribute can be used to override the
Qt GUI style for embedded widgets. The default is given by
It is possible to specify almost the entire palette for the widgets
as documented at
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
disabled- for the respective color group.
Supported color roles are
The suffix can be
-alpha with the respective meaning as in
As an alternative to specifying the palette inline, the
colorscheme attribute can be used to load
a complete KDE color scheme. The default is given by
color specifications will override
the colors from the scheme.
<style edit-font="Comic 16" text-color="#dddddd" frame="true"/>
Color nodes permit overriding the background color of the items
in the face browser.
altlabelcolor are essentially equivalent to
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
attribute is omitted, the POSIX locale is assumed):
Text nodes can contain the following special character sequences which will be translated as follows:
|%%||A literal % character|
|%c||Wall clock time and date|
|%d||Display name (|
|%m||Machine name (|
|%n||Node name (|
|%o||Domain name (|
|%r||Release name (|
|%s||System name (|
|%t||Remaining number of seconds until timed login is performed, plus the appropriate i18n plural form of “second”|
|%u||Username for timed login|
|_||Causes the following character to be an accelerator|
%u are intended to be
used only internally to display the
message, which is automatically updated every second.
Certain common localized labels can be specified via the stock
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:
|caps-lock-warning||“Caps Lock is enabled”|
|timed-label||“User %u will login in %t”|
|welcome-label||“Welcome to %h”|
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
label's accelerator pressed).
The buddy is referenced by id with the
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>