• The intent of this page is to offer an explanation of the various components in a Gnome Display Manager theme (also known as a gdm theme or a graphical greeter theme), as well as a basic tutorial of creating a theme, and tips for getting the most out of GDM features.

What is a GDM Theme?

• A GDM theme Is a collection of files that control the appearance of the Login Window, officially named the Gnome Display Manager, and referred to in short as the GDM. If you look in the /usr/share/gdm/themes/ directory, you can see the GDM themes that are already installed.

GDM Theme Components

• A GDM theme consists of around five components:

The .desktop file

• Apparently, this is not a "true" .desktop file. I can neither confirm nor deny that fact. I can tell you that the GdmGreeterTheme.desktop file allows you to specify a name, creator, copyright information, a brief description, and the name of the preview image. This information is used by the GDM settings panel when listing your theme.

<pos x="50%" y="33%" width="scale" height="15%" anchor="c"/>

The Theme's XML file

• This is the file that tells the GDM what to display, how it should look, and where it will go. This is where we will be doing most of our work.

The Background Image

• This is fairly self explanatory. The background image is just like a wallpaper. Changing the background image is probably the most common change made to existing GDM themes. I know that's how I got started.

The Preview Image

• This, too, is fairly self-explanatory. The preview image is a picture of the theme in use, and is displayed in the GDM preferences window.

Any Foreground Images (Not Required)

• These are images that you use like icons in your theme. Common uses are for placing distro logos in the theme and to accompany or replace button label text.

The GdmGreeterTheme.desktop File

• This is a skeleton for a GdmGreeterTheme.desktop file

[GdmGreeterTheme]
Greeter=
Name=
Description=
Author=
Screenshot=
Copyright=

• Greeter gives the filename of the XML file for the theme. Name gives the title of your theme. Description gives a brief description of your theme. Author gives the name of the theme's creator. Screenshot gives the filename of the preview image. Copyright gives the copyleft information for the theme.

The Theme's XML file

• This is a skeleton for an XML theme file.

<?xml version="1.0"?>
<!DOCTYPE greeter SYSTEM "greeter.dtd">
<greeter>
</greeter>

