The Viewport

At it’s simplest, making Rockbox themes is all about making what are called Viewports. Viewports provide an easy and reliable way to position and control visual elements on the screen. They will be your main way of bringing a theme design to life.

Lets think of our device’s screen like a sheet of paper. Creating a Viewport is like cutting a rectangular shape out of that piece of paper. We have to decide where to cut it, and how tall or wide to cut.

(image of cutting)

The most basic of Viewports works just like this. Two values for position, X and Y, and two values for width and height, H and W. In the example below you can also see a 5th value, this designates the font a Viewport will be drawn with, which we’ll take a look at in a minute.

# Basic Viewport
# %V(x,y,width,height,font)
%V(0,0,32,16,-)

In our previous example the Viewport would remain on at all times. But what if we want to control when the Viewport is displayed? Our second type of Viewport, the Conditional Viewport, allows a name to be assigned and then called upon whenever we like.

The name comes first before any other values and the same name can be shared among different Viewports. When you want to then display these Conditional Viewports, a seperate tag is used to call them.

# Calling the Conditional Viewport.
# Generally we place this before the Conditional Viewport.
%Vd(1st_Viewport_Label)
#
# Conditional Viewport
# %Vl(label,x,y,width,height,font)
%Vl(1st_Viewport_Label,8,8,32,64,-)

Thankfully when making a theme we don’t have to code everything. Rockbox provides us with some handy defaults for displaying things like the menus and quicksettings.

These Info Viewports function almost identically to Conditional Viewports just with some different tag names. It’s important to note that you can’t set anything to be drawn inside these Viewports. Despite looking similar to the other Viewports, these function exclusively to tell Rockbox where to draw it’s Menus and Quicksettings displays.

# Calling the Info Viewport
%VI(Info_Menu)
#
# Info Viewport Declaration
# %Vi(label,x,y,width,height,font)
%Vi(Info_Menu,8,42,200,100,-)

There are a number of Tags which allow us further control over parts of displaying Viewports. By default Viewports will make some assumptions that are not crucial to their function, which provides a simpler syntax. Rockbox gives us the opportunity to change these values through the use of Modifier Tags that are used after a Viewport is defined.

Rockbox provides us with two layers to draw our theme on. By default all Viewports will be drawn on the Foreground layer, but we can designate a Viewport to be drawn on the Backdrop by attaching a %VB tag to any Viewport declaration.

%V(x,y,w,h,f)%VB

However if we leave it like this, more than likely you’ll find that nothing will show up on your screen.The Backdrop layer will typically not update itself. Hence, whenever a Viewport is drawn in the Backdrop, the same area needs to be cut out in the Foreground.

# Our Backdrop drawing layer
%V(x,y,w,h,f)%VB
#
# Our Foreground Layer Cutout
%V(x,y,w,h,f)

If we return to our paper metaphor from earlier, the Backdrop layer is basically a separate piece of paper placed underneath. We obviously would not be able to see what is on the sheet underneath unless we cut out a piece from the sheet on top.

Easily one of the most common Viewport Modifiers,