• ThemeGuide

Moblin Theme Guide (0.7)

---

• Contents

  1. Overview
     1. Available Theming Subsystems
        1. Widget (GTK+2) Themes
           1. Hierarchy or Structure of GTK+2 Resource Files, and Orders of Precedence
        2. Window Manager (Matchbox) Themes
           1. Matchbox
           2. Compiz
        3. Icon Themes
        4. Desktop (Hildon or Gnome) Themes
        5. Boot Splash Themes
  2. Guidelines for Moblin Theming
     1. Put it in Perspective - Target Screen Resolutions
     2. Size Doesn't Matter - Icon and Font Sizing Recommendations
     3. Touch of Class - Considerations for Finger-Based Input Methods
  3. How To Theme Moblin
     1. Moblin Startup
     2. Icon Locations for Hildon
     3. Changing the Screen Background
     4. Changing the Sounds
     5. Adding or Changing Fonts
     6. List of Moblin Customizations Applied to Maemo Themes
     7. Theme Tools
        1. Hildon Theme Tools - Creator or Cutter
        2. ThemeMaker
        3. Theme Selector or Manager
           1. gtk-theme-switch
        4. Theme Testing
  4. Application Developers Guide to Themes in Moblin
  5. Theme Developers Guide to Themes in Moblin
     1. HOWTO: Customizing Existing Themes
     2. HOWTO: Create a New Theme from Scratch
  6. Useful Links
  7. Miscellaneous Notes:
     1. Paths and Resources, Listed in Order of Precedence
  8. Glossary

---

• Legal Disclaimer

INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL^® PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN INTEL'S TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS, INTEL ASSUMES NO LIABILITY WHATSOEVER, AND INTEL DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT. Intel products are not intended for use in medical, life saving, or life sustaining applications.

• Intel may make changes to specifications and product descriptions at any time, without notice.

Designers must not rely on the absence or characteristics of any features or instructions marked "reserved" or "undefined." Intel reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them.

Contact your local Intel sales office or your distributor to obtain the latest specifications and before placing your product order.

Intel and the Intel logo are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

*Other names and brands may be claimed as the property of others.

Copyright © 2008, Intel Corporation

---

1. Overview

Moblin is the Mobile & Internet Linux* Project. which is an umbrella, open source project focused on the development of Linux for Intel-based devices Moblin is based on the Hildon Application Framework, so it inherits many of the Maemo/Hildon theming components and capabilities.

This document has three goals:

1. Review the relevant subsystems available for theming in Moblin
2. Establish a set of Moblin theming assumptions, guidelines and rules
3. Review, and make recommendations on, how these subsystems should be used to meet Moblin theming guidelines, review the tools available to do so, and walk through some HOWTOs for theme creation and modification

Theming is made up of multiple configurable elements, ranging from the X Windows resources to application icons. There is no one configuration file and image repository that controls it all, but rather a series of subsystems, each with its own methods of configuration. When this series of subsystems is combined in the right way, it allows a user or OEM to customize the look, feel, and behavior of the entire interface. Customization consists of the modification, to some degree, of one or all of the following:

• Widgets: These are the fundamental building blocks of an interface.In our case, widgets are based on the GTK+2 libraries. For theming, you can adjust the colors, fonts, dimensions, borders, padding, and other properties of widgets using a configuration file(s), typically named gtkrc or something similar.

• Window Manager: The Window Manager controls how a window (dialogs and menus, too), border, title, and buttons (min, max, close) look. In the theme.xml file, a designer can set what size and color the borders (frames) are, and can even define images (shapes, when using alpha blends) that alter the frames to be non-rectangular. You can also control some behaviors of the close and open actions.

• Icons: These are the images used in various forms to represent applications, actions, properties, emblems, and etc. There is a generally agreed upon set of common/standard icons, used by desktops and widget sets, as well as literally hundreds of customized versions available to install. There is a hierarchical order in which icon directories are searched for matches to requested icons, and by replacing a few key icons in paths that have higher priority, you can customiz the look of applications and the desktop without having to replace the entire set of images.

• Desktops: A desktop is the combination of a display or login manager, panels, and usually a file manager, the right mouse action, backgrounds, component libraries and APIs for applications to integrate into, notification from the desktop, and probably some other things I am forgetting. The key point is that each desktop, be it Hildon, Gnome, KDE, or Xfce, tends to have its own look and feel, which is controlled by the combination of widget sets, window manager, and icons it is build on.

In Moblin, as in Maemo, the structure of a theme consists of:

• /usr/share/themes/${THEME}/
        gtk-2.0/
              gtkrc
              gtkrc.maemo_af_desktop
              gtkrc.moblin           #Not yet implimented, but adding it to GTK2_RC_FILES in /etc/X11/Xsession.d/25ume-config-common_startup causes it to also be applied
        images/
              *.png
        matchbox/
              theme.xml
        index.theme
  

Not included in the context of themes are:

• icons
• backgrounds
• fonts
• sounds

Today, these elements are usually installed or configured by the distributor or OEM per their brand or style preferences, and there are no packages and management tools available to integrate these elements into a theme. However, we will still touch on each of these elements, and discuss how they might be included in the concept of themes and theme management tools.

