Making Themes for MediaBox

Today I'm showing you how to make new themes for MediaBox.

Every theme is a subdirectory in /usr/lib/mediabox/theme or in ~/.mediabox/themes (MediaBox 0.96.2 or higher).
You can test your themes in ~/.mediabox/themes and when distributing the theme as an installer package, it will install into /usr/lib/mediabox/theme.

There are a two files that are absolutely necessary for a theme to work, and every theme must include them.

The one is PREVIEW.png, which is a PNG image of size 112 x 67 pixels, showing a preview image of your theme. This is the icon that the users will see in the theme selector.

The other file that is necessary is a simple text file called info. This file describes the theme and looks like this:

name:        MyTheme
description: My example theme for MediaBox
author:      Your Name

Of course, with only these two files, your theme will be pretty empty. Actually, MediaBox will load everything that it doesn't find in the current theme from the default theme. Thus, every theme inherits from default.

When you look into the directory of the default theme (/usr/lib/mediabox/theme/default), you will see a lot of images in PNG format. These are the theme elements. Your theme can override any of these images by providing a PNG image of the same name and the same size. I have to stress that it is absolutely necessary that the theme elements provided by your theme are exactly the same size as the ones in the default theme! For instance, the element mb_panel.png is of size 64 x 64 pixels. If your theme provides mb_panel.png, it must be of size 64 x 64 pixels, too.

A theme can have a bunch of .def files, which are text files containing font and color definitions. The name and number of the .def files is not important. Below are example entries of a .def file:

#
# Virtual Keyboard
#
color_mb_vkb_background: #000000
color_mb_vkb_text: #dddddd
font_mb_vkb: Nokia Sans Cn bold 20

Empty lines and lines starting with a # symbol are ignored by MediaBox and can be used for adding comments and making the file better readable.
The other lines contain key-value pairs, where key and value are separated by a : symbol. If the key name starts with color_, then MediaBox treats it as a color definition. If the key name starts with font_, then MediaBox treats it as a font definition.

Color values are given in hexadecimal RGB (6 digits) or RGBA (8 digits) notation, prepended by a # symbol. Most color keys take RGB values only.

Font definitions are given in Pango syntax, containing the font name, optionally a style (bold or italic), and the font size in points. Although the Nokia internet tablets have a screen resolution of 225 dpi, the system renders fonts with 96 dpi.

Any keys defined in the .def files of the default theme can be overriden by your theme in .def files.

Once your theme is ready, you may want to distribute it as a installer package for the application manager. I have created a build script for this task. If you have upload permission for the maemo-extras repository, you can then upload your theme with the Maemo Extras Assistant web site and promote it to the extras repository, so that other users can enjoy it, too.

Theme packages always depend on mediabox-compat-theme with a certain version number. For MediaBox 0.96 and some following releases, this version number will be 1.0. So as long as MediaBox provides mediabox-compat-theme, version 1.0, your theme will remain compatible. At a later point some minor changes or extensions to your theme may be necessary to fully restore compatibility again.