Customizing maemo user interface

A Quick Start with Hildon Theme Tools

A quick way to create a new theme is to use hildon-theme-tools package, which is available for Scratchbox and Ubuntu desktop. First, you must install both hildon-theme-tools and hildon-theme-layout-4 packages in order to be able to create, edit and package your theme.

After installing the packages you have the command 'hildon-theme-bootstrap' available. Run it in command line and you'll be asked some basic questions about your theme. It will create a new theme directory and fetch the current basic theme from subversion (N.B. if you run on a desktop machine instead of Scratchbox, you need to install also subversion in order to make things work. In Scratchbox this tool is already available). Here is an example of running hildon-theme-bootstrap (user commands in red):

$ hildon-theme-bootstrap
Theme bootstrap tool by Michael Dominic K.
Copyright 2007 by Nokia Corporation.

This tool will bootstrap a new theme directory structure.

Which layout do you want to use?
1) hildon-theme-layout-3
2) hildon-theme-layout-4
#? 2

What's the theme name? [ie. My Theme]
#? Theme 1

What's the theme directory? [ie. mytheme]
#? theme1

What's the author name? [ie. John Doe]
#? Mr maemo

What's the author's e-mail? [ie. john_doe@gmail.com]
#? xxxx@maemo.org

Summary:

Theme name      : Theme1
Layout          : hildon-theme-layout-4
Package name    : hildon-theme-theme1
Theme directory : theme1 [/usr/share/themes/theme1]
Author          : Mr maemo 

Is this correct? [y/n]
#? y
Fetching source from subversion repository...

After that you will have folder called hildon-theme-theme1. It contains some files, out of which the most important is template/template.png, containing the theme graphics. You're free to edit it with your favourite graphics editor.

When done with editing, you must make a theme package. In order to make the package, change to the directory containing your theme and run the packaging command as follows:

$ cd hildon-theme-theme1
$ dpkg-buildpackage -rfakeroot -b

If everything went fine, you should have hildon-theme-theme1_VERSION.deb file in the parent directory. The file can be transferred to the device and installed with Application Manager.

Now you're done with the customization of the theme, if you wish you can proceed with manual editing process to gain a full access on theme layouts.

For a more thorough tutorial on hildo-theme-tools, visit the following link: Hildon Theming Overview

The theme package automatically installs its contents to /usr/share/themes on the device.

Image reference with pixel sizes for manual customization (Plankton theme)

The images of the theme reside on the device on the following folder: /usr/share/themes/[Theme name]/images, for example:
/usr/share/themes/plankton/images

Specifications of images are presented on a separate page. Click here to see the theme image index.

Customizing Icons

In order to customize Task Navigator, Status Bar, Control panel and other icons you must manually change the icons located in the device. The icons that come with maemo SDK (and that are included on the icon index part of this document) are not the same ones than you can see on the device. If you want to change just couple of icons and not all of them, please make sure that you install only those and do not install the whole icon set from the maemo SDK because it overwrites the product icons with a less polished set which is not a recommended thing to do.

Task Navigator Icons

The main icons used in maemo, such as Internet browser, Application menu, Mail and the status bar icons can be modified just by changing the images in the following directory: /usr/share/icons/hicolor/scalable/hildon/

The icons can be customized by changing the following images. Again, the original ones should be backed up first. Also, the same file format and image size should always be used. All icons are 8-bit, 64x54 pixels .png images.

Preview	Description	File name
	Contacts	qgn_grid_tasknavigator_contact.png
	Active Contact	qgn_grid_tasknavigator_contactactive.png
	Mail / Inbox	qgn_grid_tasknavigator_inbox.png
	New message	qgn_grid_tasknavigator_newmessage.png
	Sending / Receiving	qgn_grid_tasknavigator_sendrecieve.png
	Web Browser	qgn_grid_tasknavigator_web.png
	Others / Menu	qgn_grid_tasknavigator_others.png

Status bar icons

Also the status bar icon can be customized. Battery status, volume status, connection and phone are multiple state icons, so every single state image should be customized.

Files are located in the directory /usr/share/icons/hicolor/40x40/hildon/

Icon	File name	Icon	File Name
	qgn_stat_battery_full100.png		qgn_stat_displaybright4.png
	qgn_stat_battery_full75.png		qgn_stat_displaybright3.png
	qgn_stat_battery_full50.png		qgn_stat_displaybright2.png
	qgn_stat_battery_full25.png		qgn_stat_displaybright2.png
	qgn_stat_battery_low.png		qgn_stat_usbact.png
	qgn_stat_battery_verylow.png		qgn_stat_alarmact.png

Battery, Brightness, USB and Alarm icons listing.

Icon	File name	Icon	File Name
	qgn_stat_internetconn_generic.png		qgn_stat_volumelevel4.png
	qgn_stat_internetconn_adhocwlan.png		qgn_stat_volumelevel3.png
	qgn_stat_internetconn_datacall.png		qgn_stat_volumelevel2.png
	qgn_stat_internetconn_packetdata.png		qgn_stat_volumelevel1.png
	qgn_stat_internetconnection_no.png		qgn_stat_volumelevel0.png
	qgn_stat_volumemute.png

