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.
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 .desktop
files. 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.
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">
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 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.
A GDM Theme is created by specifying a hierarchy of item and box nodes. Item nodes can have the following value for "type":
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.
Text entry field.
A text label. Must have a "text" node to specify the text.
A face browser widget. Only useful if the face browser is enabled via the configuration.
An pixmap image in a format that gdk-pixbuf supports like PNG, JPEG, Tiff, etc...)
Rectangle.
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:
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.
A list of available sessions, which allows the user to pick the session to use. Supported since GDM 2.16.2.
A list of available languages, which allows the user to pick the language to use. Supported since GDM 2.16.2.
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.
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:
Label that displays the date and time.
Label that displays the PAM prompt. This is the prompt that PAM uses to ask for username, password, etc...
Label that displayst PAM/GDM error messages. Such as when user can't log in.
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.
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.
Label that displays timed login information.
Rectangles can have id values as follows:
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.
Runs the XDMCP chooser.
Runs the GDM configuration application.
Runs the n-th
custom command.
Disconnect from remote session.
Displays the language selection dialog.
Halt (shuts down) the system.
Restart the system.
List and select from available sessions.
Suspend the system.
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>
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 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.
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<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.
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