Themed Greeter

This section describes the creation of themes for the Themed Greeter. For examples including screenshots, see the standard installed themes and the themes from the theme website.

Theme Overview

GDM Themes can be created by creating an XML file that follows the specification in gui/greeter/greeter.dtd. Theme files are stored in the directory <share>/gdm/themes/<theme_name>. Usually this would be under /usr/share. The theme directory should contain a file called GdmGreeterTheme.desktop which has similar format to other .desktop files and looks like:

[GdmGreeterTheme]
Encoding=UTF-8
Greeter=circles.xml
Name=Circles
Description=Theme with blue circles
Author=Bond, James Bond
Copyright=(c) 2002 Bond, James Bond
Screenshot=screenshot.png

The Name, Description, Author and Copyright fields can be translated just like the other .desktopfiles. All the files that are mentioned should be in the theme directory itself. The Screenshot field points to a file which should be a 200x150 screenshot of the theme in action (it is OK not to have one, but it makes it nicer for user). The Greeter field points to an XML file that contains the description of the theme. The description will be given later.

Once a theme is installed, it can be tested with the gdmthemetester program. This program assumes that the X server supports a nested server command. This command takes two arguments, first the environment that should be used. The environment can be one of the following values: console, console-timed, flexi, remote-flexi, or xdmcp. The "console" option tests the theme as it would be shown on an attached display. The "console-timed" option tests the theme as it would be shown on an attached display with timed login enabled. The "flexi" option tests the theme as it would be shown on an attached flexible display (such as started via Xnest). Finally, the "xdmcp" option tests the theme as it would be shown for remote XDMCP displays. The second argument is the theme name. For example, to test how the circles theme would look in XDMP remote display mode, you would run the following command:

gdmthemetester xdmcp circles

When developing a theme, make sure to test all the environments, and make sure to test how the caps lock warning looks by pressing the caps lock key. Running gdmthemetester is also a good way to take screenshots of GDM themes. Simply take a screenshot of the theme running in the nested display window. This can be done in GNOME by focusing the nested login window and pressing Alt-PrintScreen.

Once a theme has been fully tested, then make a tarball that contains the directory as it would be insatlled to the <share>/gdm/themes directory. This is the standard format for distributing GDM themes.

Detailed Description of Theme XML format

greeter tag

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

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

Where "num" means number and bool means either "true" or "false" The alignment value can be either "horizontal" or "vertical". If you leave any property off it will default to zero or "false" in case of "homogeneous" and "vertical" for the orientation.

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 Nodes

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>

Then you put other items with proper position nodes inside this.

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

Item Nodes

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

button

A button field. This field uses a GTK+ button. It is also possible to make a "rect" item act like a button by setting its button element to true. However it is better to use GTK+ buttons in GDM themes since these are accessible to users with disabilities. Also, GTK+ buttons can be themed. This feature is supported in GDM 2.14.6 and later.

entry

Text entry field.

label

A text label. Must have a "text" node to specify the text.

list

A face browser widget. Only useful if the face browser is enabled via the configuration.

pixmap

An pixmap image in a format that gdk-pixbuf supports like PNG, JPEG, Tiff, etc...)

rect

Rectangle.

svg

Scaled Vector Graphic image.

For example:

<item type="label">

Items can specify ID values which gives them a specific look and feel or formatting. Furthermore you can customize the login process by adding custom widgets with custom id's for some items (currently only the list item)

Entry items can have id values as follows:

user-pw-entry

Entry field for userid and password entry. This is the field used for responses for the PAM/GDM questions (Username, Password, etc..).

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.

session

A list of available sessions, which allows the user to pick the session to use. Supported since GDM 2.16.2.

language

A list of available languages, which allows the user to pick the language to use. Supported since GDM 2.16.2.

userlist

A Face Browser list, so that users can pick their username by clicking on this instead of typing. This obviously exposes the usernames to viewers of the login screen, and is not recommended for users who feel that this reduces security. The face browser does not support combo box style.

userlist-rect

This id can be specified for the <rect> object containing the userlist and if the userlist is empty then this rectangle will not be shown. This allows the theme to define something like an area with a different color and/or alpha to surround the userlist, but only if there are users to display. Supported since 2.16.2.

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:

clock

Label that displays the date and time.

pam-prompt

Label that displays the PAM prompt. This is the prompt that PAM uses to ask for username, password, etc...

pam-error

Label that displayst PAM/GDM error messages. Such as when user can't log in.

pam-error-logo

An image that will be displayed only when a pam-error message is being displayed. This is useful for displaying an "Attention" icon, for example. This feature is supported in GDM 2.14.6 and later.

pam-message

Label that displays the PAM message. These are messages that PAM/GDM gives about state of the account, help about the prompts and other information.

timed-label

Label that displays timed login information.

Rectangles can have id values as follows:

caps-lock-warning

Displays an icon that shows if the CAPS LOCK key is depressed. This rectangle will be hidden/shown appropriately

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.

chooser_button

Runs the XDMCP chooser.

config_button

Runs the GDM configuration application.

custom_cmd_button[0-9]

Runs the n-th custom command.

disconnect_button

Disconnect from remote session.

language_button

Displays the language selection dialog.

halt_button

Halt (shuts down) the system.

reboot_button

Restart the system.

session_button

List and select from available sessions.

suspend_button

Suspend the system.

system_button

Perform halt/restart/suspend/etc. options (if allowed by GDM configuration). Also allows user to run configurator if user enters root password (again if allowed by GDM configuration). This is usually now labeled Actions, and referred to as the Actions menu.

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>

Position Node

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

Show Node

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.

Normal/Active/Prelight Nodes

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 distribution-foo-image.png is a valid image filename it will be used. Otherwise distribution-blah-image.png will be used if valid. This feature supported since 2.16.3.

Face Browser Icon/Label Color Nodes

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 Node

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<sup>bar</sup>", 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.

Stock node

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

Custom Widgetry

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