1.1. Available Theming Subsystems

1.1.1. Widget (GTK+2) Themes

A widget theme defines the look (colors, pixmaps, shadows, etc.), size (borders, widths, etc.), layout (offsets, padding, etc.), and various other properties of the Gtk+ objects, as they will appear in applications, menus, and dialogs. A widget theme does not define the window border or title bar properties, however. That is done with the Window Manager theme.

A GTK+ theme consists of three things:

• a theme engine (sapwood in our case), which is a shared object, including code to draw the graphical elements

• a configuration file to set the operation of the theme engine and the core parts of GTK+2
• extra data files for the theme engine, such as images

Some variation is possible in the use of a theme engine. A theme can include its own theme engine. A theme can use an existing theme engine, such as the Pixbuf theme, which uses images rather than vectors to draw all elements, or it can use GTK+'s built-in drawing code. In Hildon/Moblin, Sapwood provides a server and client library to access theme images. The server is responsible for loading the theme-related images and distributing them to clients. Sapwood saves memory, as if differs from the Pixbuf engine, which does not share the bitmaps between applications. Sapwood is also much faster because it tiles the 16-bit images using X server, whereas the Pixbuf engine scales the 24/32-bit on the client side and then converts it to 16-bit for blitting on the X server.

Some key points to note about widget themes:

• Buttons, scrollbars, edit boxes, and etc. can all be themed individually.

• Theme properties are applied hierarchically, so widgets based on parent widgets will inherit their parents' set properties. For example, setting the default-border on a GtkButton, will apply to all children, such as the GtKOptionButton. Conversely, setting a property to a child object will NOT have any affect on widgets it is derived from. A hierarchy of the GTK objects and their relationships can be found at: http://library.gnome.org/devel/gtk/unstable/ch01.html

• The gtkrc file is where all the theme options are stored. You can include external files using the include directive. This allows for split development of themes or quick testing of different design elements, by changing symbolic links to external theme files. Note: Under the Hildon theme framework or libraries, them options do not appear to be working as described. We tried to create a gtkrc.moblin file for our changes, but we couldn't get it to apply. Bob Spencer found in hildon-deskop that the gtkrc.maemo_af_desktop file was hard coded to be the only gtkrc file loaded. So this is an area where we may want to create and provide patches to Maemo to enhance its capability to load custom gtkrc files, including application-specific resource files. It's possible that applications may want to load an application-specific config file that will allow further customization, over and above what the theme provides, while not requiring it to be hard coded at compile time. We will discuss the relative merits of loading an application-specific resource file later in this document. Part of the point of Moblin is to provide a framework developers can use to create a consistent UI, per OEM, so allowing applications to deviate from that framework may not be desirable. However, we recognize that not all future possible widgets and classes can be anticipated in today's resource files.

• Theming in GTK is a combination of some basic widget styles and something called theme engines (mentioned above) that provide most of the flexibility and customization potential. A theme engine is a shared library with the code needed for drawing the basic components of widgets (shadowed boxes, frames, arrows, scrollbars, radio button indicators, and etc.). We learn from http://live.gnome.org/GnomeArt/Tutorials/GtkEngines that: GTK has about 20 drawing functions internally, which can be overridden by the GTK engine. GTK itself has only a very basic implementation for these drawing functions, and all widgets have the same 3d look to them. GTK engines override the buildin functions used by GTK. This enables them to draw whatever they want. There are three basic types of engines:

  1. The Pixmap Approach: Every aspect of every widget is drawn from a user-specifiable pixmap image.

  2. The Single-Look Approach: A single, uniform look is used for all widgets; generally only allowing for color variations or minor changes to widget style.
  3. The Flexible Approach: The engine internally allows for multiple ways of drawing things so the user can configure it to draw what he wants but it doesn't have the overhead of pixmap images.

  Examples of other theme engines are: Clearlooks, UbunutLooks, Crux, Mist, Redmond, PixBuf, Sapwood, and etc.). Installed engines are located at: /usr/lib/gtk-2.0/2.10.0/engines/

• A list of available GTK, and application-specific, style properties can be found at: http://live.gnome.org/GnomeArt/Tutorials/GtkThemes/StyleProperties

• There are three ways to apply styles, binding a style to a named object, in GTK, using one of the class, widget_class, and widget statements.

• The order of precedence for styles is as follows:

  • widget styles, which take precedence over

  • widget_class styles, which take precedence over

  • class styles

  For example, if in the gtkrc file we have the following:

  ...
  style "clearlooks-wider" = "clearlooks-default"
  {
      xthickness = 3
      ythickness = 3
  }
  style "clearlooks-wider-orange" = "clearlooks-wider"
  {
      bg[SELECTED] = "#FF6D0C"
  }
  style "clearlooks-button" = "clearlooks-wider-orange"
  {
      bg[PRELIGHT] = "#f5f3f0"
      bg[ACTIVE] </nowiki><nowiki>= "#d9d3cc">
  }
  ...
  style "clearlooks-tree" = "clearlooks-wide"
  {
  }
  style "clearlooks-my-tree-hack" = "clearlooks-tree"
  {
      xthickness = 1
      ythickness = 1
      bg[SELECTED] = "#F5F3F0"
  }
  ...
  # widget styles
  class "GtkWidget" style "clearlooks-default"
  class "GtkButton" style "clearlooks-button"
  ...
  # treeview stuff (Any widget subclassed under GtkTreeView and GtkButton matches)
  widget_class "*.GtkTreeView.GtkButton" style "clearlooks-tree"
  ...
  # My custom treeview style
  widget "my-gtk-treeview" style "clearlooks-my-tree-hack"
   

  We see that the widget with the name my-gtk-treeview is a widget based on the GtkTreeView widget class, which is also a subclass of GtkWidget. The filtering of the application of the GtkTreeView widget class' sets of style properties happens from least to most specific.

