Gnome Display Manager Reference Manual
<<< Previous		Next >>>

Graphical Greeter Themes

This section describes the creation of themes for the Graphical 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 you have theme ready and installed you can test it with the installed gdmthemetester script. This script assumes that you also have installed the Xnest X server. It takes two arguments, first the environment that should be used. This is one of console, console-timed, flexi, remote-flexi, xdmcp. Where console is a standard console login, console-timed is a console login with a timed login going on, flexi is for any local flexible server, remote-flexi is for flexi server that is not local (such as an Xnest flexiserver run from a remote display) and xdmcp is for remote xdmcp connections. The second argument is the theme name. So for example to test how things look in the xdmcp mode with the circles theme you would run:

gdmthemetester xdmcp circles

Be sure to test all the environments with your theme, and make sure to test how the caps lock warning looks by pressing caps lock. This is also a good way to take screenshots, just take a screenshot of the Xnest window. This can be done in GNOME by focusing the Xnest window and pressing Alt-PrintScreen.

Once you have all this done, then make a tarball that contains the directory name (so that you could just untar it in the /usr/share/gdm/themes directory). And this is the tarball you distribute and people can install from the graphical setup program. You can do this with the commands:

     cd /usr/share/gdm/themes
     tar czvf <theme_name>.tar.gz <theme_name>/

Detailed Description of Theme XML format

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 just has it's children scattered about layed 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":

entry: Text entry field.
list: A list widget.
label: A text label. Must have a "text" node to specify the text.
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 can have id values as follows:

userlist: A user browser list, so that users can pick their username by clicking on this instead of typing.

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 the displays the date and time.
pam-prompt: Label the displays PAM prompt. This is the prompt that PAM uses to ask for username, password, etc...
pam-error: Label the displays PAM/GDM error messages. Such as when user can't log in.
pam-message: Label the displays 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 Setup program.
disconnect_button: Disconnect from remote session.
language_button: Displays the language selection dialog.
halt_button: Halt (shuts down) the system.
reboot_button: Reboot the system.
session_button: List and select from available sessions.
suspend_button: Suspend the system.
system_button: Perform halt/reboot/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.

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.

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 gdm.conf file.

config, if ConfigAvailable is set to "true" in gdm.conf file.

halt, if HaltDaemon is specified in gdm.conf file.

reboot, if RebootCommand is specified in gdm.conf file.

suspend, if SuspendCommand is specified in gdm.conf file.

system, if SystemMenu is specified in gdm.conf file

timed, if TimedLoginEnabled is set to "true" in gdm.conf file.

For example:

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

Note that if SystemMenu is off then all of halt, reboot, suspend, chooser and config will not show, 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, 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>.

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&lt;sup&gt;bar&lt;/sup&gt;</text>

Stock

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:

caps-lock-warning, _("You've got capslock on!")

chooser, _("_XDMCP Chooser")

disconnect, _("D_isconnect")

halt, _("Shut_down")

language, _("_Language")

quit, _("_Quit")

reboot, _("_Reboot")

session, _("_Session")

suspend, _("Sus_pend")

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

timed-label, _("User %s will login in %d seconds")

username-label, _("Username:")

welcome-label, _("Welcome to %h")

For example:

       <stock type="welcome-label"/>

Custom Widgetry

Currently there is one item which can be 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/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>

Then if the user chooses 'Foo' then /var/gdm/:0.GreeterInfo will contain:

       custom-config=foo

<<< Previous	Home	Next >>>
GDM and Related Commands		Example Configurations