• This portion of the XML file must remain unaltered. Everything that we can add or change will go in between the <greeter> and the </greeter> tags. If you want a quick explanation of the "rules" for XML, along with the basic vocabulary, I recommend reading [http://www.xml.com/pub/a/98/10/guide0.html?page=3 this] page on XML.com.

Available Theme Elements

These are all of the elements that will be used for the tutorial theme. More information on each element is available in the tutorial and in the reference tables at the end of this page.

<item></item>

• Everything that we add to the skeleton XML file will appear, wither inside of, or in between <item> tags.

<pos/>

• The <pos/> element is used to control the position and size of an item. The "x" and "y" attributes to give either exact pixel values, or percentages. the "height" and "width" attributes will also accept pixel or percentage based values.

<normal/>

• The <normal/> element allows you to control the color, font, opacity and other features of certain items. The <normal/> element can often be used in conjunction with the <active/> and <prelight/> elements to change the appearance of an item when the mouse cursor is over it, and when it is actually clicking the item.

<stock/>

• The <stock/> element is your best friend. Really. The stock element will display common labels in a user's preferred language. This takes all of the work out of making your GDM theme multilingual.

The Tutorial

• For much of this tutorial you will be required to write in files and directories that are in the /usr directory, so, you must be running in "superuser" mode. To do this you will need the root password, also known as the administrator password.

Phase One: The Setup

• As I have said, you will need to be able to execute commands as root. In particular, you will need to install GDM themes, change the default theme, and write files to the theme directory in /usr/share/gdm/themes/ To make things easier here in the beginning, I have created a "skeleton" of a theme. No, it doesn't feature any bones, just all of the files necessary to act as a template for a GDM theme. You can download it [attachment:GDMTheme.tar.gz here]. If you are going to use the GDMtheme template, go ahead and install it now. If not, I will assume that you know what you are doing and leave you to your own devices.

Phase Two: The Beginning

• In this phase, we are only going to create the bare minimum of a functioning GDM theme. Latter phases will build on this base.

Step One

• Pick a background to use for your theme and copy it into the theme directory. If you are using the template, this should be /usr/share/gdm/theme/GDMtheme/ Make sure that the permissions allow for it to be read by everyone.

Step Two

• As root, open the GDMtheme.xml file in /usr/share/gdm/theme/ directory with your favorite text editor.

Step Three

• Now we are going to tell GDM to use the background that we have chosen. In between the <greeter> and </greeter> elements, write or paste this:

<item type="pixmap">
        <normal file="background.png"/>
        <pos x="0" y="0" width="100%" height="100%"/>
</item>

• where background.png is the name of the background image that you have copied into the theme directory. If you are using an SVG image, change the item type from "pixmap" to "svg". Now let's look at what we've just added:

<item type="pixmap">

• This item element tells GDM that we want to display an image.

<normal file="background.png"/>

• This normal element gives the name of the pixmap.

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

• This pos element tells GDM how to display the pixmap. The x attribute gives the distance from the left-hand side of the screen, and the y attribute gives the distance from the top of the screen. The height and width attributes give are given in percent of screen space. In this case, we want to cover the entire screen, so we align with the left-most pixel, 0, the topmost pixel, 0, and tell GDM to stretch the image to 100% of the screen width and height.

</item>

• This is the closing tag of the item element. Notice that because they appear inside the item tags, the other elements are "encapsulated" in the item element.

Step Four

• The one thing that we absolutely need is an entry field for the username and password. Insert the following in between the closing item tag for the background and the closing greeter tag.

<item type="entry" id="user-pw-entry">
<pos y="50%" x="50%" width="10%" height="20" anchor="c"/>
</item>

• This will tell the GDM theme that it should display a text entry field, and using the id of user-pw-entry means that the field will be used to enter the username and password. We used a new attribute in the pos element, anchor. the anchor tells GDM what part of the item to place at the x and y coordinates. in this case, we used c, for center. So the center of the user-pw-entry field will be placed at y 50% and x 50%. All other possible values for anchor are based on compass points: n, s, e, w, ne, se, sw, and nw.

If you save your work, you can set GDM to use this theme in your Login Window preferences and log out to see your progress so far. It's not very friendly, but it is functional.

Phase Three: Enhancing Usability

In the last phase we created the bare minimum of a functional theme, but not a very helpful one. you can enter the username and password, but there is no feedback as to the current state or for any errors. So in this phase we will be improving it's current state of usability.

Step One

• First change the pos anchor in the user-pw-entry item from "c" to "n" so that the pos tag will look like this:

<pos anchor="n" x="50%" y="50%" height="20" width="20%"/>  

• By changing the anchor position from center to north, it will allow us to position the next item directly above the entry box by using the same x and y coordinates, but an anchor of "s".

Step Two

• In between the last item tag and the closing greeter tag, add the following:

<item type="label" id="pam-prompt">
 <pos anchor="s" x="50%" y="50%"/>
 <normal font="Bitstream Vera Sans Bold 10" color="#ffffff"/>
 <stock type="username-label"/>
</item>

• The normal element allows us to specify the font name "Bitstream Vera Sans", to make the font "Bold", specify the font size "10" and the font color value of "#ffffff" for white. The stock element of the type username-label will insert a localized label to prompt for the username and password. If you want to test this out, you can save your XML file and log out now.

Step Three

• This will certainly be better, but there are a few more things that would help. First, what happens if the username and password authentication fails, what happens? Not much. The username-label changes back from password to username. There is a built-in error message for authentication errors. In between the last item tag and the closing greeter tag, add the following:

<item type="label" id="pam-error">
 <pos x="50%" y="-10" anchor="s" />
 <normal font="Bitstream Vera Sans Bold 10" color="#ffffff"/>
 <text></text>
</item>

• Using the y coordinate of "-10" will place the login error message 10 pixels from the bottom the screen. There is a new element in this item, the text element. Normally, you would type something in between the text tags to have it appear in the theme. In this case it is necessary to display the error message. There will be more information on text elements in the reference tables after the tutorial. If you want to test this out, you can save your XML file and log out now.

Step Four

• Another common option to add to GDM themes is a warning for timed logins. To add this message to your theme, add the following between the last item tag and the closing greeter tag:

<item type="label" id="timed-label">
 <pos x="50%" y="10" anchor="n"/>
 <show type="timed"/>
 <normal font="Bitstream Vera Sans Bold 10" color="#ffffff"/>
 <stock type="timed-label"/>
</item>

• Using the y coordinate of "-10" will place the timed login message 10 pixels from the top the screen. There is a new element in this item, show the show item. Using a show element of the type "timed" ensures that the message will only be shown when a timed login is enabled. There will be more information on the show element in the reference tables after the tutorial. If you want to test this out, you can save your XML file and log out now.

Step Five

• The last thing that we will add in this phase is a button. There are several functions that can be made available from the greeter, including the ability to select sessions, and shutting down or rebooting the computer. To add this button to your theme, add the following between the last item tag and the closing greeter tag:

<item type="rect" id="options_button" button="true">
 <pos x="-1" y="-1" anchor="se" width="box" height="box"/>
 <box>
  <item type="label">
   <normal color="#ffffff" font="Bitstream Vera Sans 10"/>
   <stock type="options"/>
  </item>
 </box>
</item>

• The item type rect will draw a rectangle that, with the options_button id and the additional attribute of button="true", will act as a button to open the options menu. The width and height of a rect item can be set like the entry item, in the pos element. You can specify the height and width in pixels, percentages, or the box value which will grow to fit the contents of the rectangle. The box element will hold our label item and is necessary to have the button show up and function. I would suggest that you save your XML file and log out now to see your progress.

Phase Four: Beautify

Phase Five: Packaging

In the last stage we put the finishing touches on our theme's appearance. For our final phase, we are going to add some final additions to make our theme complete and package it to be distributed and installed.

Step One

• We need to take a screenshot of our theme. This is a little difficult for most of us because we need to be logged in to take a screenshot. If you have xnest installed, you can choose to log in in a nested window, but the method I prefer and will show you here came straight from the art.gnome.org tutorial.

  Unfortunately we need to install a software package that does not come with Ubuntu, ImageMagick. to do this, open a terminal and type

sudo apt-get install imagemagick

• This will give us a screenshot application that can be used from the command line.

Step Two

• Next we will create a shell script to switch to the virtual terminal that GDM uses and then take a picture. In your terminal, type (or copy and paste) this:

echo "chvt 7 ; sleep 5 ; XAUTHORITY=/var/gdm/:0.Xauth DISPLAY=:0.0 import -window root /tmp/screenshot.png" > /tmp/capture

• That will create a shell script named capture in the /tmp directory. When you run the script, it will switch to your normal virtual terminal, VT7, wait five seconds, take a picture, then beep through the pc speaker on your computer's motherboard. The picture will be in the /tmp directory as well.

Step Three

• Now, how to actually run the script while logged out. First, you will need to log out. So, If you are following this howto exactly, you may need to print it out this part or take some notes for the next section. If you hold the ALT and CTRL keys at the same time, and then press the F1 key on your keyboard, you will get a login that looks something like:

Ubuntu 6.06.1 LTS You-Desktop tty1

You-Desktop Login:_

• depending on your hostname. Go ahead and login using your normal username and password, then type this:

sh /tmp/capture

and wait while the imagemagick works. The screen should change to your GDM theme, and then about five seconds later, beep. After that, it is safe to log back in to the GDM theme. If you are using a timed login, you may need to turn it off or adjust the timeout to actually get the shot.

Step Four

• Now move the picture, which is currently called screenshot.png from /tmp to your theme folder.

You will now have to add this to the GdmGreeterTheme.desktop file, As root, open it in a text editor, and Change the screenshot line so it reads:  Screenshot=screenshot.png 

• While you have it open, you may want to add any additional information, such as your name, the name of your theme, a description, and the copyright information. If you intend to distribute this theme to others, You may want to change the name of the folder your theme is in. If you do, remember to substitute your folder name for GDMTheme in the next step.

Step Five

If you just wanted to create a theme for your own use, you are done. But if you ever decide to share your work with others, this last step will help you package your theme so that it can be distributed and installed easily by others. To do this, just open up your terminal, and type:

cd /usr/share/gdm/themes/
tar -zcf GDMTheme.tar.gz GDMTheme

Your packaged theme will be the file GDMTheme.tar.gz in the /usr/share/gdm/themes/ directory.

Tips

Box as a Size Value

Optimum Wallpaper Size

Preview Image Size

• "Officially" the preview image should be 200x150 pixels. If you use a larger image, it will be scaled to 200x150 pixels when it is shown in the Login Manager preferences window. So, while there is no disastrous disadvantage to using a large preview image, it will increase the disk space that the theme occupies.

Backups

• There is no rule saying that you can't have extra files in your theme directory. If you are going to make changes that you are unsure about, or you are going to make lots of changes at once, make a copy of your XML file. If your edited theme misbehaves , you can revert back to an unaltered state.

Reference Tables

Item Types

Item Ids

Label Ids

Stock Types

Normal/Active/Prelight Attributes

Show types

Show modes

Other Resources

• There are few tutorials (that I have found) for GDM themes on the web. Along with a basic understanding of XML, I found this site to be extremely useful when I started writing GDM themes:

  • http://live.gnome.org/GnomeArt/Tutorials/GdmThemes - The home of the official Gnome Tutorial for GDM themes

  But, by far, the best resource that I have found is just looking at other peoples themes. Read through the XML, try to isolate a part of the theme that you like, extract it, and use it in your own theme. If it isn't quite what you want, modify it until it is. Just remember to test often. There is nothing worse than making extensive changes to your theme, only to realize that somewhere in there is a single line, or even a single character that causes a spectacular failure in display manager.

  Another very useful resource is within the documentation. Here is the portion pertaining to GDM greeter theming:

  • http://www.gnome.org/projects/gdm/docs/2.14/thememanual.html

Comments

• -- TroySobotka DateTime(2006-09-05T03:50:11Z) I just recently found out about the "scale" option for the <pos /> as in <pos x="50%" y="33%" width="scale" height="15%" anchor="c"/> to properly scale your image regardless of screensize. Perhaps you could find a location for that. This document is turning out beautifully. Please email me when you get a chance. Thanks!