CustomWPS < Main

Downloads
release
dev builds
extras
themes
Documentation
manual
wiki
device status
Support
forums
mailing lists
IRC
Development
bugs
patches
dev guide
Donate
Wiki > Main > DocsIndex > CustomWPS
---+!! Custom WPS Display - File Format Specifications

%TOC%

---

---++ Description / General Info

   * The Custom WPS Display is used as a means to customize the while playing screen or Custom Status Bar to the user's likings. This guide was originally designed for the While Playing screen only, but unless explicitly noticed everything applies to the Custom Status Bar and the FM Screen as well.
   * After editing the .wps, .sbs or .fms file, "play" it to make it take effect.
   * All characters not preceded by % are displayed as typed.
   * Everything that follows a # in a line (including the newline character) is a comment.
   * The file size isn't limited, but the content is. If your WPS file is too complex, only the first part of it will be loaded and used.
   * Any text, including newlines, will be treated as text and will thus take up a line on the screen, unless the ONLY thing on the line is a non-text tag and a newline. Non-text tags are, for example, the status bar tags and the tags for image displaying.
   * For a simpler guide to making your own WPS, see the SimpleGuideToWPSMaking.
---

---++ File Location

Custom WPS files may be located anywhere on the drive, although it's recommend to organize them in the =".rockbox/wps/"= directory. The only restriction is that they must end in .wps. When you PLAY a .wps file, it'll be used for the future WPS screens. If the "played" wps file is located in the /.rockbox folder, it'll be remembered and used for subsequent restarts. Filenames in the /.rockbox folder must be no more than 24 characters long. Images will be looked for in the same-named folder in the =".rockbox/wps/"= directory.

---

---++ How To Create A .wps File

Quite simply, enter the WPS code in your favourite text editor, Notepad on Windows works fine. When you save it, instead of saving it as a .txt file, save it as a .wps file. Example: Instead of Rockbox.txt, save the file as Rockbox.wps. To make sure non english characters display correctly in your WPS you must save the .wps file with UTF-8 character encoding. This can be done in most editors, for example Notepad in Windows 2000 or XP (but not in 9x/ME) can do this.

---

---++ Tags

---+++ Viewports

By default, a WPS fills the whole screen, and that screen is split into lines. Viewports allow you to specify a rectangular window in this screen, complete its own foreground/background colour. For the WPS, all lines before the first viewport declaration are drawn in the default (full-screen) viewport, and lines after a viewport declaration are drawn within that viewport. In Custom Status Bars, you can only load images in that default viewport. You cannot draw them or display text in it.

The syntax for a viewport declaration is as follows: %V(x,y,[width],[height],[font]) - where: x is the x pixel, y is the y pixel (0,0 being top left). width is the pixel width of the viewport, using '-' means the full width. height is height of viewport ('-' is full height). font is the font number. 0 is the built in font, 1 is the user font, 2-9 are skin loaded fonts (see below)

