GdmThemeing

Revision 41 as of 2006-08-26 03:59:21

Clear message

Work In Progress!

Contributions welcomed!

  • 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.

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

[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. 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].

Phase One: The Setup

  • As I said, you will need to be able to execute commands as root. In particular, you will need to install GDM themes, changed the default theme, and write files to the theme directory in /usr/share/gdm/themes/ 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

  • At first we are only going to create the bare minimum of a 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="24" 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 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

Phase Four: Beautify

Phase Five: Packaging

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

Type

entry

A text entry field.

list

A list widget.

label

A text label. This item must contain a text or stock element.

pixmap

A pixmap image. Use a normal element inside of the item element to give image file name.

rect

Draws a rectangle. Use the normal element to describe appearance.

svg

An SVG image. Use a normal element inside of the item element to give image file name.

Item Ids

Id

Description

Buttons

Buttons can be used with the rect item type. They require the additional item attribute of button="true" to function.

language_button

Opens the language menu.

session_button

Opens the session menu.

system_button

Opens the system menu.

disconnect_button

clock

caps-lock-warning

timed-rect

timed-label

pam-prompt

user-pw-entry

The username and password entry field. Requires an item type of entry.

userlist

Displays a list of usernames and photos. Requires an item type of list.

pam-message

pam-error

Label Ids

id

Description

clock

Displays the date and time.

pam-prompt

Displays a friendly prompt for the username, password, etc..

pam-error

Displays login errors.

pam-message

Displays messages about the state of an account

timed-label

Displays a message describing automatic login. This item should always encapsulate a element of show with the attribute type="timed".

Stock Types

Type

Description

caps-lock-warning

displays a warning if your caps lock is on.

chooser

Displays a label for the chooser_button.

disconnect

Displays a label for the disconnect_button.

halt

Displays a label for the halt_button.

language

Displays a label for the language_button.

quit

reboot

Displays a label for the reboot_button.

session

Displays a label for the session_button.

suspend

Displays a label for the suspend_button.

system

Displays a label for the system_button.

timed-label

Displays "USERNAME will login in NUMBER seconds" when a timed login is used.

username-label

Displays a username prompt, and once the username is entered, it changes to a password prompt.

welcome-label

Displays the system welcome message, which can be configured in the Login Window preferences panel.

Normal/Active/Prelight Attributes

color

Accepts hex colors with a preceding hash (#) mark. When placed inside of a rect item, it gives the background color. When placed inside of a label item, it gives the font color.

alpha

Specifies the opacity: fully opaque would have a value of 0.0; fully transparent, a value of 1.0. If the alpha tag is not used, 0.0 is assumed.

font

Specifies the font and font size for label items. Text can also be made bold and/or italic. Example: font="Sans Bold Italic 12"

file

Specifies the file name for an image in pixmap and svg items. Relative pathnames are assumed to be in the same directory as the theme .xml file

tint

Specifies a tint color in hex. This will tint an image when it is encapsulated by a pixmap item. This is extremely useful when used with the active and prelight elements.

Show types

chooser

Show if the chooser button is enabled.

config

Show if the configuration is enabled.

halt

Show if halt is enabled.

reboot

Show if Reboot is enabled.

suspend

Show if suspend is enabled.

system

Show if system is enabled.

timed

Show if a timed login is enabled.

Show modes

Multiple modes

You can list more than one mode by separating them with commas

console

Show in console mode.

console-fixed

Show in console non-flexi mode.

console-flexi

Show in console & flexi mode.

flexi

Show in flexi mode.

remote

Show in remote mode.

remote-flexi

Show in remote & flexi mode.

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: 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.