How-to Customizing and theming Maemo

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
	qgn_plat_clock_analog_plain.png	100x90
	qgn_plat_clock_analog_am.png	100x90
	qgn_plat_clock_analog_pm.png	100x90

Digital Clock:

Preview	File name	Size
	qgn_plat_clock_digital_background.png	100x90
	numbers from 0 to 9 normal and focused: qgn_plat_clock_digital_display_number_0.png qgn_plat_clock_digital_display_number_0_focused.png	16x30
	qgn_plat_clock_digital_display_separator.png	16x30
	2 images on for normal other for focused state qgn_plat_clock_digital_label_am.png qgn_plat_clock_digital_label_am_focused.png	30x20
	2 images on for normal other for focused state qgn_plat_clock_digital_label_pm_focused.png qgn_plat_clock_digital_label_pm_focused.png	30x20

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: /home/user/.fonts/

After that your fonts will be available on the font selector dialog. To change the fonts used by the whole system, you should modify it on your theme.xml file explained in the Understanding the Maemo UIsection.

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

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

Icon	File name	Icon	File Name
	qgn_stat_gatewayconn_connected.png		qgn_stat_gatewayconn_notselected.png
	qgn_stat_gatewayconn_connected.png		qgn_stat_gatewayconn_flightmode.png

Telephone connection icon listing

      gtk-20/
          gtkrc
          gtkrc.cache
      images/
          *.png
      matchbox/
          theme.xml
      index.theme
     

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

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


   

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

Type=X-Hildon-Metatheme
  	Name=YourThemeName
  	Icon=/usr/share/themes/YourThemeFolderName/images/qgn_plat_theme_thumbnail.png
  	Encoding=UTF-8
  	
  	[X-Hildon-Metatheme]
  	GtkTheme=YourTheme
  	IconTheme=default
  	X-MatchboxTheme=YourTheme
  	X-OperaSkin=default.zip // this will only exist on the product firmware
  

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:
   
   
   
   /home/user/.osso/current-gtk-theme
   
   
   
   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

Uou 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 at: www.marceloeduardo.com/me/files/personalization_0.1_all.deb
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

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 [8] and in the UI style guide[9]

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. Hacking 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[10]. 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" />
    

or

  < 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" />
    

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 -->
    
    </theme>
    

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.

TitleBar

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:

       
<!-- 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>
  <button x="-40" y="2" w="40" h="40" action="close" >
    <active pixmap="titlebarclosebuttonpressed" />
    <inactive pixmap="titlebarclosebutton"/>
  </button>
<!-- 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"
   type="sublabel"/>
</frame> 

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

Dialogs

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
	qgn_plat_dialog_frame_corner_top_left.png	51x51
	qgn_plat_dialog_frame_corner_top_right.png	51x51
	qgn_plat_dialog_frame_corner_bottom_left.png	20x20
	qgn_plat_dialog_frame_corner_bottom_right.png	20x20
	qgn_plat_dialog_frame_tile_left.png	10x2
	qgn_plat_dialog_frame_tile_right.png	10x2
	qgn_plat_dialog_frame_tile_top.png	2x51
	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.[10]

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[11] 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:

The main view uses the following images:

Preview	File name	Dimensions
	qgn_plat_application_frame_bottom.png	50x24
	qgn_plat_application_frame_right.png	24x2
	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.

Tasknavigator

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	80x90
	qgn_plat_task_navigation_button_02_normal.png	80x90
	qgn_plat_task_navigation_button_03_normal.png	80x90
	qgn_plat_task_navigation_skin_01.png	80x10
	qgn_plat_task_navigation_application_switcher_01_normal.png	80x38
	qgn_plat_task_navigation_application_switcher_02_normal.png	80x38
	qgn_plat_task_navigation_application_switcher_03_normal.png	80x38
	qgn_plat_task_navigation_application_switcher_04_normal.png	80x38
	qgn_plat_task_navigation_application_switcher_05_normal.png	80x38
	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