How-to: Customizing and theming maemo

This document is released under the GPL license.

Goal:This how-to intends to show how theming works on maemo and how basic customization can be done.

Target audience: Designers interested on customizing maemo and developers interested to know how theming works.


  • Familiarity with maemo platform
  • Xml and Xml-like file editing
  • Connecting to your Device via SSH


Maemo uses Matchbox as window manager on top of the X server. This show you some basic possibilities to understand maemo themeing. This document will give your a more deep look at customization and even show you some ways to go deeper on customizing maemo.

For basic customization, you are able to for example, just change graphics and sounds by replacing the original file. This is not the best way to do it, but it will enable basic customization for end users. This kind of customization will be listed on the Basic Customization Section bellow. Feel free to send us your customization tips.

In order to create new Themes, this document will show how to create a basic theme by modifying the default theme and then how to test it on the fly. This section of this document uses a lot of information from the Matchbox theming tutorial.

Connecting to your maemo device

The themes and most of customizable images are located on the /usr/share/themes/ folder , so in order to be able to test most of the customization you will need to connect to your maemo device using SSH via USB or Wi-FI. Please refer to the others maemo how-tos if you don't know how to do it.

Also if you want to customize your Internet Tablet device, with the "Product" firmware, you'll need to become root and then install some packages before going on : X-terminal and SSH and be sure to enable RD Mode on your device. There are some UI customizations only available on the Product firmware. These options will be shown here with the icon: this shows that
      this topic is about the product firmware.

Basic Customization

Most of these basic customizations are made simply by replacing original files or editing default configuration files. These kind of customization is not recommended for real Theme creation, so please make backup copies of any file before modifying it to avoid any problems.

Home screen : Clock Applet

To customize the clock you need only to change the following images, all of them located on the following folder : /usr/share/themes/ThemeName/images/

Analogic Clock

Preview File name Size
Analog clock qgn_plat_clock_analog_plain.png 100x90
Analog clock qgn_plat_clock_analog_am.png 100x90
Analog clock qgn_plat_clock_analog_pm.png 100x90

Digital Clock:

Preview File name Size
Digital clock qgn_plat_clock_digital_background.png 100x90
Digital clock numbers from 0 to 9 normal and focused:



Digital clock qgn_plat_clock_digital_display_separator.png 16x30
Digital clock 2 images on for normal other for focused state
Digital clock 2 images on for normal other for focused state

Adding new fonts

First you need to create the user's fonts folder:

cd /home/user/
mkdir .fonts

To add new fonts is pretty simple: just place your font files ( .ttf or type1) in the fonts folder located on:


To update the font cache run the command fc-cache -fv in your .fonts directory.

To change the fonts used by the whole system, you should modify it on your theme.xml file explained in the Understanding the maemo UI section.

Task Navigator Icons

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

The Mail and Browser icon are only available on the product firmware.

You can customize the icons by changing the following images. Again, don't forget to back them up first and always use the same file format and image size. All icons are 8bit, 64x54 pixels png images.

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

Status bar icons

You can also customize the status bar icon. Battery status, volume status, connection and phone are multiple state icons so be sure to customize every single state image.

Files are located on the folder: /usr/share/icons/hicolor/40x40/hildon/

Icon File name Icon File Name
full battery qgn_stat_battery_full100.png brightness 4 qgn_stat_displaybright4.png
75% battery qgn_stat_battery_full75.png brightness 3 qgn_stat_displaybright3.png
50% battery qgn_stat_battery_full50.png brightness 2 qgn_stat_displaybright2.png
25% battery qgn_stat_battery_full25.png brightness 1 qgn_stat_displaybright2.png
battery low qgn_stat_battery_low.png USB active qgn_stat_usbact.png
battery very low qgn_stat_battery_verylow.png Alarm active qgn_stat_alarmact.png

Battery, Brightness, USB and Alarm icons listing.

