Introduction

Since the mid-2000s, Rockbox has allowed users to modify the user-interface. Over time, this feature has evolved and matured into an intricate system of tags and markup. The theming system as it stands today provides the user with an incredible amount of freedom and control, with the possibility to do so much.

Despite this however, the barrier for entry has historically been incredibly high. If someone wished to learn how to build themes from scratch, all that was available were existing themes, a single page of documentation, along with frustrating trial and error.

Ultimately, the goal of this guide series is to provide those who have a desire to make themes with all the information they could possibly need to do just that.

This beginners guide will break down the core concepts of the rockbox theme engine, walk you through implementing basic features, and show you how to use external tools to make your theme look and perform the best it can. By the end, you’ll have a basic template of a theme, but what you learn to get there should be enough to help you realise your own vision.

Note on learning from themes

Learning from existing themes is a great way to see things in action and experiment, however there are some downsides to be aware of.

Almost every existing theme right now was made by someone who learned from other themes, as mentioned previously. This has meant that older, more complicated (and inefficient) ways of implementing features have become the de-facto standard.

This can, and most likely will, make theming seem far harder than it is and confuse you a fair amount.

This guide however will follow a style of creating themes I developed myself independently, making use of the full capabilities in the theming system. This style is incredibly simple, versatile and easy to learn and should be a great starting point for those new to theming.

What you’ll need

Creating themes is an incredibly simple process, and all you’ll really need is a basic text editor, some kind of image editor and creation software (GIMP and Inkscape) and a device to test on.

I highly recommend checking out the Ui Simulator as an alternative to using a device to test, as it allows for must faster iteration and can provide detailed errors from the command line.

Basic Terminology

There is no concrete terminology used when talking about themes, but there’s been some loose terms used over the years that I will attempt to frame here.

⚬ Theming Engine - A common term used to describe the internal system which manages the creation of themes.
⚬ WPS - While Playing Screen. The name given to the music player part of a theme.
⚬ SBS - Status Bar Screen. The name given to the part of a theme managing the status bar, menus etc.
⚬ FMS - FM Screen. The part of a theme that manages the FM Radio player.
⚬ Tag or Theme Tag - The part of the markup system controlling content on screen.
⚬ Viewport - Content sandboxes in themes. Will be covered next chapter.

Theme files

For each instance of the WPS, SBS and FMS mentioned above, a text file is used to code these part of the themes. Each file is saved with a corresponding file ending that Rockbox can read, for example a WPS theme file would be named ‘filename.wps’. These files live inside the .rockbox directory of your device, in a folder named ‘wps’.

To manage these files, and tell Rockbox what to load, there is another folder on your device called ’themes’. Inside here we find config files typically titled ‘themename.cfg’. This is what allows your theme to appear in the theme selection menu on your device, and ties together all the parts that make up your theme. It includes the location of WPS, SBS, FMS and icon files, as well as the default fonts, colours and other settings.

Font files are contained in a fonts folder in the .rockbox directory of your device. You don’t in fact need to create custom fonts for your theme, and can make use of any existing fonts in this folder that are installed as part of rockbox. Fonts are called by referring to their filename.

Assets, image files you load for the visuals of your theme, are stored in a folder named after your theme inside the wps folder. The name should be the exact same name used for the config file, and should be used across all theme files.

Images themselves are exclusively in the bmp format, however there is no need to worry about this yet as there will be an entire chapter dedicated to them.

What’s next?

Over the next few chapters, we will start with a blank slate. Working from nothing, we will make a theme up from scratch and cover some core topics of the theming system by example. I highly recommend following along, if you can, to get a good feel for the system.