Notes:
   * In the Custom Status Bar, you must use viewports. You must not draw into the default full-screen viewport. However, loading images in the default vp is OK.
   * If any viewports are defined, you cannot display text in the default viewport (use it for images only)
   * Viewports cannot be layered transparently over one another. Subsequent viewport definitions will be drawn over any other viewports already drawn onto that area of the screen.
   * Only the x and y values need to be specified. The rest can be left empty if you want to use their default values (use '-' to achieve this, e.g. %V(0,0,-,-,1)).
      * default width/height is the remaining part of the screen
      * default font is the user font
      * default colour (16 bit lcd's) is the theme colours
      * default shade (2bit lcd's) is black FG on white BG
   * The x and y values may be negative which means "pixels from the far edge".. i.e x == -50 means 50 pixels from the right edge
   * The x, y, width and height value may be specified as percentages, the actual value will be calculated from the target's display at load time. Percentage parameters can be mixed with normal ones. Percentages can carry upto 1 fractional digit for increased precision. Example: %V(10.5%,10,80%,80,-)
   * The width and height values may also be negative which means almost the same as above (e.g. %V(50,-,-50,-,-) will go from 50 to 170 on a 220-pixel display).

---++++ Conditional Viewports
Any viewport can be conditionally displayed with minor changes to the above syntax.

| *Tag* | *Description* |
| %Vl('identifier',....) | Preload a viewport for later display. 'identifier' is a single lowercase letter (a-z) and '....' is the same as the usual %V tag (above) |
| %Vd('identifier') | Display the 'identifier' viewport. e.g <literal>%?C&lt;%C%Vd(a)|%Vd(b)&gt;</literal> will show viewport 'a' if album art is found, and 'b' if it isnt. |

   * Viewports can share identifiers so you don't end up with bloated code like =%?C&lt;%V(da)%V(db)%V(dc)|%V(de)%V(df)%V(dg)&gt;=.
   * The conditional viewport display tag must come before the preload tag.

---++++ Info Viewport (Base Skin (.sbs) only)
| *Tag* | *Description* |
| %Vi(label,....) | This viewport is used as Custom UI Viewport in case the theme doesn't have a ui viewport set in the theme.cfg. Using '-' for the label means it is used by default. Having this is strongly recommended since it makes you able to use Custom Status Bars with other themes. If *label* is set this viewport can be selectivly used as the Info Viewport using the %%VI tag |
| %VI(label) | Set the Info Viewport to use the viewport labeled *label* |
| *LCD type* | *Colour values* |
| Mono  | no colours. tag ignored |
| Greyscale  | in the range 0 (= black) to 3 (= white) |
| Colour  | 6-digit RGB888 colours - e.g. !FF00FF |

---++++ Viewport Colours
| *Tag* | *Description* |
| %Vf(colour) | colour is used for the remainder of the viewports foreground colour. |
| %Vb(colour) | colour is used for the remainder of the viewports background colour. |
| %Vg(start, end [, text]) | start end and optional text colour for gradient coloured lines. |
These need to be before any other tags after a %V() line or scrolling lines will not work as expected.

---++++ Viewport Line Text Styles
| *Tag* | *Description* |
| %Vs(mode[, param]) | set the viewport text style to 'mode' for the remainder of the viewport |
Mode is:
| *Mode* | *Description* |
| clear | restore the default style |
| invert | draw the line inverted |
| color | Draw the text coloured the value given in param. Functionally equivalent to using the %Vf() tag |
| gradient | Draw the next *param* lines using a gradient. by default the gradient is over 1 line. %Vg(gradient,2) will use 2 lines to fully change from the start colour to the end colour |

---++++ Viewport Draw Layer
| *Tag* | *Description* |
| %VB | Draw on the backdrop layer |

Rockbox uses two framebuffers when it does a screen redraw. The bottom layer is used for the backdrop image (the static parts of the display behind text for example), and the upper layer (the text/images).
Using this tag you can tell the skin engine to instead draw everything in this viewport onto the backdrop layer instead of the foreground layer. *Don't* draw text here as it may not work too well.
If the skin has this any %X() tag will be ignored and the whole screen will have a solid background (with the colour specified in the settings), so to get the most out of this feature:
   1 Add a full screen viewport at the start of the skin .. i.e %V(0,0,-,-,-) %VB
   1 Use %x(filename, 0, 0) to draw a backdrop image (If you want one!)
   1 Then add %V(0,0,-,-,-) and continue with your skin as normal. Any viewports you want drawn on the backdrop need the %VB tag but otherwise code as normal.

---+++ Draw a rectangle! (optionally with a gradient)
| *Tag* | *Description* |
| %dr(x,y,width,height[colour1[,colour2]]) | Colour a rectangle at pixel (x,y), width/height can be - to fill the viewport. |
if both colours are left out the viewports foreground colour will be used
if one colour is specified it will fill the rectangle that colour.
if both colours are specified it will gradient fill the rectangle.


---+++ Fonts
| *Tag* | *Description* |
| %Fl(id,filename,glyphs) | id is the number you want to use in viewport declerations, 0 and 1 are reserved so can't be used. filename is the font filename to load. glyphs is an optional specification of how many glyphs to reserve memory for. This should be large enough to prevent frequent glyph loading from disk. The default is 256 glyphs if not specified. fonts live in /.rockbox/fonts/ e.g %Fl(2,12-Font.fnt,150) |

---+++ Status Bar
These tags override the player setting for the display of the status bar, they must be on their own line.

| *Tag* | *Description*  |
| %we | Status Bar Enabled |
| %wd | Status Bar Disabled |
| %wi  | Display the inbuilt statusbar in the current viewport |

It can also be used for the Custom Status Bar

---+++ ID3 Tag Info
Remember that this information is not always available, so use the conditionals to show alternate information in preference to assuming.

| *Tag* | *Description* |
| %ia | ID3 Artist* |
| %ic | ID3 Composer* |
| %iA | ID3 Album Artist* |
| %id | ID3 Album Name* |
| %iG | ID3 Grouping |
| %ig | ID3 Genre Name |
| %in | ID3 Track Number* |
| %it | ID3 Track Title |
| %iC | ID3 Comment |
| %iv | ID3 Version (1.0, 1.1, 2.2, 2.3, 2.4 or empty if no ID3 tag) |
| %iy | ID3 Year |
| %ik | ID3 Disc Number |
If a cuesheet is associated with the current playing track (and cuesheet support is enabled), the starred items above will be retrieved from the cuesheet instead of the audio track
---+++ Next Track Info
| *Tag* | *Description* |
| %Ix | Next song ID3 tag info |
| %Fx | Next song file info |
| %Dx | Next song directory info |

You can also display information about the next track in the playlist. If you use the uppercase versions of the I, F and D tag groups they will refer to the next song instead of the current one.

Example: %Ig is the genre name used in the next track and %Ff is the audio frequency of the next track.

Take note that the next song information WILL NOT be available at all times, but will most likely be available by the end of a song. We suggest you use the conditional display tags when displaying information about the next song, just in case.

---+++ Power-Related Information
Tags pertaining to power - namely battery level and charging.

| *Tag* | *Description* |
| %bl | Show numeric battery level in percent. Can also be used in a conditional: <literal>%?bl(-1|0|1|2|...|N)</literal> <br />where the -1 value is used when the battery level isn't known (it usually is). Can also be used as a bar (See [[#Bar_Tags]]) |
| %bv | Show the battery level in volts |
| %bt | Show estimated battery time left or -1 if no runtime data is defined in target config file |
| %bp | "p" if the charger is connected (only on targets that can charge batteries) |
| %bc | "c" if the unit is currently charging the battery (only on targets that have software charge control or monitoring) |
| %bs | Sleep timer - Time left until stop |

---+++ Real Time Clock
Tags allowing to add a clock to your WPS. They will be empty if the time isn't set correctly.

| *Tag* | *Description* |
| %cc | Is there a RTC? |
| %cd | day of month (01..31) |
| %ce | day of month, blank padded ( 1..31) |
| %cf | use for a conditional for 12/24 hour format. <literal>%?cf&lt;24 hour stuff|12 hour stuff&gt;</literal> |
| %cH | hour (00..23) |
| %ck | hour (0..23) |
| %cI | hour (01..12) - (that's a c and an uppercase i) |
| %cl | hour (1..12) - (and this is a c and a lowercase L) |
| %cm | month (01..12) <br />Can also be used in a conditional tag: <literal>%?cm&lt;January|February|March|April|May|June|July|August|September|October|November|December&gt;</literal>  |
| %cM | minute (00..59) |
| %cS | second (00..60) |
| %cy | last two digits of year (00..99) |
| %cY | year (1970...) |
| %cP | upper case AM or PM indicator |
| %cp | lower case am or pm indicator |
| %ca | abbreviated weekday name (Sun..Sat) |
| %cb | abbreviated month name (Jan..Dec) |
| %cu | day of week (1..7); 1 is Monday <br />Can also be used in a conditional tag: <literal>%?cu&lt;Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday&gt;</literal>  |
| %cw | day of week (0..6); 0 is Sunday <br />Can also be used in a conditional tag: <literal>%?cw&lt;Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday&gt;</literal>  |

For example, ="%ca, %cb %cd, %cH:%cM:%cS"= will display (assuming it's January 1st, a Sunday, at 04:10 and 42 seconds) ="Sun, Jan 01, 04:10:42"=.

The tags have values only if the RTC is set properly. This means that to avoid having empty values displayed like =", , ::"=, you can use a conditional like this: ="%?cc&lt;%ca, %cb %cd, %cH:%cM:%cS|RTC needs setting!&gt;"=

---+++ File Info
| *Tag* | *Description* |
| %fb | File Bitrate (in kbps) |
| %fc | File Codec (e.g. "MP3" or "FLAC")<br />This tag can also be used in a conditional tag, <literal>%?fc&lt;mp1|mp2|mp3|AIFF|wav|vorbis|flac|mpc|a52|wavpack|alac|aac|shorten|SID|ADX|NSF|speex|SPC|APE|WMA|unknown&gt;</literal> <br />The codec order is as follows: MP1, MP2, MP3, AIFF, WAV, Ogg Vorbis (OGG), FLAC, MPC, AC3, <nop>WavPack (WV), ALAC, AAC, Shorten (SHN), SID, ADX, NSF, Speex, SPC, APE, WMA. See the AFMT_* enum in [[http://git.rockbox.org/?p=rockbox.git;a=blob;f=apps/metadata.h;hb=HEAD][apps/metadata.h]] |
| %ff | File Frequency (in Hz) |
| %fk | File Frequency (in KHz) |
| %fm | File Name |
| %fn | File Name (without extension) |
| %fp | File Path |
| %fs | File Size (In Kilobytes) |
| %fv | "(avg)" if variable bit rate or "" if constant bit rate |
| %d(1) | First directory from end of file path. |
| %d(2) | Second directory from end of file path. |
| %d(3) | Third directory from end of file path. |

Example for the the %d(N) commands: If the path is "/Rock/Kent/Isola/11 - 747.mp3", %d(1) is "Isola", %d(2) is "Kent"... You get the picture.

---+++ Playlist/Song Info
| *Tag* | *Description* ||
| %pb(x,y,width,height,filename.bmp) | [[#Bar_Tags][Progress Bar]]<br /><strong>Archos Player/Studio:</strong> This will display a 1 character "cup" that empties as the time progresses. (only %pb) <br /><strong>Others:</strong> This will replace the current entire line with a 6 pixels high progress bar if no bitmap and other parameters are defined. Optionally, you can set the image to use, as well as its position and size. Any parameter can be set to the default by using a dash (-). ||
| %pf | *Archos Player/Studio only:* Full-line progress bar + time display ||
| %px | Percentage Played In Song. Can also be used in a conditional to create custom progress indicators. ||
| %pc | Current Time In Song  (when used with %if() returns the number of seconds elapsed)||
| %pe | Total Number of Playlist Entries ||
| %pm | Peak Meter The entire line is used as volume peak meter. ||
| %pL | Show the left channel peak meter value. Can also be used in a conditional: <literal>%?pL(0|1|2|...|N)</literal> <br />. Can also be used as a bar (See [[#Bar_Tags]]) ||
| %pR | Show the right channel peak meter value. Can also be used in a conditional: <literal>%?pR(0|1|2|...|N)</literal> <br />. Can also be used as a bar (See [[#Bar_Tags]]) ||
| %pn | Playlist Name (Without path or extension) ||
| %pp | Playlist Position ||
| %pr | Remaining Time In Song (when used with %if() returns the number of seconds remaining) ||
| %ps | Shuffle. Shows 's' if shuffle mode is enabled. ||
| %pt | Total Track Time  (when used with %if() returns the number of seconds the track runs for)||
| %pv | Current volume in decibels (dB). Can also be used in a conditional: <literal>%?pv&lt;Mute|...|0 dB|Above 0 dB&gt;</literal> Can also be used as a bar (See [[#Bar_Tags]]) ||
| %pS | Track is starting (optionally with a number for how many seconds the tag should stay true for after the song starts) Default time is 10s if no number used. <verbatim>%?pS(7)<in first 7s of track|rest of track></verbatim> ||
| %pE | Track is ending (optionally with a number for how many seconds the tag should stay true for before the song ends) Default time is 10s if no number used <verbatim>%?pE<in last 10s of track|rest of track></verbatim> ||
| %Sp | Current playback pitch ||

---+++ Playlist viewer

This allows you to display some information for the upcoming tracks in the playlist (instead of just the next track).
| *Tag* | *Description* ||
| %Vp(start,skin code to render) | Display the playlist viewer in the current viewport. The *entire* viewport will be used, so don't expect other tags in the same viewport to work well ||
   * start - the offset from the current playing track for the playlist to start showing (0 is start at the current track, 1 is the next track, etc)
   * "skin code to render" is a single line of code which should get displayed. It can have conditionals and sublines to make it interesting. Will be repeated for each line in the viewer
example: <literal>%Vp(1, %pp - %?it&lt;%it|%fn&gt;)</literal> will display the playlist position, then either the track title (from id3) or the filename. The viewer will display as many tracks as will fit in the viewport.

---+++ Runtime Database and Replaygain
| *Tag* | *Description* |
| %rg | Replaygain value in use (x.y dB). If used as a conditional, Replaygain type in use: <literal>%?rg&lt;Off|Track|Album|TrackShuffle|AlbumShuffle|No tag&gt;</literal> |
| %rp | Song playcount |
| %rr | Song rating (0-10). This tag can also be used in a conditional tag, <literal>%?rr&lt;0|1|2|3|4|5|6|7|8|9|10&gt;</literal> |
| %ra | Database autoscore for the song |

---+++ Hold Switches
| *Tag* | *Description* |
| %mh | "h" if the main unit hold switch is on |
| %mr | "r" if the remote hold switch is on |

Example: =%?mh&lt;Locked|Unlocked&gt;=

---+++ Virtual LED
| *Tag* | *Description* |
| %lh | "h" if there is hard disk activity |

---+++ Repeat Mode
| *Tag* | *Description* |
| %mm | Repeat mode, 0-4, in the order: Off, All, One, Shuffle, A-B |

Example: =%?mm&lt;Off|All|One|Shuffle|A-B&gt;=

---+++ Playback Mode
| *Tag* | *Description* |
| %mp | Play status, 1-9, in the order: Stop, Play, Pause, Fast Forward, Rewind, Recording, Recording paused, FM Radio playing, FM Radio muted |

Example: =%?mp&lt;Stop|Play|Pause|Ffwd|Rew|Rec|Rec pause|FM|FM pause&gt;=

Note: Currently, playing status 0 (stop), is only entered for a brief period of time when the last file in a playlist ends, just before the ï¿½menuï¿½ screen is automatically displayed. Intended future changes in WPS's features will extend the use of the "stop" status.

---+++ Crossfade
| *Tag* | *Description* |
| %xf | Crossfade type, 0-5, in the order : Off, Automatic Track Skip Only, Manual Track Skip Only, Shuffle, Shuffle or Manual Track Skip, Always |

Example: =%?xf&lt;Off|Automatic Track Skip|Manual Track Skip|Shuffle|Shuffle or Manual Track Skip|Always&gt;=

---+++ Images
Images are used to make skins slightly more interesting than just plain text.

Because most uses of images are to display some player/setting state it is usual to create an "image strip" which groups all the images for a single tag into one vertical strip where only one of the images in the strip will be shown (explained below)

| *Tag* | *Short Description* |
| %X(filename.bmp) | Load and set a backdrop image for the Skin. |
| <literal>%x(label, filename.bmp, x, y)</literal> | load and display this image at the desired coordinates (viewport relative) |
| <literal>%xl(label, filename.bmp, x, y [, nimages])</literal> | Preload an image to be displayed later (optionally specifing the number of subimages in this bmp strip) |
| <literal>%xd(&lt;subimage label&gt;)</literal> or <literal>%xd(label[, &lt;subimage number&gt;[, subimage offset]])</literal> | Display a preloaded (sub)image |

---++++ !%X - Load a background image
filename.bmp is the filename of the image to load. If - is used then the background image from the Base Skin or settings will be used. if %X(d) is used NO background image will be used (so only the flat background colour will be used)
---++++ !%x - Load and display an image
   * label is ignored unless %xd() is used with this image, which is not necessary. x,y are the viewport relative pixel coordinates to draw at
---++++ !%xl - Load an image for display with %xd
   * label is some unique identifier for this image. All alphanemrical characters are supported (unicode might also work). If only a single letter is used you may use the shorter form of %xd(&lt;subimage label&gt;) to display it
   * _nimages_ is an optional number of subimages in this bitmap strip. If this isnt specified then the whole image will always be displayed.
---++++ !%xd - Display a preloaded (sub)image
This tag has a few forms. 
   1 The simplest is when the image is *not* a bitmap strip. %xd(label) will display that image in the current viewport at the relative pixel coordinates.
   1 If the image is a bitmap strip: 
      * %xd(label, &lt;subimage number&gt; [, offset]) 
         * label is the label of the image to draw
         * &lt;subimage number&gt; is either a number (1 being the first/top image) of the subimage to draw, *or* a tag which is useable in a conditional to automatically draw the corresponding subimage. (e.g %xd(playmode, %mm) is equivilant to %?mm&lt;%xd(playmode, 1)|%xd(playmode, 2)|%xd(playmode, 3)|%xd(playmode, 4)&gt;
         * offset is an offset into the bitmap strip to add before selecting the subimage. (i.e if there is no "stop" image then the above example would be changed to %xd(playmode, %mm, -1) is equivilant to %?mm&lt;|%xd(playmode, 1)|%xd(playmode, 2)|%xd(playmode, 3)&gt;
      * %xd(&lt;subimage label&gt;) is the final form: ( *only usable if the image label is one letter*) 
         * &lt;subimage label&gt; is a 2 letter combination, the first letter being the image label, the second being the subimage letter, a = 1, b = 2, etc.. z = 26, A = 27
*Notes:*

   * The images must be in a Rockbox compatible format (see table below for model specific BMP compatibility). On color displays, all common sorts of BMP are supported.

   * The size of the LCD screen for each player varies. See table below for appropriate sizes of each device. The x and y coordinates must repect each of the players' limits.

   * ARGB BMP's can be used for transparent images.

   * The colour magenta [R=255,G=0,B=255] is translated as transparent when used in BMP's, and can be used to create transparent (or background colour) parts in images in the WPS.

   * The colour pure cyan [R=0,G=255,B=255] is translated as foreground colour when used in BMP's, and therefore can be used to create images in the WPS that will be foreground dependent.

   * Similarly to the two notes just exposed, if monochrome bitmaps are used (real 1-bit ones) the black parts will use the foreground colour and the white parts will use the background colour (or transparent colour). This method also works on greyscale targets with shades set through %Vf/%Vb. Also, these bitmaps will be smaller and take less skin buffer.

   * The image tag must be on its own line.

   * The ID is case sensitive

   * Images will be searched for in a folder in the =".rockbox/wps/"= directory with the same title as the WPS file. So, for example, if your WPS is titled !RockboxWPS.wps, you need to create a folder titled !RockboxWPS and place your image files inside of it.

   * The coordinates give the position relative to the [[#Viewports][viewport]] the corresponding display bitmap tag (%xd) is in.
---++++ Bitmap Strips
Bitmap Strips are used to display portions of an image. The images you wish to display must be tiled vertically within the "container" image. For example <pre>%xl(M,volume.bmp,134,153,10)
%?pv&lt;%xd(Ma)|%xd(Mb)|%xd(Mc)|%xd(Md)|%xd(Me)|%xd(Mf)|%xd(Mg)|%xd(Mh)|%xd(Mi)|%xd(Mj)&gt;
</pre>

The above code says "Load volume.bmp at coordinates x,y , which contains 10 subimages". So if the "volume.bmp" was 100 pixels high, this would display the top 10 pixels for %xdMa and the next 10 pixels for %xdMb and so on.

Also see the [[#Images][images]] section above for more information about the tag syntax.

---++++ LCD Screen Sizes / BMP Compatibility
| *Player* | *Main LCD Size* | *Main LCD - BMP's* | *Remote LCD Size* | *Remote LCD - BMP's* |
| iriver H1x0 | 160x128 | 1-bit | 128x64 | 1-bit |
| iriver H3x0 | 220x176 | 1-bit, 24-bit, 32-bit | 128x64 | 1-bit |
| iriver H10 (5/6Go) | 128x128 | 1-bit, 24-bit, 32-bit |  _no LCD remote_  |  _n/a_  |
| iriver H10 (20Go) | 160x128 | 1-bit, 24-bit, 32-bit |  _no LCD remote_  |  _n/a_  |
| Archos Recorders | 112x64 | 1-bit |  _no LCD remote_  |  _n/a_  |
| Archos Ondio | 112x64 | 1-bit |  _no remote_  |  _n/a_  |
| iPod Nano | 176x132 | 1-bit, 24-bit, 32-bit |  _no remote_  |  _n/a_  |
| iPod 4G Grey | 160x128 | 1-bit |  _no remote_  |  _n/a_  |
| iPod 4G Color | 220x176 | 1-bit, 24-bit, 32-bit |  _no remote_  |  _n/a_  |
| iPod 5G Video | 320x240 | 1-bit, 24-bit, 32-bit |  _no remote_  |  _n/a_  |
| iPod Mini/Mini2G | 138x110 | 1-bit |  _no remote_  |  _n/a_  |
| iAudio X5 | 160x128 | 1-bit, 24-bit, 32-bit | 128x96 | 2-bit (4 gray levels) |
| Toshiba Gigabeat Fxx | 240x320 | 1-bit, 24-bit, 32-bit |  ?  | ? |
| Toshiba Gigabeat Xxx | 240x320 | 1-bit, 24-bit, 32-bit |  ?  | ? |
| <nop>SanDisk Sansa e200 | 176x220 | 1-bit, 24-bit, 32-bit |  _no remote_  |  _n/a_  |
| <nop>SanDisk Sansa Fuze | 176x220 | 1-bit, 24-bit, 32-bit |  _no remote_  |  _n/a_  |
| <nop>SanDisk Sansa c200 | 132x80 | 1-bit, 24-bit, 32-bit |  _no remote_  |  _n/a_  |
| <nop>SanDisk Sansa Clip(+) | 128x64 | 1-bit |  _no remote_  |  _n/a_  |

---+++ Album Art

It is possible to make your WPS display cover art. See AlbumArt for full details. Both of the following tags are required:

| *Tag* | *Description* |
| %Cl(xpos,ypos,maxwidth,maxheight,[horizontal alignment],[vertical alignment]) | Define the picture settings. [[AlbumArt#The_Cl_tag][More details]]. Horizontal alignment can be 'l', 'r', or 'c', for left, right and center. Vertical alignment can be 't', 'b', or 'c', for top, bottom and center. |
| %Cd | Display the album art bitmap. [[AlbumArt#The_C_tag][More details]] |
| %C | Use in a conditional to check if album art has been loaded |

---+++ Recording Screen tokens (currently only usable in a .sbs skin)
| *Tag* | *Description* |
| %Rp | Does this target have recording? If it doesnt the "true" of this conditional is completely ignored so you don't need to worry about tags which are not recognized on non recording targets |
| %Rm | Currently recording in mono |
| %Rf | Recording frequency/samplerate... conditional always uses the values HWCODEC: <literal>%?Rf | 44 | 48 | 32 | 22 | 24 | 16&gt;SWCODEC: %Rf&lt;96 | 88 | 64 | 48 | 44 | 32 | 24 | 22 | 16 | 12 | 11 | 8&gt;</literal> (remember, your target may not support all of these  |
| %Re | Encoder being used: in the order Wav, aiff, wv, mp3. SWCODEC only! |
| %Rb | Bitrate - SWCODEC (and MP3 only): <literal>%?Rb&lt;8 | 16 | 24 | 32 | 40 | 48 | 56 | 64 | 80 | 96 | 112 | 128 | 144 | 160 | 192&gt;</literal> HWCODEC: Quality setting.. 0-7 inclusive  |
| %Rr  | Does this target currently record? Used in FM screen on HWCODEC targets. |
| %Rh | Recording hour. Used in FM screen on HWCODEC targets. |
| %Rn | Recording minute. Used in FM screen on HWCODEC targets. |
| %Rs | Recording second. Used in FM screen on HWCODEC targets. |

---+++ FM Radio tokens
Some of the radio tokens are better used as a switch for a conditional, i.e. as =%?xx&lt;stuff for true|stuff for false&gt;=.

| *Tag* | *Description* |
| %tp | Does this target have a radio? If it doesn't, the "true" branch of this conditional is completely ignored so you don't need to worry about tags which are not recognized on non radio targets. |
| %tt | Tuner tuned? |
| %tm | Scan or preset mode? Scan is "true", preset is "false" |
| %ts | Is the station in stereo? |
| %ta | Minimum frequency (region specific) in MHz, with two decimal digits |
| %tb | Maximum frequency (region specific) in MHz, with two decimal digits |
| %tf | Current frequency in MHz, with two decimal digits |
| %tr | Current signal strength in dBu |
| %Ti | Current preset id, i.e. 1-based number of the preset within the presets list (usable in playlist viewer) |
| %Tn | Current preset name (usable in playlist viewer) |
| %Tf | Current preset frequency (usable in playlist viewer) |
| %Tc | Preset count, i.e. the number of stations in the current preset list |
| %tx | Does this target have RDS? |
| %ty | RDS name |
| %tz | RDS text |

---+++ Alignment
| *Tag* | *Description* |
| %al | Text is left aligned |
| %aL | Text is aligned left on LTR languages and right on RTL languages |
| %ac | Text is center aligned |
| %ar | Text is right aligned |
| %aR | Text is aligned right on LTR languages and left on RTL languages |
| %ax | The next tag should follow the language direction (what that means is deifned by the individual tag). Currently %Cl and %V support this |
| %Sr | Use as a conditional to define options for left to right, or right to left languages. |

All alignment tags may be present in one line, but they need to be in the order left - center - right. If the aligned texts overlap, they are merged.

---+++ Scrolling
| *Tag* | *Description* |
| %s | Indicates that the line should scroll |

This tag can occur anywhere in a line, given that the text is displayed (see conditionals). You can specify up to 10 scrolling lines. Scrolling lines can not contain dynamic content such as timers, peak meters or progress bars.

---+++ Increasing/Decreasing Volume
| *Tag* | *Description* |
| %mv | Indicates that volume is increasing/decreasing |

This tag can be used to display text or images only when the volume is being changed. If you put a number straight after %mv it will be used as a timeout in seconds (e.g %mv(2.5) will give a 2.5s timeout) between the volume button being released and the tag going false. If no number is specified it will use a 1 second timeout

Can also be used as a conditional, and can be used with conditional viewports for some really neat effects.

---+++ Showing other settings
| *Tag* | *Description* |
| %St(setting name) | Indicates value of the specified setting |
| %St(*bar params*, setting, (setting name)) | Displays the setting value as a bar |

Example: Can be used as a simple tag =%St(skip length)= or with conditionals =%?St(eq enabled)&lt;Equalizer is enabled|Equalizer is disabled&gt;=

---+++ Touchscreen areas
| *Tag* | *Description* |
| %Tp | Indicates if the target has a touchscreen or not |
| %T([label,] x,y,width,height,action,[options]) | Invoke the action when the user presses in the touchscreen area. label is optional and only needed if you wish to link it with a %Tl (see below) |

Action is one of:
| *Action* | *Description* |
| none | do nothing |
| play | play/pause playback |
| stop | stop playback, exit the wps |
| prev | prev track/item |
| next | next track/item |
| wps_prev | prev track |
| wps_next | next track |
| ffwd | seek forward |
| rwd | seek backwards |
| progressbar | seeks to the appropriate position based on the touch |
| shuffle | toggle shuffle mode |
| repmode | cycle the repeat mode |
| volume | sets the appropriate volume based on the touch |
| voldown | decrease volume by one step |
| volup | increase volume by one step |
| mute | mute/unmute playback volume |
| createbookmark | create a bookmark in the currently-playing track |
| hotkey | performs the action assigned to the hotkey |
| menu | go back to the main menu |
| browse | go back to the file/db browser |
| resumeplayback | go back to the last music screen (wps or radio) |
| quickscreen | go into the quickscreen |
| contextmenu | open the context menu |
| playlist | go to the playlist viewer |
| listbookmarks | list the bookmarks for the currently-playing directory or playlist |
| trackinfo | open the track info viewer |
| pitch | go into the pitchscreen |
| setting_inc | increase a config setting (the setting name is the next parameter) Example: %T(10,20,32,32,setting_inc,bass,[options]) |
| setting_dec | decrease a config setting (the setting name is the next parameter) |
| setting_set | set a config setting to a specific value. Example: %T(10,20,32,32,setting_set, repeat, off,[options]) |
| lock | soft lock the touchregions effectivly disableing all regions unless they are the lock action (or have the allow_while_locked option (see below) |
   * Not all config values are supported or work well. Outright unsupported settings will cause the parser to reject the theme. Other settings might not take effect immediately. similar limitations to the options allowed on the quickscreen
Available options:
| *option* | *Description* |
| repeat_press | This region will trigger mulitple times when held (i.e for seeking) |
| long_press | This region will trigger once after it is held for a long press |
| reverse_bar | Reverse the bars touch direction (i.e seek right to left) |
| allow_while_locked | Allows the region to be pressable when the skin is locked by the lock touch action |

---+++ Last Touchscreen Press
| *Tag* | *Description* |
| %Tl | Indicates that the touchscreen is pressed |

This tag can be used to display text or images or a viewport when the touchscreen get pressed (like an On Screen Display). If you put a number straight after %Tl it will be used as a timeout in seconds (e.g %Tl(2.5) will give a 2.5s timeout) between the touchscreen press being released and the tag going false. If no number is specified it will use a 1 second timeout

Can also be used as a conditional, and can be used with conditional viewports for some really neat effects.

This tag can be given a label of a touch region so it only goes true if that region was touched recently. Example: <verbatim>%?Tl(play_button, 1)<some text></verbatim> will display "some text" for one second after the touch region labeled "play_button" is pressed

---+++ Current Screen
| *Tag* | *Description* |
| %cs | Current Screen, returns a number for use in conditionals, values below |
   1 Menus
   1 WPS
   1 Recording screen
   1 FM Radio screen
   1 Current Playlist screen
   1 Settings menus
   1 File Browser
   1 Database Browser
   1 Plugins Browser
   1 Quickscreen
   1 Pitchscreen
   1 Setting chooser
   1 Playlist Catalog
   1 Plugin
   1 Context Menu
   1 System Menu
   1 Time And Date screen
   1 Bookmark browser
   1 Shortcuts Menu
   1 Track Info screen

Example: <verbatim>You are in the %?cs<Main menu|WPS|Recording screen|FM Radio screen|Current playlist screen|etc..></verbatim> or <verbatim>%?if(%cs, =, 2)<This is the WPS></verbatim>

---+++ List Title (.sbs only)
| *Tag* | *Description* |
| %Lt | Title text, use it in a conditional so non list screens dont show a title when they shouldn't) |
| %Li | Title icon. Same order as CustomIcons, except icon 0 is "no icon" |

---+++ Drawing the lists using a skin
The entire list can now be drawn using the skin engine! To do this you need at least one viewport which will be drawn for each item on the screen, and the ui viewport configured (using the %Vi tag).
To make this work do the following:
   1 Setup the ui viewport as normal. As many items as can fit in this viewport will be displayed (Titles are not included and need to be drawn in a seperate viewport manually)
   1 Create one or more viewports with a shared label which you want to display for each item. The x/y position is relative to an imaginary box which each item fits in inside the ui viewport.
   1 Tell the skin to draw the lists using the %LB() tag (see below)

| *Tag* | *Description* |
| %LT[(offset, nowrap)]* | Get the current items text, can be used in normal viewports to get the selected items text |
| %LI[(offset, nowrap)]* | Get the current items icon number, can be used in normal viewports to get the selected items icon number |
| %LN | Get the position of the current item in the list (1-based). Useful for displaying numbered lists |
| %LR | Get the row number on which the current item will be drawn (1-based). Can be used to change the style based on where on the screen the item appears. |
| %LC | Get the column number on which the current item will be drawn (1-based). Can be used to change the style based on where on the screen the item appears. |
| %Lc | Use as a conditional to determine if the current item is the selected item |
| %LB | BAR TAG to show the scroll bar, params/options like other bar types. It still needs a bit of work though. Use as a conditional to find out if the bar is actually needed |
| %Lb(viewport, width, height [,tile]) | specify the viewport label to draw for each item and the size of each item. if the last param is 'tile' it will form a grid instead of a list |

%LI and %LT accept two optional parameters to get a different line option than the one currently being drawn. The first paramter is an offset from the current item. The second can be the word "nowrap" (without quotes) to make the line not wrap if the offset would go past either end of the list

example:
<verbatim>%?cs<%Lb(a,100,20)|> 
%V(0,0,10,-,1)%Vf(aabbcc) 
%?LB<%LB(0,0,10,185, invert)> 
%Vi(-,10,0,-,-35,1) 
%Vl(a,5,5,160,12,1) 
%s%?Lc<%Vg(00ffaa, ff0000, 000000)%Vs(gradient)%>%>%>%ac>zzzzzzz %LT zzzzz%s%?Lc<%ar%<%<%<> 
%V(0,185,-,-,1) 
%s%LT
</verbatim>


---

---++ Conditional Tags
---+++ If/else
Syntax: =%?xx&lt;true|false&gt;=

If the tag specified by "xx" has a value, the text between the "&lt;" and the "|" is displayed (the _true_ part), else the text between the "|" and the "&gt;" is displayed (the _false_ part).

The else part is optional, so the "|" does not have to be specified if no else part is desired. The conditionals nest, so the text in the if and else part can contain all % commands, including conditionals.

---+++ %if() logical comparison tag
Syntax: =%if(tag, operator, operand [,option count])=

This lets you do very simple logical comparissons on other tags.
   * *tag* is the tag to check against
   * *operator* is the comparison to do, any one of: <tt>=, !=, >, >=, <, <=</tt>  (when comparing against a string tag like %ia, only <tt>=</tt> and <tt>!=</tt> work, and it is NOT case sensitive)
   * *operand* is either another tag, a number, or text.
   * *option count* is an optional number to use for the few tags which scale to the amount of options when used as a conditional (i.e <tt>%?pv<a|b|c|d></tt> would have 4 options)

example: <tt>%?if(%pv, >=, 0)<Warning.. volume clipping|coool...></tt>

That says "If the value from %pv (volume) is greater than or equal to 0 then display the warning line, otherwise the cool line."

<tt>%?if(%ia, =, %Ia)<same artist></tt>   <tt><=</tt> this artist and next artist are the same.

---+++ %and() and %or logical operators
Syntax: =%and(tag, [tag, ...])=

This tag allows you to check multiple tags in one conditional instead of doing nested conditionals. %and() will be true if all tags are true, %or() will be true if any tags are true

---+++ Enumerations
Syntax: =%?xx&lt;alt1|alt2|alt3|...|else&gt;=

For tags with multiple values, like Play status, the conditional can hold a list of alternatives, one for each value the tag can have.

Example: =%?mp&lt;Stop|Play|Pause|Ffwd|Rew&gt;=

The last _else_ part is optional, and will be displayed if the tag has no value. The WPS parser will always display the last part if the tag has no value, or if the list of alternatives is too short.

---+++ Skin Variables (Touchscreen only)
| *Tag* | *Description* |
| %vs(name, action, value [,max]) | set a variables value, action is *set* to set the value, *inc* to increment by value, *dec* to decrement by value, *touch* to reset the timeout without changing the value |
| %vg(name) | get a variables value |
| %vl(name [,timeout] | check if the variable changed values in the last 'timeout' |

Variables minimum value is 1 and are set to 1 on skin load.

---

---++ Alternating Sublines
It is possible to group items on each line into 2 or more groups or "sublines". Each subline will be displayed in succession on the line for a specified time, alternating continuously through each defined subline.

Items on a line are broken into sublines with the semicolon ';' character. The display time for each subline defaults to 2 seconds unless modified by using the '%t' tag to specify an alternate time (in seconds and optional tenths of a second) for the subline to be displayed.

Subline related special characters and tags: <verbatim>
  ;  : Split items on a line into separate sublines
  %t  : Set the subline display time. The '%t' is followed by either integer
        seconds %t(5), or seconds and tenths of a second %t(3.5).</verbatim>

Each alternating subline can still be optionally scrolled while it is being displayed, and scrollable formats can be displayed on the same line with non-scrollable formats (such as track elapsed time) as long as they are separated into different sublines.

Example subline definition: <verbatim>
  %s%t(4)%ia;%s%it;%t(3)%pc %pr   : Display id3 artist for 4 seconds,
                                  Display id3 title for 2 seconds,
                                  Display current and remaining track time
                                  for 3 seconds,
                                  repeat...</verbatim>

Conditionals can be used with sublines to display a different set and/or number of sublines on the line depending on the evaluation of the conditional.

Example subline with conditionals: <verbatim>
  %?it<%t(8)%s%it|%s%fn>;%?ia<%t(3)%s%ia|%t(0)></verbatim>

The format above will do two different things depending if ID3 tags are present. If the ID3 artist and title are present :

Display ID3 title for 8 seconds,

Display ID3 artist for 3 seconds,

repeat...

If the ID3 artist and title are not present :

Display the filename continuously.

Note that by using a subline display time of 0 in one branch of a conditional, a subline can be skipped (not displayed) when that condition is met.

---

---++ Bar Tags
Some tags can be used to display a bar which draws according to the value of the tag. To use these tags like a bar you need to use the following params (%XX should be replaced with the actual tag)

<verbatim>%XX(x, y, width, height, filename, [options])</verbatim>

| *param* | *Description* |
| x | X co-ordinate (viewport relative) to start displaying this bar |
| y | Y co-ordinate (viewport relative) to start displaying this bar |
| width | width of this bar (- for the full viewport width) |
| height | height of this bar (- for font height for horizontal bars, viewport height for vertical) |
| options | Any or all of the possible options (a comma separated list) in the next table |

| *option name* | *description* |
| horizontal | Force the bar to be drawn horizontally |
| vertical | Force the bar to be drawn vertically |
| invert | Invert the draw direction (so right to left or top to bottom) |
| slider | Draw an image at the bar's "value/position" over the top of the bar. The centre of the slider indicates current position. The next param must be the loaded image's label. |
| image | Specify the image to use to draw the bar. The next param must be the filename of the image or the loaded image's label. If this option is not used a default image will be drawn instead. |
| backdrop | Specify an image to draw as the bar's backdrop. The next param must be the loaded image's label. |
| nofill | Don't draw the fill bar, only the empty image (use with slider for the desired effect) |
| nobar | Don't draw the bar at all (for use with slider) |
| notouch | Don't create a touchregion for this bar automatically |

To maintain backward compatibility a filename can be given as the first option instead of using the 'image, <id>' tuple.

---++ Other Tags

---+++ Substring
|*Tag* | *Description* |
| %ss(start, length, tag) | Get a substring of another tags value. |

Use - for the length to get the full string starting at the 'start' index (0 being the first character).

---+++ Special characters
<verbatim>
  %%  : Display a '%'
  %<  : Display a '<'
  %|  : Display a '|'
  %>  : Display a '>'
  %;  : Display a ';'
  %#  : Display a '#'
  %(  : Display a '('
  %)  : Display a ')'
  %,  : Display a ','</verbatim>

---

---++ Example Files
---+++!! Example WPS for the iPod 5g

<img width="320" alt="example_wps_ipod5g.png" src="http://www.rockbox.org/twiki/pub/Main/WpsIpod5g/example_wps_ipod5g.png" height="240" /> <br />Download: [[http://www.rockbox.org/twiki/pub/Main/WpsIpod5g/example_wps_ipod5g_V1.1.zip][Example WPS for ipod5g.zip]]

---+++!! Example WPS for the Gigabeat F
<img width="240" alt="example_wps_gigabeat.png" src="http://www.rockbox.org/twiki/bin/viewfile/Main/WpsGigabeatF?rev=1;filename=example_wps_gigabeat.bmp" height="320" /> <br />Download: [[http://www.rockbox.org/twiki/pub/Main/WpsGigabeatF/example_wps_gigabeat_V1.1.zip][Example WPS for gigabeat.zip]]

<br />More examples can be found in user submitted WpsGallery

---

---++ Tools

---+++!! The UISimulator

You can use a [[http://rasher.dk/rockbox/simulator/][Rockbox UISimulator]] to preview your WPS on your Windows PC. Extract the archive for your model and copy your .wps file into the existing subdirectory ="simdisk\.rockbox\wps"=. The directory ="simdisk\"= represents the root of your device. Put some music files into the ="simdisk\"= directory and play them. Change the WPS by choosing your WPS from the menu, just as you would on the player itself. Adding the ==--debugwps== command line switch will provide very detailed information on the loaded WPS that will help you with the design process.

---+++!! The checkwps tool

==checkwps== is a tool that will check whether a WPS is compliant to the syntax. It will also display various levels of debugging information. The maximum level of debugging information is equivalent to what the UiSimulator outputs.

<verbatim>
Usage: checkwps [OPTIONS] filename.wps

OPTIONS:
        -v      verbose
        -vv     more verbose
        -vvv    very verbose</verbatim>

This tool is included in a regular SVN checkout. To compile it, cd to the =tools/checkwps/= directory and run the =./buildall.sh= script - this will create many versions of checkwps, one for each target device.

---+++!! Vim

In the Vim text editor, a script [[http://www.vim.org/scripts/script.php?script_id=2550][here]] provides syntax highlighting for WPS files. 
---
r238 - 16 Sep 2012 - 01:19:40 - HaydenPearce
Parents: DocsIndex