Work In Progress! |
Contributions welcomed! |
Currrent Status |
Adding Content 70% |
- 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 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 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
- The rule of thumb here is that a scaled-down image usually looks better than a scaled-up image. It is also wise to keep in mind different aspect ratios; a 1280x1024 image might look a little strange on a 1280x800 screen. Personally, I always try to use abstract SVG images for my backgrouds.
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 |
Disconects from a remote login. |
clock |
Used with the label id clock to display a constantly updated time |
caps-lock-warning |
Displays a warning when caps-lock is on. |
timed-rect |
Used in conjunction with the timed-label label id. |
timed-label |
Used in conjunction with the timed-label label id. |
pam-prompt |
Displays a prompt fo the username and password. |
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 |
Displays a verbose prompt fo the username. |
pam-error |
Displays an error on failed login |
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 |
Quits GDM when attempting a second login. |
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:
http://live.gnome.org/GnomeArt/Tutorials/GdmThemes - The home of the official Gnome Tutorial for GDM themes
Another very useful resource is within the documentation. Here is the portion pertaining to GDM greeter theming:
Comments
-- TroySobotka 2006-09-05 03:50:11 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!
-- Pyrotica I'll try to get that into the unfinished tutorial stage. I'd write, but I can't find your contact info. If you want, you can contact me. I the means to do so are on my wikipage.