Some loose notes on the Rockbox Theme engine feature that allows you to theme the menu lists of the Ui. Mostly covering my own exploration and experimentation to achieve desired results.

This feature is largely unexplored territory in terms of it’s potential. Only a very small handful of people have made themes from scratch with this feature, gevaerts who is a Rockbox developer and Frankenpod who is one of the most experienced creators of themes. Recently with adwaitapod 3.0, I utilised the feature to create the highly custom user preference settings menus, but this is as far as I’ve gotten.

---

Setting up a basic list

To create a basic list, you need three elements. A %Lb tag, a %Vi viewport, and a %Vl Viewport. The %Lb and %Vl functions must have the same title, this will define an entry in your menu. The %Vi or main viewport, will define the range of space we want our menu entries to tile within. Here’s a quick example:

%Lb(entry,100,10)
%Vi(-,0,0,100,60,-)
%Vl(entry,0,0,100,10,-)text

From the above example, we would get a simple menu where 6 items would be displayed on screen.

Single Item Display

So for adwaitapod, I wanted to have the numerical selection screens be like the libadwaita style, where you see a single number and can increase or decrease it. To achieve this in Rockbox we need to first set up a %Lb function that wont render, then using a %Vl viewport we render the numbers by utilising the %LT current text item.

%Vd(numbers)%Lb(hide,1,1)
%Vl(hide,0,0,1,1,-)
%Vl(numbers,46,45,75,25,-)%LT

It should be noted here that the hide functions are set to 1x1, instead of 0x0 as you might instinctively do. This is done to prevent crashes due to memory bugs, you might also need to test this on different hardware as it can still crash like this.

If all else fails, use the smallest font you can possibly make, fit the viewport to that and then colour it to the background (if possible).

Themed Scroll Bar

Arguably the best feature of theming lists, themed scroll bars, this has a bit of setup to keep in mind. For starters, you want to treat it like any old progress bar, so setup a viewport where you want this scrollbar. Next set up an %LB tag using the basic progress bar setup.

This will initially not function like you’d expect, partly because it’s still basically just a progress bar but based on your position on a page. To fix this we can use the invert and nobar parameters, then add a slider from an image that will be our actual scrollbar.

Setting a backdrop on the scroll bar wont work like it does for other progress bars, so here to do that you can use an identical viewport but rendered on the backdrop layer and display your image.

%Vl(scrollbar,310,30,5,205,-)%VB
%xd(scroll_backdrop)
#
%Vl(scrollbar,310,30,5,-,-)
%LB(0,0,5,210,invert,noborder,nobar,slider,scrollbar_image)

One last note is that it’s crucial to still consider the user’s preferences and settings. Make sure to use %?LB to only call the scrollbar when needed, and use the %St tag to respect the user’s scrollbar position settings.

Incorporating with a Lockscreen

Switching off viewports to create a Lockscreen is pretty similar to how it works with regular list menus. You need to set up your %Lb and %VI loading with hold triggers. You will want to set up a screen flushing viewport to clear the menu from the screen, this can just be a simple fullscreen viewport.

%?mh<%Vd(flush)|%Lb(entry,100,10)%VI(range)>
#
%Vl(entry,0,0,100,10,-)text
#
%Vl(flush,0,0,-,-,-)

One thing to note if you are using a themed scrollbar: you will want to place the code setting up the scrollbar after all this, and the code rendering the scrollbar before. This prevents strange clipping after deactivating the lockscreen.

Styling Menu Lists

You can style your menu item selectors using themed lists, adding images, extra text and more. This is done simply by making more viewports and adding your elements. Use %?Lc to only show elements on the currently selected item.

One important rule to follow here is that in order for the current selected text to scroll, it must be placed last in the viewport order. If there is anything else placed after the viewport with %LT, then the text wont be able to scroll

%Vl(main,0,0,10,26,-)%?Lc<%xd(left_corner)>
%Vl(main,7,0,20,26,-)%xd(icon)
%Vl(main,292,0,10,26,-)%?Lc<%xd(right_corner)>
%Vl(main,27,0,265,26,-)%s%LT

Multiple Viewports

Setting up multiple viewports is a little less straight forward than with the default menu system as there are a lot of out-of-bounds crashes than can be encountered if you don’t set up correctly. From what I can tell, having a fallback viewport is crucial to avoiding any crashes and errors.

This is done by creating a default viewport before any of the viewports you intend to use like the following:

%Vi(-,3,28,302,-,-)
%Vi(Main_Menu,3,28,302,-,-)
%Vi(Sub_Menu,3,55,302,-,-)
%Vi(Half_Menu,3,28,182,-,-)

These viewports can then be called alongside your %Lb viewports wherever you manage those.

Don’t draw on the Backdrop

It’ll crash :(