GdmThemeing
ContentsBRTableOfContents |
Work In Progress! |
Contributions welcomed! |
- The intent of this page is to offer an explination 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 Gnome Display Manager, refered 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 explanitory. 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 apperance 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 freind. Really. The stock element will display common labels in the systems prefered 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 feild 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 feild 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 feild 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 Useability
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 disasterous 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 unatered 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 feild. 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 freindly 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 |
Dispalys 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. |
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 seperating 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 extreemly useful when I started writing GDM themes:
http://live.gnome.org/GnomeArt/Tutorials/GdmThemes - The home of the official Gnome Tutorial for GDM themes
Other Links
Gnome Display Manager Reference Manual - [http://www.gnome.org/projects/gdm/docs/2.14/thememanual.html Themed Greeter]