• So when the my-tree-view widget is created, the order of priority the sets of style properties will be applied in is:

  1. all clearlooks-default style properties defined for GtkWidgets

  2. all clearlooks-button properties

  3. clearlooks-tree properties

  4. clearlooks-my-tree-hack properties

• Or, stated another way, the following properties are applied in this order (with the most recently applied style to any property being the one used):

  1. From clearlooks-default:

         GtkButton ::default_border <nowiki>= { 0, 0, 0, 0 }
         GtkTreeView ::expander_size = 14
         GtkButton ::child-displacement-x = 0
         GtkButton ::child-displacement-y = 0
         xthickness = 1
         ythickness = 1
         GtkTreeView::odd_row_color = "#F5F2ED"
         GtkTreeView::even_row_color = "#FAF9F7"
         ...
         bg[PRELIGHT] = "#f5f3f0"
         bg[ACTIVE] = "#E1D9D1"
         bg[SELECTED] = "#D6722D"
         ... 

  2. Next, clearlooks-wider alters the x/y thickness properties:

         xthickness = 3
         ythickness = 3 

  3. Next, clearlooks-wider-orange changes the selected color of the widget background:

         bg[SELECTED] = "#FF6D0C" 

  4. Next, clearlooks-button changes additional background colors for additional states:

         bg[PRELIGHT] = "#f5f3f0"
         bg[ACTIVE] = "#d9d3cc" 

  5. Finally, clearlooks-my-tree-hack alters a few more properties:

         xthickness = 1
         ythickness = 1
         bg[SELECTED] = "#F5F3F0" 

• The result is a union of all properties, with styles merged in later, overriding the previous settings. This makes sense, because the class matches are very broad while the widget match is very specific and often picks out single widgets. The order for widget_class and widget matches is simply whatever order is in the file, more recent settings overriding the older ones.

1.1.1.1. Hierarchy or Structure of GTK+2 Resource Files, and Orders of Precedence

On an installed system, several locations are searched for a gtkrc resource file. The first gtkrc file found in this search order is the file used.

1. ~/.gtk-2.0/gtkrc

2. $GTK2_RC_FILES environment variable, typically set to something like:

       /usr/share/themes/<THEME>/gtk-2.0/gtkrc
       # On a Hildon desktop, it includes an additional entry:
       /usr/share/themes/<THEME>/gtk-2.0/gtkrc:/usr/share/themes/<THEME>/gtk-2.0/gtkrc.maemo_af_desktop 

   If more than one file is specified here, both are applied and the most recent, and most specific, style match will be applied, replacing older matches.

   Note: Adding a Moblin-specific file here will allow us to keep our changes separate from the Maemo and GTK-specific filees. Right now, we (Intel) modified the existing one that came with the Plankton theme, which is not a longterm, maintainable solution.

3. ~/.themes/<THEME NAME>/gtk-2.0/gtkrc

4. /etc/gtk-2.0/gtkrc

If an application loads its own resource files with gtk_rc_parse(), they will override system theme styles, as long as it calls gtk_rc_parse() after gtk_init(). Any styles applied to properties of application widgets, defined in the source code, will have the highest priority and cannot be modified by external resource files. Obviously, this is not an ideal situation and prevents adapting such an applications presentation into the overall theme the OEM (or user) desires to maintain. These application specific styles will stand out and disrupt overall visual continuity.

1.1.2. Window Manager (Matchbox) Themes

1.1.2.1. Matchbox

Matchbox themes can set values for colors, fonts, and pixmaps, and apply these as properties to window, dialog, menu, button (close, minimize, and maximize), and panel borders (frames). You can "shape" windows and dialogs by using images or pixmaps with transparent alpha channels in them (rounded dialog corners, for example). You can also define window or dialog title placement and buttons (minimize, close, and etc.), as well as menu positions and frame animations

You can override application icons by using theme .desktop files in the same location as the theme.xml file. The basic mechanism works by 'overriding' the application's default icon. For example, before checking $PREFIX/share/pixmaps for a specified icon file, Matchbox applications will check the following in order:

1. $HOME/.icons/

2. $HOME/.icons/[theme_name]/[size]x[size]/[type]/

3. $PREFIX/share/icons/[theme_name]/[size]x[size]/[type]/

Where [size] is usually one of 48, 36, 32, 24, or 16 and [type] can be anything (usually 'apps', 'emblems' etc.). So, as long as you know the image filename an application wants (Hint: Look at its .desktop file), a Matchbox theme can change its icons appearance.

