Guide to writing Rockbox Skins
------------------------------
1 Introduction
----------------
Rockbox has an ever-evolving themeing engine which allows you to
theme most of the major screens. Blaa blaa
1 The basics
--------------
Rockbox skins are simple text files a different extension depending
on which type of skin the file should be loaded to (i.e *.wps* for the
WPS, *.sbs* for the main menus and browsers, etc).
For the sake of simplicity all explanations assume we are talking about
the WPS, but just about all tags work equally well in any screen (with
some obvious exceptions.)
1.1 Tags
----------
The entire system is built around the idea of *tags*. Tags in skins
are a % followed by one or more letters (case sensitive) which are used
as placeholders for actual data (usually text being displayed).
For example::
%ia - %it
Will display the current track's artist (%ia) a - and the current tracks
title (%it).
Tags can also have parameters (%xd(foo, 1) ) which are simply comma
seperated (with spaces between items being optional, however *strongly*
recommended for readability.)
Finally, some characters are special (i.e %) so they need to be 'escaped'
to display. %% will display % on the screen.
Any other text which the parser doesn't recognise as tags will siply be
displayed on the screen as static text.
1.2 Lines
-----------
Each line in the skin file is equivilant to a line on the display.
A *very* limited set of tags will break this behaviour by forcing the
next line to show up on the current line, but this can be mostly ignored.
Lines can also swap between various sets of tags (or text) using *sublines*.
Sublines are simply sets of tags seperated by a semi-colon (;).
Each subline will be displayed for 2 seconds unless the *timeout* tag
is used to change that value. (%t(timeout)).
Lines by default are static. If the line doesn't fit in the display
it will not scroll unless the %s tag is used to tell it to scroll.
1.2.1 Text alignment
--------------------
Text is always drawn from the left of the display however tags are provided
to position the text on the left, middle or right of the display.
%al
1.3 Conditionals
------------------
Most tags can have more than one value. %ia (current track artist)
comes from the file which may not have that value set. When that happens
%ia will show nothing, so you could end up with a line like::
01 - - Some song!
To only display a tag if the tag has a value we use conditionals.
Conditionals are in the form::
%?xx<values>
where xx is the tag name and values is a pipe (|) seperated list of
lines (possibly including sublines) to display depending on the value
of the tag. For text tags the "value" is either "has text" or "no text/blank".
Examples::
%?ia<%ia>
Will only display the track artist if it is avialable.
%?ia<%ia|No artist>
Will display "No artist" if it isnt available.
%?mm<Off|All|One|Shuffle|A-B>
Will show the text representation for each of the repeat modes.
This syntax can be difficult to read when the number of options is
more than a few so the *%if()* tag is an alternative::
%?if(%mm, >=, 1)<Repeat enabled>
will display "Repeat enabled" if any repeat mode is enabled.
Conditionals can of course be nested::
%?ia<%?it<%ia - %it|%ia>|%fm;%fb>
Will display "Artist - Title" of both are present, or just Artist if
artist is present but title isnt. If neither are present the line will
alternate between the filename and the files bitrate.
2.0 Viewports
-------------
Normally the skin will cover the entire display and each line in the
file represents the equivilant line in the display. Using viewports
allows you to position the text lines anywhere on the screen.
By default every skin has an initial viewport which covers the full
screen and uses the font specified in the settings. This viewport will
not draw anything if any other viewports are specified.
2.1 Declaring Viewports
-----------------------
::
%V(x, y, width, height, font id)
Where:
*x* is the x pixel of the rectangle to draw in.
*y* is the y pixel of the rectangle to draw in.
*width* is the width of the rectangle.
*height* is the height of the rectangle.
*font id* is the font number to use for the viepworts text (1 means UI font).
For example::
%V(0, 100, 50, 50, 1)
will create a viewport with the top left corner at (0,100) and bottom
right corner at (50, 150).
Once a viewport is declared all lines following it (untill the next viewport)
will be drawn in this rectangle.
2.2 Conditional Viewports
-------------------------
You may want to display