Connection and volume icon listing

Image reference with pixel sizes for manual customization of icons

The images of the theme reside on the device under the following folder: /usr/share/icons/hicolor/ under the following subfolders:

    scalable/hildon
    40x40/hildon
    250x250/hildon
    26x26/hildon
    12x12/hildon
    34x34/hildon
    50x50/hildon
    16x16/hildon
    

Specifications of images are presented on a separate page. Click here to see the icons image index.

Designer's task: draw new icons with exactly same sizes as the original ones and save them on the place of the original ones with exactly same file names (please see the icon index for reference).

Programmer's task: Please see the maemo debian packaging tutorial to understand how to create the package that installs the files on correct locations and that is installable with the Application Manager. It is recommended that the theme package only replaces the customized icons and not the whole set unless all the icons are new ones and the customization is not limited changing just couple of icons.

Editing Theme Layouts Manually

This chapter explains how to edit theme layouts manually. This allows broader customization of the device extending beyond mere modification of graphical elements.

Editing layout files enables the modification of the following:

• Font sizes and styles
• Widgets parameters (spacings, margins, distances)
• Hildon desktop parameters (Task Navigator size, place etc.)

N.B. Note that the modification of colors and graphical elements is easier with hildon-theme-tools than by manipulating layouts. This should be sufficient for most customization needs.

Layouts can be edited either by modifying already existing layouts or creating custom layouts. For instance, in order to apply changes to the package created by hildon-theme-tools you can edit files under /usr/share/hildon-theme-layout-4, if hildon-theme-layout-4 has been installed. The layout files for the selected layout are used for the theme created by hildon-theme-tools. If you want easily installable themes, it is the preferred way to edit these files.

Theme Files

After installation, all maemo themes are located in the following directory: /usr/share/themes/[Theme_name]

All themes share the same structure, having a pretty straightforward meaning:

      gtk-2.0/
          gtkrc
          gtkrc.maemo_af_desktop
      images/
          *.png
      matchbox/
          theme.xml
      index.theme
    

Theme.xml

Some simple window decoration customization can be achieved by modifying the theme.xml. In the maemo platform, the theme.xml defines the main title bar decoration and some dialog decoration as well. More information on theme.xml files can be found in the Matchbox themes tutorial.

Basic Resources

There are three basic resources in a theme.xml file: colors, fonts and pixmaps. All of them have to be declared before using. The syntax is pretty straightforward:

For colors:

 
    <color id="lowlightcol" def="#d4e6fd80" />
    

basically it is an "id" followed by a definition, the element real value.

For fonts:

      
    <font id="osso-TitleFont" def="Nokia Sans-16.75:30px" />
   

or

  
    <font id="osso-TitleFont" def="Nokia Sans,fixed bold 16.75" />
    

again, an id and a definition. In font elements, alternative fonts can be defined by separating them with "|" (pipe). The first match will be used.

For Pixmaps ( images ):

      
    <pixmap id="dialoguptile" filename="../images/qgn_plat_note_frame_tile_top.png" />
    

Id followed by a filename, pointing to a png image.

An example of a layout file can be seen in the hildon-theme-layout-4 package.

gtkrc customization

After modifying theme.xml and the basic images and fonts, the next step on maemo customization and theme creation is to modify the GTK resource file and the resources used by it. This will enable changing the visuals for almost everything else in the system, including the Hildon widgets.

Even with the gtkrc file giving control over some important things, it is recommended to modify only the images in the folders that are used by the gtkrc file. The gtkrc file is too big to describe in full detail in this document.

N.B. It should be noted again, that the most important GUI elements can be modified using the hildon-theme-tools template.

Modifying System-Wide Colors

Some sections of the gtkrc file have to be changed to match the colors of the theme. Most color definitions are located in the beginning of the file. N.B. Be careful not to enter invalid values. If possible, always test on your Scratchbox first.

Modifying System-Wide Fonts

In addition to the colors, the gtkrc file can be modified to make some custom fonts to work on UI. Again, it is very important to use the correct font name and size, or the rootfs may be damaged.

     
style style-Identifier{ font_name="Font Name size"}

Sample of font definition:

style "osso-SystemFont" { font_name = "Nokia Sans 16.75"}

and font usage:

 
class "*GtkComboBox" style "osso-SystemFont"

N.B. This is just a very simple introduction to gtk resource files. The GTK documentation should always be checked, if there are any doubts about the resource files.

Distributing Themes

Themes can be distributed as an Application Manager ready package. This will make it easier for the end users to install and uninstall themes. Themes created using the hildon-theme-tools skeleton are instantly ready for building the package using dpkg-buildpackage -rfakeroot as described above. The resulting .deb file can be then installed on the device using Application Manager by the user.

Adding New Fonts

First step is to create a fonts folder for the user:

cd /home/user/
mkdir .fonts
      

Adding new fonts is pretty simple: the font files ( .ttf or type1) are to be placed in the fonts folder located on:

/home/user/.fonts/
      

To update the font cache, the command fc-cache -fv should be run in the .fonts directory.

To change the fonts used by the whole system, theme.xml file should be modified, as was explained in the document.