Icon File name Icon File Name
internet connection qgn_stat_internetconn_generic.png volume 4 qgn_stat_volumelevel4.png
Ad hoc Wlan qgn_stat_internetconn_adhocwlan.png volume 3 qgn_stat_volumelevel3.png
Internet connection data call qgn_stat_internetconn_datacall.png volume 2 qgn_stat_volumelevel2.png
Internet connection packet data qgn_stat_internetconn_packetdata.png volume 1 qgn_stat_volumelevel1.png
no internet connection qgn_stat_internetconnection_no.png volume 0 qgn_stat_volumelevel0.png
. . volume mute qgn_stat_volumemute.png

connection and volume icon listing

Icon File name Icon File Name
internet connection qgn_stat_gatewayconn_connected.png volume 4 qgn_stat_gatewayconn_notselected.png
Ad hoc Wlan qgn_stat_gatewayconn_connected.png volume 3 qgn_stat_gatewayconn_flightmode.png

Telephone connection icon listing

Advanced customization: Theme creation

Now its time to start the real customization. Creating themes is not difficult, but it takes a little bit of time to theme every single themeable element on the platform.This how to will show you how to customize the most important elements. This will allow will to understand how theming works on maemo and how a complete new skin can be created.

all maemo themes are located on the following directory: /usr/share/themes/[Theme_name]

All themes must share the same structure and it has a pretty straightforward meaning:


Starting a custom Theme

To start your first theme in the simplest way, you should create a new dir, with your theme name, and then copy the files from the default theme to it. The Default maemo theme is the best way to start your theme. In the future a better guideline can be developed and be published on the site, but for now the default theme is the best starting point.

Steps for starting your new theme. Which we are going to name "Golden":

      :~# cd /usr/share/themes/
      :/usr/share/themes# mkdir Golden

and then copy everything from the default theme:

    :/usr/share/themes# cp -r default/* Golden/<br></br>