1.1.2.2. Compiz

More research is required to understand what is configurable and how in Compiz, and how to integrate it in a way that works with the Hildon Desktop.

1.1.3. Icon Themes

Icon themes define the paths and subdirectories in which to search for icons used or defined by applications, and potentially by the desktop and widget themes.

By default, applications should look for icons in the following locations, in this order:

1. $HOME/.icons (for backwards compatibility)

2. $XDG_DATA_DIRS/icons

3. /usr/share/icons/${THEME} 

4. /usr/local/share/icons/${THEME} 

5. /usr/share/icons/hicolor

6. /usr/local/share/icons/hicolor

Applications may also add their own icon directories to this list. In your application, where you initialize GTK+, you also want to do the following, so that your application will find these icons if the theme tree structure you are using doesn't provide them:

 gtk_icon_theme_append_search_path (gtk_icon_theme_get_default (),
                                    APPNAME_DATA_DIR G_DIR_SEPARATOR_S "icons");

In at least one of the theme directories, there must be a file called index.theme that describes the theme. The first index.theme found, while searching the base directories in order, is used. The index.theme file describes the general attributes of the theme.

The easiest way to modify an icon is to copy an existing theme, modify the theme name in the path and index.theme file, and then replace or add the new icons, that represent the desired look.

Some applications have their own icons, defined for functions that are not yet standardized by GTK+ definitions, and these icons are usually located in application-specific resource locations. For example, the FireFox icon go-arrow.png is stored in the chrome being used, in the classic.jar file. This is not something a casual theme developer will be able to replace without getting into application-specific skinning methods. Though, in this case, work is underway for the FF 3.0 release, to add tango icons for these common browser functions: http://tango.freedesktop.org/Firefox, https://bugzilla.mozilla.org/show_bug.cgi?id=381206.

As a rule of thumb, it is not appropriate for an application to install or replace any of its icons in the ${THEME}  directories. Instead, they should either place them in an application-specific location (/usr/share/${APP}/icons) or in the hicolor theme (/usr/share/icons/hicolor). The hicolor theme is preferred because then other themes and applications can use it in the future.

