Themed Greeter

The GDM theme format is specified in XML format contained within a <greeter> tag. You may specify a GTK+ theme to be used with this theme by using the gtk-theme element in the greeter tag as in the following example.

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

Contained within the greeter tag can be the nodes described in the next sections of this document. Some of these nodes are containers (box nodes, rect item nodes) which can be used to organize how to display the nodes that the user sees and interacts with (such as button, pixmap and entry item nodes).

Box nodes are container nodes for item nodes. Box nodes are specified as follows:

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

If the box is homogeneous then the children are allocated equal amount of space.

The "min-width" must be specified in pixels. Obviously there is also a corresponding "min-height" property as well.

Fixed is a container that has its children scattered about laid out with precise coordinates. The size of this container is the biggest rectangle that contains all the children. Fixed has no extra properties and so you just use:

<fixed>

The "toplevel" node is really just like a fixed node.

A GDM Theme is created by specifying a hierarchy of item and box nodes. Item nodes can have the following value for "type":

For example:

<item type="label">

Entry items can have id values as follows:

List items by default display as lists, but the combo="true" attribute can be used to specify combo box style (combo style supported since GDM 2.16.2). Some predefined lists may be included in a theme by using the following id values. Customized lists may also be defined, which are explained below.

Furthermore, you can have an arbitrary id (I'd recommend starting the id with 'custom' not to conflict with future additions to this spec) and ask extra information of the user. See the section 'Custom Widgetry'

Label items can have id values as follows:

Rectangles can have id values as follows:

If an item is of type rect, the item can be a button. Buttons must also include a "button" value as follows:

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

Possible values for button ids are as follows.

By default, the GDM login screen will disappear after authentication. This can result in flicker between the login screen and the session. The "background" property allows users to specify what elements of the theme are the background image. When used, this will cause GDM 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. For example, if the GDM theme and the session use the same background, then this will make the background apear seamless.

Item nodes may specify a "background" property which can be set to "true" or "false" (not setting this property is equivalent to "false"), as follows:

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

If no item node has "background" property set, then the background is not modified when greeter exits.

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"/>
    <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>

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

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

Both position and size can be given in percent and it will be taken as the percentage of the size of the current container. For toplevel items it's the percentage of the whole screen.

For x and y, you can also specify a negative position which means position from the right or bottom edge. But this only applies with absolute coordinates. With percentage you can specify negative position and it will be still from the same edge.

The position also specifies the anchor of the item, this can be "n" "ne" "e" "se" "s" "sw" "w" and "nw" or "center" which stand for the different edges/corners or "center" for center. For example:

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

If the item contains a box, you can specify width and height 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.

If the item contains an SVG image, you can specify width and height to be "scale" to mean that the SVG image should be scaled to fit the requested area.

You can also specify an "expand" property to either be "true" or false. If true then the child will be expanded in the box as much as possible (that is it will be given more space if available).

There are two extra properties you can specify (as of 2.4.4.3) for labels (and labels only). The first is "max-width" which will specify the maximum width of the label in pixels. And the second is "max-screen-percent-width" which specifies the maximum percentage of the screen width that the label can occupy. By default no label will occupy more then 90% of the screen by width. An example may be:

<item type="label">
<pos x="10%" max-screen-percent-width="50%"/>

Some items may only display in certain modes, like when doing a remote display. Multiple values can be specified and must be separated with commas. The following values are possible:

console - In console mode.

console-fixed - In console non-flexi mode.

console-flexi - In console & flexi mode.

flexi - In flexi mode.

remote - In remote mode.

remote-flexi - In remote & flexi mode.

For example:

<show modes="flexi,remote"/>

You can also specify the "type" value to indicate that certain items should only be displayed if the type is true. Valid values include the following:

chooser, if ChooserButton is set to "true" in the GDM configuration.

config, if ConfigAvailable is set to "true" in the GDM configuration.

custom_cmd[0-9], if n-th CustomCommand is specified in the GDM configuration.

halt, if HaltDaemon is specified in the GDM configuration.

reboot, if RebootCommand is specified in the GDM configuration.

suspend, if SuspendCommand is specified in the GDM configuration.

system, if SystemMenu is specified in the GDM configuration.

timed, if TimedLoginEnabled is set to "true" in the GDM configuration.

For example:

<show modes="console" type="system"/>

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

For example:

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

Note that if SystemMenu is off then the halt, restart, suspend, chooser and config choices will not be shown, so this is a global toggle for them all. See some of the standard themes for how the show modes are used.

Depending on the item type (except for userlist - refer to Color node below), it can specify its color, font, or image via the following tags:

normal - normal state.

active - when the item has active focus.

prelight - when the mouse is hovering over the item.

When item is "rect" (alpha can be omitted and defaults to 0.0):

<normal color="#ffffff" alpha="0.0">

When item is "label"

<normal color="#ffffff" font="Sans 14"/>

When the item type is "pixmap" or "SVG", then the normal, active, and prelight tags specify the images to use as follows:

<normal file="picture.png" tint="#dddddd"/>

Note that relative pathnames are assumed to be in the same directory as the theme .xml file in <share>/gdm/themes/<theme_name>.

Note that alternative image file can be specified using the altfile[n] property. GDM will use the last valid image filename specified. For example:

<normal file="picture.png" altfile1="distribution-blah-image.png" altfile2="distribution-foo-image.png"/>

If the item type is of userlist, then the background color for the icon and label can be set separately via the the following tag:

<color iconcolor="#dddddd" labelcolor="#ffffff"/>

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

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

You can include pango markup in the text nodes for labels, however you must encode it. So for example to have the label of "foo^bar", you must type:

<text>"foo<sup>bar</sup>"</text>

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

%% - A literal % character

%c - Clock time. Only labels with the "clock" id will update automatically every second. Other labels will contain a static timestamp.

%d - Display name (DISPLAY environment variable)

%h - Hostname (gethostname output)

%m - Machine name (uname.machine output)

%n - Node name (uname.nodename output)

%o - Domain name (getdomainname output)

%r - Release name (uname.release output)

%s - System name (uname.sysname output)

%t - Current timed delay value from configuration file (0 if off) followed by the word "seconds" if value is greater than 1 or the word "second" if the value is 1. This character sequence is intended to be only used internally to display the "timed-label" message, which is automatically updated every second.

%u - Timed username value from configuration file (empty if off) This character sequence is intended to be only used internally to display the "timed-label" message, which is automatically updated every second.

\n - Carriage return

_ - An underscore causes the following character to be underlined. If it precedes a % character sequence, the string that replaces the character sequence is underlined.

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

cancel, _("_Cancel"

caps-lock-warning, _("Caps Lock is on."

chooser, _("Remote Login via _XDMCP"

config, _("_Configure"

custom_cmd[0-9], getting label from config file

disconnect, _("D_isconnect"

halt, _("Shut _Down"

language, _("_Language"

ok, _("_OK"

options, _("_Options"

quit, _("_Quit"

reboot, _("_Restart"

session, _("_Session"

startagain, _("_Start Again"

suspend, _("Sus_pend"

system, _("_Actions" (Formerly "S_ystem"

timed-label, _("User %u will login in %t"

username-label, _("Username:"

welcome-label, _("Welcome to %n"

For example:

<stock type="welcome-label">

Currently there is one item which is customizable and this is the list item. If you need to ask the user extra things, such as to pick from a list of places to log into, or set of custom login sessions you can setup the list item and add listitem children that describe the choices. Each listitem must have an id and a text child. The choice will be recorded in the file <ServAuthDir>/<display>.GreeterInfo as <list id>=<listitem id>.

For example suppose we are on display :0, ServAuthDir is <var>/lib/gdm and we have the following in the theme:

<item type="list" id="custom-config">
<pos anchor="nw" x="1" y="1" height="200" width="100"/>
<listitem id="foo">
<text>Foo</text>
</listitem>
<listitem id="bar">
<text>Bar</text>
</listitem>
</item>

Using GDM 2.20, the file is created in INI format. The group value is "GreeterInfo", and the "custom-config" key will specify the id of the chosen listitem. For example, if the user chooses "Foo" (which has an id value of "foo", then <var>/lib/gdm/:0.GreeterInfo will contain:

[GreeterInfo]
custom-config=foo

Using GDM 2.18 and earlier, the file is not saved in INI format, so the "GreeterInfo" group will not be in the file. In other words, the file will contain only the following:

custom-config=foo