You can now start customizing the new theme. In this how-to will only make the new theme a variation of the Default theme but with a new color (you can download the theme used in this example from: You could also use your favorite editor to change the image's color/saturation/hue as you like, and then copy the images back to the folder images.

After downloading or creating your new images, it's time to send them to your theme folder with a SCP command or copying to a mmc and then moving it to the /usr/share/themes/Golden/images/ folder.Now you need to make some changes on the theme's theme.xml file:

Open the file theme.xml on the matchbox folder of your theme's directory and change the first line:

 <theme name="YourThemeName" author="YourNameHere" desc="" version="1.0" engine_version="1" >

Now open the file index.theme on the your theme directory and change the following items:

  	X-MatchboxTheme=YourTheme // this will only exist on the product firmware

Save it and close it.

Testing your Theme

If you are using the product firmware, use the personalization tool in the control panel or the personalization item in the home screen's main menu.

If you are in the maemo SDK version you can:

Do it manually in the shell (x-term) or ssh:

  1. Edit the following file:


    Change the only line to point to your theme:

    include "/usr/share/themes/Golden/gtk-2.0/gtkrc"

  2. Run the following commands in the shell:
    export DISPLAY=:0
    matchbox-remote -keys-reload
    matchbox-remote -t YourThemeName
    reboot your device ( tasknavigator, background and statusbar reload)

Use the free theme changer

You can use this simple theme change to avoid typing that in the shell and when editing the theme directly on the device.

  1. Get the theme changer .deb package from : (Note: Request package personalization_0.1_all.deb directly from Marcelo Eduardo)
  2. Install it using the application installer
  3. Run it from the application menu -> extra -> personalization

This is how your theme looks like:

Golden theme in action

Golden theme in action

Now you are able to the see the differences and test your theme. Go to some complex application and see if everything is running fine.

Understanding the maemo UI: Theme.xml

So now you have your theme running, but batch editing only change images colors or saturation is nothing like real theming. To be able to do real themes you must understand how the main GUI elements in maemo are built and how they relate to each other.

All these Elements (controls not included) are defined in the gtkrc file and in the theme.xml. First, a simple overview of maemo GUI:

Maemo GUI overview

You can check out more about the maemo UI on the maemo Tutorial - Gui applications and in the UI style guide

This shows how a basic theme can be created by modifying the default theme. But if you want to go further you will need to tweak this theme.xml for real.

The theme.xml file

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 dialogs decoration as well. You can also refer to the Matchbox theming tutorial for more info about theme.xml files.

Basic resources

There are 3 basic resources in a theme.xml file: colors, fonts and pixmaps. You need to declare them all before using. The syntax is pretty straightforward:

For colors:

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

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

For fonts:

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



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


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

You must use a valid font. To avoid problems, use the '|' to let the default Nokia sans font as second alternative: def="your Font,fixed bold 16.75 | Nokia Sans,fixed bold 16.75"

For Pixmaps ( images ):

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


Plain simple: Id followed by a filename, pointing to a png image.

Example of a simple theme.xml file:

    <?xml version="1.0"?>
    <theme name="Golden"

         author="Marcelo Oliveira"
           desc="First maemo variant theme" 
        version="1.0" engine_version="1">
    <color id="lowlightcol" def="#d4e6fd80" />

    <font id="osso-TitleFont" def="Nokia Sans-16.75:30px" />
    <pixmap id="titlebarclosebutton" filename="../images/qgn_plat_button_close_normal.png" />

    <pixmap id="titlebarclosebuttonpressed" filename="../images/qgn_plat_button_close_pressed.png" />
    <!-- frame definitions will go here -->

Customizing Matchbox Frames

Now you can start modifying the Matchbox frames elements. In maemo this will allow will to modify the main title bar and the dialog decorations. These modifications will allow you to make real modifications also on the minimize and close buttons and application menu launch area.


The main title bar is always visible (when not in the fullscreen mode) and gives you the: foremost application's menu, the background for the status bar and the close and minimize buttons. The code for the title bar (default theme) is defined in the following section of the theme.xml file:

Title bar

<!-- Main windows title bar. You need to define its height -->
<frame id="main" height="60">
  <layer x="0" y="0" w="720" h="60"  type="pixmap" pixmap="applicationtopbararea"/>

  <layer x="35" y="8" w="283" h="30"  type="label" color="osso-TitleTextColor" justify="left" font="osso-TitleFont" />

  <!-- Define the area that launches application menu -->
  <button x="3" y="0" w="315" h="60" action="custom" options="inputonly,pressonly" />

  <!-- Define the status bar applet panel -->
  <panel x="-372" y="2" w="280" h="40" />

  <!-- Define minimize and close buttons -->
  <button x="-80" y="2" w="40" h="40" action="minimize" >

    <active pixmap="titlebarminimizebuttonpressed"/>
    <inactive pixmap="titlebarminimizebutton"/>
  <button x="-40" y="2" w="40" h="40" action="close" >

    <active pixmap="titlebarclosebuttonpressed" />
    <inactive pixmap="titlebarclosebutton"/>
<!-- w="127" is result of trial and error testing and limits the maximum
     width of the whole title area to the value specified. It is quite
     possible that this is not the exactly correct value. -->

  <layer x="labelend+27+6" y="9" w="127" h="30"


Remember that pixmaps and others resources as colors and fonts are defined in the beginning of the file.


The next frame element defined in the theme.xml file is the Dialog. It defines the look and fell using the following images:

Preview File name Dimensions
Dialog frame corner top left qgn_plat_dialog_frame_corner_top_left.png 51x51
New Message qgn_plat_dialog_frame_corner_top_right.png 51x51
Sending and Receiving messages qgn_plat_dialog_frame_corner_bottom_left.png 20x20
New Message qgn_plat_dialog_frame_corner_bottom_right.png 20x20
New Message qgn_plat_dialog_frame_tile_left.png 10x2
New Message qgn_plat_dialog_frame_tile_right.png 10x2
New Message qgn_plat_dialog_frame_tile_top.png 2x51
New Message qgn_plat_dialog_frame_tile_bottom.png 2x10

Images used in the dialogs.

Please refer to the Matchbox tutorial to learn more about modifying the supported window types.

Titlebar and Dialogs Fonts customization

After placing custom fonts on your fonts folder, you can know modify the theme.xml to make those fonts the default fonts in the system. The following resources define the system fonts for:

Lines 29 to 32:

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

        <color id="osso-DialogTitleTextColor" def="#ffffff" />
You must use a valid font. To avoid problems, use the '|' to let the default Nokia sans font as second alternative: def="your Font,fixed bold 16.75 | Nokia Sans,fixed bold 16.75"

gtkrc customization

After modifying your theme.xml and the basic images that are used to create the main toolbar background and decoration for dialogs, the next step on maemo customization and Theming is to modify the GTK resource file and the resources used by it. This will enable you to change the visual of the almost everything else in your system, including the Hildon widgets.

Even with the gtkrc file giving you control over some important things, it's recommended to modify only the images on your folders that are used by the gtkrc file.The gtkrc file is to big to describe on full details on this how to. This document will keep to showing the most important UI elements components. It will list the images that compose. Customize them to improve more your theme.

Modifying System-Wide Colors

You will need to change some sections of the gtkrc file to match your theme's colors. Most color definitions are located in the beginning of the file. Be careful to do not enter invalid values. if possible always test it on your Scratchbox first. Color definitions are located in the following lines:229 to 280

Modifying System-Wide Fonts

Like the colors, you can modify the gtkrc file to put some custom fonts to work on UI. Again it is very important to use the correct font name and size or you can damage your rootfs. Font definitions are located in the following lines: 282 to 322

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"

Note that this is just a very simple introduction to gtk resource files. You should always refer to the GTK documentation [12] if any doubts about resource files comes out.

Modifying the main View / home view

The main view is the first thing you should customize. It has the basic "decoration" that your theme will use and still pretty simple. This view is composed by only the border around the main elements in this screenshot:

Main view

The main view uses the following images:

Preview File name Dimensions

Dialog frame corner top left

qgn_plat_application_frame_bottom.png 50x24

New Message


Sending and Receiving messages

qgn_plat_application_frame_left.png 24x2

And is defined in the following section of the gtkrc file: line: 4012 style "osso-appview-background"

Pay attention to how the engine cuts the application_frame_bottom.png. The engine grabs the tile for the whole bottom and the lower corner on the left from the same image.


The Task Navigator is located in the left side of the screen. It provides fast access to the most important one-hand use cases such as launching new applications, switching between them, going to a bookmarked web page, or reading incoming email messages.


It uses the following images on it's normal state:

Preview File name Dimensions
qgn_plat_task_navigation_button_01_normal.png qgn_plat_task_navigation_button_01_normal.png 80x90
qgn_plat_task_navigation_button_02_normal.png qgn_plat_task_navigation_button_02_normal.png 80x90
qgn_plat_task_navigation_button_03_normal.png qgn_plat_task_navigation_button_03_normal.png 80x90
qgn_plat_task_navigation_skin_01.png qgn_plat_task_navigation_skin_01.png 80x10
Sending and Receiving messages qgn_plat_task_navigation_application_switcher_01_normal.png 80x38
qgn_plat_task_navigation_application_switcher_02_normal.png qgn_plat_task_navigation_application_switcher_02_normal.png 80x38
qgn_plat_task_navigation_application_switcher_03_normal.png qgn_plat_task_navigation_application_switcher_03_normal.png 80x38
qgn_plat_task_navigation_application_switcher_04_normal.png qgn_plat_task_navigation_application_switcher_04_normal.png 80x38
qgn_plat_task_navigation_application_switcher_05_normal.png qgn_plat_task_navigation_application_switcher_05_normal.png 80x38
Sending and Receiving messages qgn_plat_task_navigation_skin_02.png 80x10

In the SDK version the Tasknavigator is placed a little bit above, so the first and second images doesn't appear. The Tasknavigator is defined in the following section of the gtkrc file: line: 5255 style "osso-navigator-button-one"

Full Customization: Widgets

All Widgets images are located inside the images folder on each theme. So, if you want to customize them too, just browser the images, modify and replace in your folders themes. For this simple customization, do not change image's size and always save them as 8 bit pngs.

Distributing themes

Now you are be able to distribute your theme as an application installer ready package. this will make easier for end users to install and uninstall themes.

In the previous version of maemo, the themes could only be installed manually. Today you can set the correct installation path to your .deb package.

You can also distribute your themes is like an tar.gz file containing your theme folder and it's structure. The user just need to untar the files in the themes folder and activate the theme. Please refer to the "Testing your theme section".

More to come

This is only the start point for themeing maemo. expect more information in the future. We would also like to hear about other customizations from you on the maemo Wiki

Improve this page