Hildon theme how to
This document describes how to build a new theme for the maemo platform using the hildon theme tools. For general information about theming on the maemo/hildon platform please read theming overview document.
Installing scratchbox
Developing themes requires installing scratchbox and development environment. This is covered in detail elsewhere. Note that if you plan developing only themes in your environment, you just need the i386 target (no armel configuration required) since the themes are binary-independent packages.
Note: It's actually possible to develop themes outside of the sbox sdk/environment. The only part that will be problematic is the last step -- building the actual debian package with proper device dependencies etc.
Obtaining the theme tools
Currently maemo SDK releases do not contain the necessary tools installed for developing themes. This issue will be addressed in future (Chinook release) but for now you need to install the hildon theme tools manually. If you're working with Sardine that can be easily achieved with a command:
apt-get install hildon-theme-tools
If not, your best option is to fetch the source and compile manually. Inside scratchbox execute:
svn co https://stage.maemo.org/svn/maemo/projects/haf/tags/hildon-theme-tools/0.5.2-1/ hildon-theme-tools cd hildon-theme-tools dpkg-buildpackage -tc -rfakeroot cd .. dpkg --install hildon-theme-tools*.deb
Note: Check the tags (parent) directory when installing from source, there might be a newer version available.
Bootstrapping a new theme
To bootstrap (start creating) a new theme log into your scratchbox installation and run:
hildon-theme-bootstrap
This utility will interactively guide you through the theme bootstrapping process. Internet connection is required for this step as the tool downloads the required skeleton data from subversion. Getting the connection working inside scratchbox might require you to copy the resolv.conf file from your workstation to the scratchbox environment.
It's worth answering the questions asked by hildon-theme-bootstrap correctly on start, since changing the parameters (in several places) later on is a bit troublesome.
At first the tool will ask for the layout version to use. Read theming overview to understand how layouts map to maemo releases.
When done, the tool will create a hildon-theme-* directory with a bootstrapped theme structure. Ie. if you decided to name your theme red the directory name will be hildon-theme-red in the current working directory. This is also the package name.
Modifying the theme
The theme skeleton comes with some (up to date) graphics representing the development (Plankton) theme for the given layout. In most cases, the graphics is the only thing that you really want to modify and personalize for your theme. However, more customizations are possible by modifying the layout as well. This is outside of the scope of this document.
By editing (drawing) over the template.png you can create your personal theme. Use the overlay.png supplied in the same directory to see where the cutting coordinates are. You can overlay this image on the top of the template.png in your favorite graphics program. There is also an SVG version of the template available. It was created using the free vector drawing program, Inkscape - available for Linux, MS Windows, and Mac OSX.
Obtaining the layout package
Before you can build the theme package you also need to install the layout package in your build environment. This is only required for the build. During the build process the layout information is embbedded into the theme itself and the theme package doesn't set any dependency on the layout. Obtaining the theme layout is similiar to obtainig the theme tools.
For Sardine users:
apt-get install hildon-theme-layout-4
or
svn co https://stage.maemo.org/svn/maemo/projects/haf/tags/hildon-theme-layout-4/0.12.0-1 hildon-theme-layout-4 cd hildon-theme-layout-4 dpkg-buildpackage -tc -rfakeroot cd .. dpkg --install hildon-theme-layout-4*.deb
Note that here we're installing the theme layout-4. If you're building a theme against another layout (ie. theme-layout-3, used in the N800 OS2007 releases which are current as of this writing, october 2007) you need to change the paths accordingly. It's recommended that when installing from source you check the repository tree yourself and manually pickup the latest version. Again, this step is temporary -- in future SDK releases we're planning to ship the layouts with the rest of the development tools.
Building the package
The skeleton is prepared to make the debian package build easily. Issue the following command from within scratchbox:
cd [the theme-folder you bootstrapped] dpkg-buildpackage -tc -rfakeroot
The produced deb file/package can be copied to the device and installed instantly. There are some more tools available in the hildon-theme-tools package. Read more about them in the theme tools section.
Figuring out bits and pieces
Sometimes it might be pretty hard to guess/figure out how bitmaps are being streched and where each piece goes. For this purpose we have a test theme that contains graphical stubs and easily-distinguishable, contrasty elements. Just by looking at the test theme template you can get a quick overview how things fit. By actually using the hildon-theme-test in the sbox environment (or on the device) you can check if widgets are scaling/streching correctly, and if your graphical border values are set properly.