Application writers are encouraged to use the GTK+-defined icons as often as possible, and refrain from creating their own custom icons in cases where icons have already been defined. Creating custom icons leads to a user experience that becomes fragmented when the application is installed on different distributions that use alternate themes, or when the user changes from the default theme to some new or cool one that suits their preferences. When creating new or custom icons is the only reasonable choice, it's best to base them on the tango pallet. If the function the icon represents could potentially be useful in other applications, it's a good idea to submit a request for a new icon (or even send a sample icon) to the common theme maintainers . It is strongly suggested that you follow the Tango (http://tango.freedesktop.org/Tango_Icon_Theme_Guidelines) and the Icon Naming Specification (http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html).

1.1.4. Desktop (Hildon or Gnome) Themes

Hildon themes are broken out into a layout and a graphic.

According to the Hildon Theme Overview (http://live.gnome.org/Hildon/ThemingOverview):

"The layout contains the common gtkrc styles and other internal bits shared among all themes. The graphics consists of a single bitmap that can be easily handled by the artist (see end of this page for examples). In other words — the layout is a static part of the theme while the graphics is the dynamic partI know this is a quote, but it's gammatically incorrect.... I can't edit it, right?. There is usually one layout per OS release — ie. hildon-theme-layout-3 for Bora release."

In Moblin, as in Maemo, the structure of a theme consists of:

/usr/share/themes/${THEME}/
      gtk-2.0/
            gtkrc
            gtkrc.maemo_af_desktop
            gtkrc.moblin            #Not yet implimented, but adding it to GTK2_RC_FILES in /etc/X11/Xsession.d/25ume-config-common_startup causes it to also be applied
      images/
            *.png
      matchbox/
            theme.xml
      index.theme

There are tools available (discussed in more detail later in this document) that allow a theme developer to generate the necessary directories and files. These tools are based on a large graphic template file and a layout.txt file. The hildon theme building tools use the layout.txt file to map a single graphic file, containing the images used by the sapwood engine to decorate the GTK+2 widgets. You will not find this file on an installed target system, but it is available in the hildon-theme-layout-4 package. To customize a theme to the level of the GTK+2 widgets, you can either edit and replace all the individual images on the installed system, or use the template.png file that maps to a matching layout.txt file and run it through the various hildon theme tools to generate an installable Maemo theme package.

The big difference for Moblin is that we have significantly modified the default layout, but we have not yet generated the matching template.png and layout.txt files that could be used by designers to easily update and change the overall appearance of the GTK+2 widgets.

Desktop themes also define how the various application launcher icons appear on the desktop, and in what order and category. There is actually a specification that covers this, located at: http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html

This specification defines the location of the .desktop files, what they must contain to be properly displayed, and what is executed when they are activated or clicked.

Moblin follows this specification, requiring any application to be displayed on the desktop to place an appropriate .desktop file in /usr/share/applications (as defined by the Menu Specification, located at: http://standards.freedesktop.org/menu-spec/menu-spec-latest.html).

1.1.5. Boot Splash Themes

Moblin (as well as Ubuntu Mobile and Embedded) is using a patched version of grub to enable splash image support. For more information on how to modify your grub implementation to support splash images, check out http://ruslug.rutgers.edu/~mcgrof/grub-images/#3

The boot splash image will be shown when system boots. The Moblin logo image show below is the default. To meet your personal or corporate branding requirements, you can create your own boot splash image and configure grub to use it by following these steps:

1. Create your own image, within the following restrictions:
   • XPM format
   • 640x480
   • 14 colors

2. Gzip the xpm (myfile.xpm.gz)file and put it into your /boot/grub directory

3. Edit the GRUB config file (/boot/grub/menu.lst) and add the following line:

   • splashimage=(hd0,X)/grub/myfile.xpm.gz

     NOTE: Change the partition and directory according to your system's setup.

4. Boot your system

Illustration 1: Default Moblin boot splash image

---

2. Guidelines for Moblin Theming

Moblin's target devices are Mobile Internet Devices, or MIDs. These devices fill a niche in device size, between a handheld PIM and a UMPC, with a screen size of appropriately 5 in.This display size will obviously impose some usage and interaction limitations, beyond those typically found on notebooks and UMPCs, so we have collected a set of recommendations to use when designing and using themes in Moblin.

2.1. Put it in Perspective - Target Screen Resolutions

TODO::

• Specific information about supported/targeted screen resolutions.

2.2. Size Doesn't Matter - Icon and Font Sizing Recommendations

TODO::

• Specific requirements on min/max font sizes
• Font family or typeface recommendations that are known to work well at target resolutions and use cases
• Icon size and/or scalable icon requirements

2.3. Touch of Class - Considerations for Finger-Based Input Methods

TODO::

• Comments or suggestions regarding finger-based input usability and how it applies to application UI design methodologies
• Recommendations on alternate data gathering or reporting methodologies
• Introduction to new widgets developed to ease adapting applications to the small form factor
• How to use gesture based input (Moko)
• Etc.

Reference or include details from the Moblin UI Style guide, as appropriate:

• http://moblin.org/toolkits/basicDevGuides/UIComp/toolkits_DevGds_UIComp_stdGuide.php

• https://blueprints.launchpad.net/ubuntu/+spec/mobile-ui-style-guide

---

3. How To Theme Moblin

3.1. Moblin Startup

On boot, upstart will execute /etc/event.d/session, which will launch X using the following command:

exec su -l ume -c "/usr/bin/startx -- -config xorg-samsungq1ultra.conf"

Once X starts, it parses the session scripts in /etc/X11/Xsession.d/ including /etc/X11/Xsession.d/25ume-config-common_startup file, which sets the GTK2_RC_FILES environment var for Gtk+2 widget themes as follows

GTK2_RC_FILES=/usr/share/themes/mobilebasic/gtk-2.0/gtkrc:/usr/share/themes/mobilebasic/gtk-2.0/gtkrc.maemo_af_desktop

These files define all the Gtk+2 styles and bindings that will create the look and feel of all the widgets in the Moblin applications, the Hildon desktop, and any other resources based on GtkWidgets

The gtkrc file in /usr/share/themes/mobilebasic/gtk-2.0 is a merged version of many separate files that used to be #included. This file is created during the build of the hildon-theme-layout-4 package, which is a requirement for hildon-theme-plankton, which is what the mobilebasic theme is derived from. The source package of hildon-theme-layout-4 has 72 individual .rc files that are merged into flat gtkrc and gtkrc.maemo_af_desktop files. These files are not complete yet as they still require color substitutions that will happen during the build or installation of the actual theme package (hildon-theme-plankton).

Maintaining this file, in its current form, by theme developers is rather insane. The gtk_rc_parse_statement() function seems to detect and handle the presence of #include directives, passing that token to parse_include_file() private function. So keeping these files separate is certainly feasible, but the hildon-theme-tools utilities and hildon-theme-plankton install scripts make some assumptions about the number and location of the resource files that need to be modified to swap in color hex values, and the template.png/layout.txt files used to get those values. So this solution requires a non-trivial set of changes to theme tools and packaging for Moblin and will really cause us to diverge from standard hildon themes (unless our theme architecture changes are acceptable to upstream hildon)

Two options present themselves:

1. Modify the hildon-theme-tools and hildon-theme-layout-4 to no longer merge the .rc files into one file, and to perform the necessary color token substitutions on multiple .rc files (they actually do now, once each for gtkrc, gtkrc.maemo_af_desktop, index.theme, and theme.xml). Then we apply changes only to the files we want to affect and can better track diffs.

2. Remove all our changes from the existing gtkrc, gtkrc.maemo_af_desktop files and add a new file, gtkrc.moblin (or gtkrc.ubuntu, or gtkrc.OEM, or ...). Then modify the GTK2_RC_FILES env var to append this new file at the end. This could be done in either /etc/X11/Xsession.d/25ume-config-common-startup or in the beginning of /usr/share/ume-config-common/ume-gui-start. I have tested this method and it works as expected.

Next, the script /usr/share/ume-config-common/ume-gui-start is run, which starts the window manager (MatchBox in our case), passing the theme.xml config file path as an argument.

• Note: The Matchbox theme is currently hard coded to mobilebasic in the /usr/share/ume-config-common/ume-gui-start file.

/usr/bin/matchbox-window-manager \
    -theme /usr/share/themes/mobilebasic/matchbox/theme.xml \
    -use_titlebar no 

• Note: This does not allow for the env vars or gconf entries to alter the window manager theme on startup based on some config. Should this be changed so it is configurable and lasting using a theme control applet or daemon, or should it be left as is for users or OEMs to customize as they see fit? Pros or cons either way?

The sapwood-server GTK+2 theme engine is startedWho starts it? Let's make this sentence active., followed by the hildon-desktop.

How does Gconf affect all this? Gconf on a Moblin image which contains the following settings

/desktop/gnome/interface
     /gtk_key_theme = Default
     /gtk_theme = Human
     /icon_theme = Human
     /font_name = Sans 10 

Right now, it seems that these settings are not being used, since we do not have the human theme installed (artifact of running in the chrooted shell from image-creator?).

It shouldn't matter, though, because the theme tools and/or theme package install scripts should set both env vars and gconf keys (and any other means of altering the settings) consistently.

3.2. Icon Locations for Hildon

Hildon default locations for icons are as follows:

• Task nav icons (64x54 .png files) /usr/share/icons/hicolor/scalable/hildon

• Status bar icons (40x40 .png files) /usr/share/icons/hicolor/40x40/hildon

3.3. Changing the Screen Background

The background setting is dependent on the exact Hildon HomeArea implementation you are using(Flash, XUL/DHTML, Clutter, etc.). Using the default UI implementation in Moblin (the XUL based HomeArea), the background is controlled with a gconf setting:

/desktop/gnome/background
     /picture_filename
     /picture_options
     /primary_color 

This is done in mobile-basic-home-plugin.cpp by registering for notification callback when certain gconf settings are changed:

 gconf_client_add_dir (context->client, "/Desktop/gnome/background",
                       GCONF_CLIENT_PRELOAD_ONELEVEL, NULL);
 gconf_client_notify_add (context->client,
                          "/picture_filename",
                          (GConfClientNotifyFunc) background_changed,
                          context, NULL, NULL);

Setting the background for other HomeArea implementations (Flash or Clutter-based, for example) is dependent on the specific technology you are using. As these are tested and understood, additional instructions for each will be added here.

3.4. Changing the Sounds

Sounds are located in /usr/share/sounds (is this really true? It is for Maemo, but I did not find much in there on a Moblin install.)

Sounds are not currently defined in themes,so the user/developer/designer/OEM must replace those that exist as the defaults with those of their choosing. Not only is this irreversible, but it's also not very friendly. We need a better way to manage this.

3.5. Adding or Changing Fonts

New fonts are placed in /usr/share/fonts/... according to their type (TrueType, X11, etc.). Font references in the gtkrc files and theme.xml may use these fonts by name, or as part of a series of names used as fallbacks, if any of them are missing. Refer to gtkrc documentation for details on how to reference multiple font names for style settings.

3.6. List of Moblin Customizations Applied to Maemo Themes

Note: We need to list the things we have done in Moblin above/beyond what was default with Hildon themes and configurations that will require developers and designers to change how they create themes for Moblin. May be accomplished in other sections of this document, or summarized here.

3.7. Theme Tools

A variety of tools are available for creating, testing, and managing themes. The bulk of the work still depends heavily on console-based file manipulation, but some interesting tools are under development that could prove useful to Moblin, either in the future as they mature, of today if you take on the burden of massaging them to meet this project's needs.

3.7.1. Hildon Theme Tools - Creator or Cutter

hildon-theme-tools package http://live.gnome.org/Hildon/ThemeToolsOverview. This contains the tools like hildon-theme-bootstrap and hildon-theme-slicer which the creator or designer can use to transform their customized template.png file into an installable theme that contains individual files for each graphical element, color and font specifications, and updates to the various resource files that define the theme.

A possible extension being explored would modify these tools to allow for multiple .png files and layout files to be parsed or cut and applied at install or build time, allowing new themes to be built on top of each other, or even add new customization capabilities not previously thought of. Some spec file would need to be present, defining the order to parse the various graphical components, especially if they contain elements that supersede settings, images, and/or colors defined in earlier parsed files.

The other option is to fork the hildon theme tools, defining a new layout spec and associated template.png format that meets Moblin needs. Unfortunately, forking the tools does not assist in our goals to be substantially compatible with existing Hildon-based applications and themes. It's desirable to work with the Hildon theme maintainers to extend the capabilities of the tool set.

3.7.2. ThemeMaker

ThemeMaker is a Java GUI theme tool http://thememaker.garage.maemo.org/Downloads.html that allows a theme developer to combine a new template.png file with the layout-4 files and generates the resulting resource files (gtkrc, gtkrc.maemo_af_desktop, index.theme and theme.xml (for Matchbox)).

3.7.3. Theme Selector or Manager

3.7.3.1. gtk-theme-switch

• Looks in $HOME/.themes/gtk-2.0/gtkrc for theme files

• Calls gtk_rc_get_theme_dir() to find $theme/gtk-2.0/gtkrc

• Notifies you that theme rc files should be re-read with the following code:

  static void
  send_refresh_signal(void)
  {
       GdkEventClient event;
       event.type = GDK_CLIENT_EVENT;
       event.send_event = TRUE;
       event.window = NULL;
       event.message_type = gdk_atom_intern("'''_GTK_READ_RCFILES'''", FALSE);
       event.data_format = 8;  '''gdk_event_send_clientmessage_toall'''((GdkEvent *)&event);
  }
   

While this tool is an excellent start, it seems to be missing a few things we need:

• Update the Matchbox theme:

  • http://matchbox-project.org/documentation/manual/wm.html#wmthemes

  • The easiest way is to use matchbox-remote to change the current theme; <tt><nowiki>matchbox-remote -t <theme name></nowiki></tt> Alternatively, if you compiled with XSettings support, you will be able to use the Gnome2/GPE/KDE3 desktop configuration tools to change the theme. The XSettings key used is Net/ThemeName. Using XSettings allows the window manager theme to change with the toolkit theme.

  • I have tested this, and it works, while really only applying to dialogs because few or no apps have "windows" per se that would be decorated by the window manager in Moblin or Hildon.
• Playing with stock gtk-theme-switch (switch2) from Gutsy did not have any immediate or direct impact to the Moblin GTK2 widget styles, so the gdk_event_send_clientmessage_toall() with the _GTK_READ_RCFILES message does not have the same effect on Moblin or Hildon, as it does on my standard Ubuntu desktop.
• Update gconf keys:

  • http://www.gnome.org/projects/gconf/

  • http://library.gnome.org/devel/gconf/2.20/gconf-GConfClient.html

  • The following presumes applications have registered to listen for theme changes. Need to experiment or read more to know how reliable updating gconf keys is, as a means to control gtk, icon themes, and default font.
  • Use gconf_client_add_dir() and gconf_client_notify_add() to register for notifications when keys at or below the dir/namespace are changed, as in the example below.

     gconf_client_add_dir (context->client, "/Desktop/gnome/interface",
                           GCONF_CLIENT_PRELOAD_ONELEVEL, NULL);
     gconf_client_notify_add (context->client,
                              "/gtk_theme",
                              (GConfClientNotifyFunc) theme_changed,
                              context, NULL, NULL);
     gconf_client_notify_add (context->client,
                              "/icon_theme",
                              (GConfClientNotifyFunc) theme_changed,
                              context, NULL, NULL);
     gconf_client_notify_add (context->client,
                              "/font_name",
                              (GConfClientNotifyFunc) theme_changed,
                              context, NULL, NULL);
     gconf_client_add_dir (context->client, "/Desktop/gnome/background",
                           GCONF_CLIENT_PRELOAD_ONELEVEL, NULL);
     gconf_client_notify_add (context->client,
                              "/picture_filename",
                              (GConfClientNotifyFunc) background_changed,
                              context, NULL, NULL);
       

• Can we assume that applications are listening for "changed" notifications on relevant gconf theme keys?
• Does not update icon theme configs and emit the "changed" gtk signal to cause apps to call gtk_icon_theme_rescan_if_needed ()

• Does not address the "background" setting (which really isn't part of a theme and is desktop or HomeArea dependent, such as,Clutter, Flash, HTML, etc., which willall have different methods of setting the background image. Setting the background image is a really interesting problem, if we want apps like moblin-media to allow users to set the selected image as the "background" image. We need an API or event that HomeArea implementations must listen for and apply in their specific manner. One way we are doing this now in Moblin with the HomeArea applet is to register for notification on changes to the Desktop/gnome/background/picture_filename gconf key, and make whatever change is needed in the callback when the event triggers. Maemo makes use of a simple symbolic link in /usr/share/background.

• Does not seem to interact with GtkSettings (XSETTINGS implementation for GTK, http://maemo.org/api_refs/4.0/gtk/GtkSettings.html) by setting some combination of the following settings using gtk_settings_set_string_properties(), as defined at http://library.gnome.org/devel/gtk/stable/gtk-Resource-Files.html#gtk-rc-reparse-all-for-settings:

  • "gtk-theme-name" (Name of theme RC file to load, default "Raleigh")
  • "gtk-key-theme-name" (Name of key theme RC file to load, default NULL)
  • "gtk-icon-theme-name" (Name of icon theme to use, default "hicolor")
  • "gtk-font-name" (Name of default font to use, default "Sans 10")
  • "gtk-cursor-theme-name" (Name of the cursor theme to use, or NULL to use the default theme, default NULL)

3.7.4. Theme Testing

The Widget Factory is a useful tool for theme developers to see what the effect their customized theme will have on a set of commonly used GTK objects, like GtkButton, GtkComboBox, etc.

Illustration 2: Example of twf with the Mist theme running on my desktop

Illustration 3: Example of twf with the Mobilebasic theme on a Moblin image

As you can see from the two images above, there is still some work to be done on the Mobilebasic GTK theme to fit the format and size of the MID device target. Also, there does not seem to be a unified look and feel, especially when you compare the sliders in the center of the screen.

Another tool that may be useful is the OLPC GTK Theme Torturer tool, developed as part of a Summer of Code project. Information about what the tool was designed to do can be found at: http://wiki.laptop.org/go/GTK_for_OLPC#GTK_theme.2Fengine_torturer_and_crash_tester and the code is currently available at: http://dev.laptop.org/git?p=projects/soc-gtk;a=tree;f=gtk-theme-torturer;h=a9a2c88f330e96a1569062d1ccbe7d506e5f321f;hb=HEAD

There has not been much active development on that tool since August 2006 and web searches have not revealed any other references to it being merged into other tool sets or distributions.

---

4. Application Developers Guide to Themes in Moblin

Below are some items that application developers need to keep in mind, as it relates to integrating their application into a theme or making use of themes, assuming the themes can or will change without the developer knowing.

Application developers should be aware of:

• How to reference or get theme-based icons to use in their applications
  • What you get if you do nothing
  • Environment variables (with sample code to get and use values)
  • gconf keys (with sample code to get and use values)
• Where to put their custom Application icons during installation
• How to design custom Application icons to work best with Moblin themes
  • Follow Tango Guidelines
  • Follow Moblin Style Guide (reference)
• What theme related events or notifications do developers need to set up callbacks for and what should developers do when the callbacks trigger

---

5. Theme Developers Guide to Themes in Moblin

Key things to keep in mind:

• Layers of theming to anticipate:
  • System themes (Plankton/mobilebasic) – applies to all widgets that do not have their resources altered by some other means (user- or application-specific gtkrc files, or hard coded into the application).
  • Platform-included or core application themes – additional widget customizations for applications that are ALWAYS included in Moblin, or are Platinum level applications that are targeting tight interface integration with Moblin.
  • General applications – using only default gtkrc theme values as defined by the current theme.The theme does not use custom settings, icons, etc., but does nothing specific to adapt its UI for deep Moblin integration (any generic application ported to Moblin at a Silver level, or lower compliance level). Application custom themes (that is,tab background images in moblin-media) and icons.

  • Applications with custom widgets (with resources or classes covered by gtkrc theme files) or that hard code resource settings, preventing the effects of any external definitions in resource files. Can't do much about this, but just noting it as inevitably theme designers will encounter these rouge conditions.

• Theme cutting tools today tie the theme package to a particular layout version (v4 when this document was created). If a theme is developed for other hildon (or Moblin) layout versions, then it must be assumed that it will not work on systems using other layout versions. Your theme package should include a dependency check to make sure that the system you are installing the package on can support your themes layout.

5.1. HOWTO: Customizing Existing Themes

This is tips and tricks on how to modify an existing theme (hildon-theme-plankton, hildon-theme-mobile-basic, or others).

5.2. HOWTO: Create a New Theme from Scratch

This is a tutorial on how to bootstrap the development of a new theme from scratch, customize it, and package and test it.

---

6. Useful Links

1. Hildon Theme Overview: http://live.gnome.org/Hildon/ThemingOverview

2. GTK+@ Theme Tutorial: http://live.gnome.org/GnomeArt/Tutorials/GtkThemes)

3. Tigert's Maemo Plankton Theme Templates: https://stage.maemo.org/svn/maemo/projects/haf/trunk/hildon-theme-plankton/template/

4. Theme Maker: http://thememaker.garage.maemo.org/

5. Matchbox Window Manager: http://matchbox-project.org/documentation/themes/

6. Theme Engine Overview: http://www.gtk.org/~otaylor/gtk/2.0/theme-engines.html

7. Icon Theme Spec: http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html

8. Icon Theme Overview: http://live.gnome.org/GnomeArt/Tutorials/IconThemes

9. Customizing the Maemo UI: http://maemo.org/development/documentation/how-tos/4-x/customizing_maemo_and_creating_themes.html

---

7. Miscellaneous Notes:

• Maemo uses a caching mechanism (using gtkrc) to speed up launching applications. (packages are here: http://tigert.1g.fi/blog-files/n800-theme/ ), does Moblin use this feature? Should we, if we don't?

• No sound theming tools or mechanisms exist today
• No real font theming tools or mechanisms exist today
• Icons, technically, do not have theme selection and management tools, but rather they are packages of images (usually .tar.gz files) that replace the existing icons. It would be handy to have a way to manage icons.

7.1. Paths and Resources, Listed in Order of Precedence

• X

  • ~/.Xresources  (Not applicable? Single user)

  • /etc/X11/Xresources

• Widgets (GTK+2)

  • ~/.gtk-2.0/gtkrc  (Not applicable? Single user)

  • ${GTK2-RC-FILES}

• Window Manager (MatchBox)

  • /usr/share/themes/${THEME}/matchbox/theme.xml

• Desktop (Gnome/Hildon)

  • /usr/share/themes/${THEME}/index.theme

• Icons

  • ~/.icons  (Not applicable? Single user)

  • ${XDG_DATA_DIRS}/icons

  • /usr/share/icons/${THEME}

  • /usr/local/share/icons/${THEME}

  • /usr/share/icons/hildon

  • /usr/share/icons/hicolor

  • /usr/local/share/icons/hicolor

• Apps

  • ~/.icons (Not applicable? Single user)

  • /usr/share/${APP}/icons

  • /usr/share/icons/hicolor/${size}/apps

---

8. Glossary