Downloads
release
dev builds
extras
themes
Documentation
manual
wiki
device status
Support
forums
mailing lists
IRC
Development
bugs
patches
dev guide
Search
Search
| Go
Wiki
>
Main
>
CustomizedDisplayGuide
---+++ %BLACK%Comprehensive Yet Comprehendible Customized Display Guide%ENDCOLOR% --- Description / General Info<br />%BLACK%File Creation<br />File Location%ENDCOLOR%<br />Themes<br />WPS and SBS<br /> Tags<br /> Positioning<br /> Alignment<br /> Scrolling<br /> Alternating Sublines<br /> Conditional Tag<br /> Viewports<br /> Conditional Viewports<br /> Info Viewport<br /> Base Skin on/off<br /> Id3 Tags<br /> Current Id3 Tags<br /> Upcoming Id3 Tags<br /> File Tags<br /> Current File Tags<br /> Upcoming File Tags<br /> Playlist Tags<br /> Progress Bar<br /> Playlist Viewer<br /> Playback Mode Tag<br /> Repeat Mode Tag<br /> Hold Switch Tags<br /> Crossfade Tag<br /> Power Related Information<br /> Drive Actvity Tag<br /> Runtime Database and Replay Gain<br /> Real Time Clock<br /> Images<br /> LCD Screen Sizes and BMP Compatibility<br /> Basic Image Tags<br /> Bitmap Strips<br /> Album Art<br /> Other<br /> Recording Screen Tokens<br /> Current Screen<br /> Touchscreen<br /> Other Settings<br /> Other Tags<br /> Tools --- ---++++ Description / General Info<a name="DescriptionGeneralInfo"></a> <br />The rockbox interface can be modified to your liking using a custom theme, wps, and base skin. The theme, saved as a .cfg file, defines the font, icons, basic colors, and links the wps and base skin together. The wps, saved as a .wps, is displayed during audio playback, and presents predominantly audio related information. The base skin, saved as a .sbs, skins the menu and file browser, and is capable of presenting various information.<br /><br />This guide is based on the "CustomWPS" guide. Another, less-featured but much simpler guide is found here, "SimpleGuideToWPSMaking". ---+++++ <span style="color: black;">%OLIVE%File Creation<a name="FileCreation"></a>%ENDCOLOR%</span> <br />The .cfg, .wps, and .sbs files can all be written in a simple text program such as notepad, gedit, pspad, etc. To create the files simply save them with the appropriate extension, e.g. a new theme could be saved as "newtheme.cfg". The other files, .wps and .sbs, are saved the same way. To ensure that non-english characters are saved, use UTF-8 encoding when you save. ---+++++ File Location<a name="FileCreation"></a> <br />While files can be placed anywhere on your device's drive, the ".rockbox" folder contains folders which make file organization easy and efficent. Theme files (.cfg), are placed in the /.rockbox/themes folder. The wps and base skin flies (.wps)(.sbs), are placed in the /.rockbox/wps folder. Images specific to the .wps or .sbs must be placed in a folder inside the /.rockbox/wps directory, and the folder must share names with the .wps and/or .sbs.<br /><br />Using a wps called "newwps" as an example, you place the newwps.wps file in the /.rockbox/wps directory (meaning its location is /.rockbox/wps/newwps.wps), and also create a folder in that directory named "newwps" (its location is /.rockbox/wps/newwps). Now all images can be placed in the /.rockbox/wps/newwps folder.<br /><br />Fonts, Icons, and Backdrops all have folders located in the /.rockbox directory. Also, keep in mind that the filenames under the /.rockbox directory must be no more than 24 characters. ---++++ Themes<a name="Themes"></a> <br />Theme files are extremely simple and also work differently than wps or base skin files. This section is the solely devoted to themes, the information here does not apply to the wps or sbs files. Below is an example .cfg file.<br /><br /> wps: /.rockbox/wps/example.wps<br /> sbs: /.rockbox/wps/example.sbs <br /> font: /.rockbox/fonts/example.fnt <br /> foreground color: FFFFFF <br /> background color: 000000 <br /> statusbar: custom <br /> backdrop: /.rockbox/backdrops/example.bmp <br /> line selector start color: FFFFFF <br /> line selector end color: FFFFFF <br /> selector type: bar (gradient) <br /> iconset: /.rockbox/icons/example_small.bmp <br /> viewers iconset: /.rockbox/icons/example_small_viewers.bmp <br /> line selector text color: 000000<br /> filetype colours: /.rockbox/themes/filename.colours<br /> ui viewport: ????????????????????????<br /><br />The first line links the theme to a .wps, and the next connects it to a .sbs. Now, after the theme has been selected, it loads those two files. The user font is defined in the font line. The foreground color changes the color of the font and several other foreground objects, and the background color is used in viewports and/or if the backdrop should fail to load. Colors are defined using standard rgb hex codes. If the statusbar line reads "custom" then a custom wps is used, by writing "top" or "bottom" in, the default .sbs is used and located at either the top or bottom. The backdrop line links a backdrop to the theme. This backdrop is used for both the .wps and .sbs unless it is over-ridden by one of those files. The line selecter is the highlighted bar that shows you what entry is selected. A gradient can be used by writing in two different colors in the "start color" and "end color" lines. The other options for selector type are, "bar (inverse)" which makes the text on the selected line the background color, and changes the selector bar to the foreground color, ??????. The iconset and viewers inconset are linked to the icons. The line selector text color defines the color of the text on a line that is higlighted. Filetype colours can be read about here: CustomFiletypeColours. ---++++ WPS and SBS<a name="WpsAndSbs"></a> All information below is applicable to both the .wps and .sbs unless otherwise stated. "Tag" refers to a code (example: %al) that displays information, displays or loads images, positions an object or otherwise executes some action. ---++++ Tags<a name="Tags"></a> ---+++++ Positioning<a name="Positioning"></a> The following codes are applicable to text and in some cases images. ---++++++ Alignment<a name="Alignment"></a> <table align="left" border="0"> <tbody> <tr align="center"> <td align="center">Tag</td> <td>Action</td> </tr> <tr> <td>%al</td> <td>Aligns to the left</td> </tr> <tr> <td>%ac</td> <td>Aligns in the center</td> </tr> <tr> <td>%ar</td> <td>Aligns to the right</td> </tr> </tbody> </table> For Right to Left language support, us these codes: <table align="left" border="0"> <tbody> <tr align="center"> <td>Tag</td> <td>Action</td> </tr> <tr> <td>%aL</td> <td>Aligns to the left on LTR languages and to the right on RTL languages</td> </tr> <tr> <td>%aR</td> <td>Aligned to the right on LTR languages and to the left on RTL languages</td> </tr> <tr> <td>%ax</td> <td>The next tag should follow the language direction (what that means is deifned by the individual tag). Currently %Cl and %V support this</td> </tr> </tbody> </table> ---++++++ Scrolling<a name="Scrolling"></a> | Tag | Action | | %s | Scrolls the line | 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. ---++++++ Alternating Sublines<a name="AlternatingSublines"></a> Items on a line can be grouped into "sublines". Each subline will be displayed in sucession for a certain amount of time, with the player continuously alternating between them. The itmes in a line are divided with a semi-colon, ";". Each subline is dispalyed for 2 seconds unless the line is modified using the "%t#" tag. | Tag | Action | | %t# | Sets display time for a subline | In the tag above, "#" represent a whole number. This number equals the number of seconds the line is displayed. For example, "%t4" will cause a subline to be displayed for 4 seconds. You can also specify tenths of a second like this, "%t4.6" or "%t0.1". Here's an example of an alternating subline:<br /><br />%t4%ia;%t0.5%id;%it<br /><br />In the example above, the current tracks artist ("%ia") is displayed for 4 seconds, then the current album ("%id") is displayed for 1/2 a second, following that, the current track title ("%it") is displayed for the default 2 seconds.<br /><br />Sublines can also be scrolled (using "%s"), and can be in the same line as non-scrolled sublines, as long as they are divided (with the ";"). The example below makes the artist ("%ia") subline and track ("%it") subline scroll, while the album ("%id") subline does not scroll.<br /><br />%s%t4%ia;%t0.5%id;%s%it<br /><br />Futhermore, sublines can be used with conditionals (conditionals explained below). Here is an example (this will make more sense if you understand conditionals first):<br /><br />%?ia<%t4%s%ia|%t0>;%?it<%t4.5%s%it|%t%s%fn><br /><br />The first thing the player comes to is a [current artist conditional ("%?ia")]. If the artist is known, it [displays it for 4 seconds ("%t4")], allowing it to [scroll ("%s")]. If the artist is not known, then a subline is [displayed for 0 seconds ("%t0")], which means that the entire conditional is no longer used. After one or the other is displayed for its alotted time, the player moves onto a [current track title conditional ("%?it")]. If the title is known, then it is [displayed for 4.5 seconds (%t4.5")], and is allowed to [scroll ("%s")] (its displayed indefinetly if the artist is not known). If the title is not known, then the [filename of the playing track ("%fn")] [is displayed for 2 seconds ("%t")] (but if the artist is not known, it is displayed indefinetly). ---+++++ Conditional Tag<a name="ConditionalTag"></a> This is definetly not the simplest of all tags, but since the word "conditionally" will pop up through out the guide, you should go ahead and look at how this tag works. The conditional tag basically says "if 'yes' then 'a'; if 'no' then 'b'". Below is a simple form, and two actual conditionals:<br /><br />%?--<a|b> ~ %?ia<%ia|Artist Unknown> ~ %?in<%in|%pp><br /><br />The first example shows the form of a conditional, the "%?" means that it is in fact condtional. The "--" is replaced with some form of tag. The "<a|b>" section offers two options to the conditional (explained using other examples).<br /><br />In the second example, the conditional deals with the current track's artist (ia). Applying the previous statement, "if 'yes' then 'a'; if 'no' then 'b'", to the condtional gives you this: "If 'yes there is artist information", then 'display it (%ia tag)', if 'no there is not artist information' then 'display text (Artist Unknown)'".<br /><br />The third example is taken from the "UniCatcher" wps. It relates to current track number (in) and playlist position (pp). Applying the same statement gives you this: "If 'yes the year is known' then 'display it (%in tag)', if 'no the year is not known' then 'display playlist position (%pp tag)'".<br /><br />Some forms of conditional tags have more than two values (a,b), for example, the repeat status conditional has 5, and each represents a different repeat mode. Here is the tag:<br /><br />%?mm<Off|All|One|Shuffle|A-B><br /><br />This basically works the same way, except there are more possible answers to the conditional's questions. Most of this kind of tag have set sections for the different values. In the shuffle conditional above, the first section will be displayed when shuffle is "Off", the second when suffle is in "All" mode, etc. You'll see more of these tags throughout the guide and each one is explained.<br /><br />Hopefully that helped you. ---+++++ Viewports<a name="Viewports"></a> 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. Lines after a viewport declaration are drawn within that viewport. In Base Skins, you can only load images in that default viewport, you cannot draw tags into it or display text in it.<br /><br />The code for viewport declarations is as follows: | LCD Type | Viewport Declaration | | Mono | %V|x|y|width|height|font| | | Greyscale | %V|x|y|width|height|font|fgshade|bgshade| | | Color | %V|x|y|width|height|font|fgcolor|bgcolor| | The |x| field determines the starting point for the vieport along the horizontal axis. The |y| field does the same, but for the vertical axis. The |width| and |height| fields set dimensions for the viewport. In the |font| field, you can put a "0" or a "1"; the 0 will load the deault system font for that viewport, and the 1 will load the user font defined in the .cfg file. For greyscale LCD's, fgshade and bgshade are defined by numbers 0-3;0=black, 3=white. For Color LCD's, fgcolor and bgcolor are defined by hexcode colors; e.g. EEC40B.<br /><br />Notes:<br /> If any viewports are defined, text can no longer be loaded into the default viewport (use it for images).<br /> Viewports should not overlap. If part or all of them should, however, the latest viewport covers the previous one.<br /> Only the |x| and |y| positions need to be defined. The other fields can default by inserting a "-" into that field, but do not delete any fields.<br /> i.e. ( %V|0|0|-|-|-|-|-| )<br /> The |x| and |y| vaules can be negative, negative values are measured from the right side (x axis) or bottom (y axis)<br /> The |width| and |height| vaules can also be negative. These are also measured from the far sides.<br /> The default width/height is the remaining part of the screen <br /> The default font is the user font (from .cfg)<br /> The default shade (greyscale LCD) is black fg, white bg<br /> The default colors (color LCD) are the theme colors (from .cfg) ---++++++ Conditional Viewports<a name="ConditionalViewports"></a> Viewports can also be conditionally displayed. For exmaple, if album art is loaded, one set of viewports can appear, if, however, album art is not found, another set of viewports could appear. Tags are below: | Tag | Action | | %Vl|'identifier'|x|y|width|height|font|... | Preloads a viewport for display. | | %Vd'indentifier' | Displays the conditional viewport | In the first tag line, "..." should be deleted, replaced with "fgshade|bgshade|", or replaced with "fgcolor|bgcolor|" depending on LCD type.<br /><br />The 'identifier' is a single, lowercase letter (a-z). Viewports can share identifiers, allowing them all to be loaded with one display tag. Keep in mind that the display tag [%Vd(a-z)] must come before the preload tag [%Vl|(a-z)|x|y|...]. ---++++++ Info Viewport<a name="InfoViewport"></a> !!Base Skin (.sbs) only!!<br /><br />A custom UI viewport (viewport for the menus and file browser) can be set using a special viewport tag. It's strongly recommended to use this in your .sbs as it allows it to be used with other themes.<br /><br />^ Tag ^ Description ^<br />^%Vi|x|y|width|height|font|...^for "..." see note below conditional viewport table^ ---+++++ Base Skin on/off<a name="BasseSkinOnOff"></a> !!WPS (.wps) only!!<br /><br />These tags either enable or disable the Base Skin on the WPS. These tags override player settings, so if your WPS relies on the Base Skin either being on or off, use them. | Tag | Action | | %we | Base Skin enabled | | %wd | Base Skin disabled | ---+++++ Id3 Tags<a name="Id3Tags"></a> <br />These tags all rely on Id3 information pulled from the audio track. They are also able to be used as conditionals, and its suggested that you use them as such so missing information doesnt leave blank spots. ---++++++ Current Id3 Tags<a name="CurrentId3Tags"></a> | Tag | Action | | %ia | Id3 Artist* | | %ic | Id3 Composer* | | %iA | Id3 Album Artist* | | %id | Id3 Album Name* | | %iG | Id3 Grouping | | %ig | Id3 Genre | | %in | Id3 Track Number* | | %it | Id3 Track Title | | %iC | Id3 Comment | | %iv | Id3 Verison** | | %iy | Id3 Year | | %ik | Id3 Disc Number | *If a cuesheet is associated with the current track, and cuesheet support is enabled, "*"ed information will come form cuesheet instead of track.<br />**Version 1.0, 1.1, 2.2, 2.3, 2.4 or empty if no ID3 tag present ---++++++ Upcoming Id3 Tags<a name="UpcomingId3Tags"></a> To draw information from the upcoming track, simply replace the lowercase "i" in the current Id3 tags with an uppercase "I". For example, "%Ia" displays the upcoming artist, "%It" displays the upcoming track title, etc. ---+++++ File Tags<a name="FileTags"></a> File tags are relative to the file itself, rather than the audio you hear. ---++++++ Current File Tags<a name="CurrentFileTags"></a> | Tag | Action | | %fb | File Bitrate (in kbps) | | %fc | File Codec (e.g MP3 or FLAC)* | | %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)" or ""<--blank** | | %d1 | 1st directory from end of path*** | | %d2 | 2nd directory from end of path*** | | %d3 | 3rd directory from end of path*** | *Codec tag can also be used as a conditional, %?fc<mp1|mp2|mp3|AIFF|wav|vorbis|flac|mpc|a52|wavpack|alac|aac|shorten|SID|ADX|NSF|speex|SPC|APE|WMA|unknown>. The codec order is as follows: MP1, MP2, MP3, AIFF, WAV, Ogg Vorbis (OGG), FLAC, MPC, AC3, WavPack (WV), ALAC, AAC, Shorten (SHN), SID, ADX, NSF, Speex, SPC, APE, WMA, ???.<br />**If bitrate is variable, then tag displays "(avg)", if it is constant, nothing is displayed.<br />***Example for the the %d# tags: If the path is "/Rock/Kent/Isola/file.mp3", %d1 is "Isola", %d2 is "Kent"... You get the picture. ---++++++ Upcoming File Tags<a name="UpcomingFileTags"></a> Same as with upcoming Id3 tag, simply replace the first letter of the tag with it's capital version. For example, "%Fb" displays upcoming birate, and %D1 displays the upcoming track's directory. ---+++++ Playlist Tags<a name="PlaylistTags"></a> | Tag | Action | | %pc | Track time elapsed | | %pr | Track time remaining | | %pt | Track time total | | %px | Elapsed time in %* | | %pe | Total # of playlist entries | | %pn | Playlist name (without ext. or path) | | %pp | Playlist position | | %pm | Entire line used as volume peak meter | | %Sp | Current playback pitch | | %pf | Full-line progress bar + time display** | | %ps | Shuffle, shows s if shuffle in on* | | %pv | Displays volume in dB* | | %mv | Indicates volume increasing/decreasing* | <br />*The "%px" can be used as a conditional to create custom progress indicators. Both the "%ps" and "%pv" can be used as conditionals. The "%ps" is used in this way, "%?ps<on|off>" (off is not needed, "%?ps<on>" is fine), and "%pv" is used in this way, "%?pv<Mute|...|0 dB|Above 0 dB> ("|...|" can be filled with as many sections as you like, the number of dB between "mute" and "0" will then be divided by the number of sections put in. For example, say "mute" is at -100dB, and i made 10 sections in the "|...|" area. At -90dB, -80dB, -70dB, etc., the next conditional would be used because 100/10 is 10.)<br />**Archos Play/Studio only ---++++++ Progress Bar<a name="ProgressBar"></a> The progress bar is a image that loads relative to the time elapsed. For example, half-way through your song, 50% of the image would be visible. Progress bars load horizontally, and you can use up to three, with a maximum of one per viewport.The progress bar tag will replace an entire line with a 6 pixel 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 "-". | Tag | Action | | %pb|filename.bmp|x|y|width|height| | Loads and positions progress bar | For the Archos Player/Studio, this will display a one character "cup" that empties as the time progresses (only %pb). ---++++++ Playlist Viewer<a name="PlaylistViewer"></a> <br />The Playlist Viewer allows you to display information for the upcoming tracks in the playlist. The Viewer takes up the entire viewport it is placed in. The tag is below: | Tag | Action | | %Vp|start|show if id3|show otherwise| | Displays the "playlist viewer" | <br />Inside "start" section is placed a digit, and that digit tells the playlist viewer where to begin in the playlist. A "0" makes the current track the beginning of the viewer's list, a "1" makes the next track top on the list, etc.<br /><br />The "show if id3" section is used for tracks which have been buffered. You can insert any of the following tags into that field.<br /><br /> playlist position "%pp", any tag beginning with "%i", most tags beginning with "%f", track length "%pt", and "%s" (scrolls ENTIRE viewer)<br /><br />The "show otherwise" section is displayed for tracks which have not been buffered, at this point really only the filename and playlist position is known.<br /><br />For example, "%Vp|1|%pp - %it|%pp - %fn|", will start the list with the upcoming track, for buffered tracks it will display the track's playlist position a "-" then the track title, and for unbuffered tracks the track's playlist position a "-" and then the filename.<br /><br /> Note: The "|show if id3|" and "|show otherwise|" sections can each have up to 16 tags, and a maximum of 8 free text strings(each up to a max. of 8 characters). ---++++++ Playback Mode Tag<a name="PlaybackModeTag"></a> <br />The playback mode tag has a total of nine modes, but not all are used on every player. The tag present the modes as the digits "1-9", and the order is Stop, Play, Pause, Fast Forward, Rewind, Recording, Recording Paused, FM Radio Playing, FM Radio Muted. The tag is as follows: | Tag | Action | | %mp | Playback Mode | The tag can also be used as a conditional, which is used in this way:<br /> "%?mp<Stop|Play|Pause|Ffwd|Rew|Rec|Rec pause|FM|FM pause>"<br /><br />You don't have to include all modes if the player doesn't have certain capabilities, however, all players should be able to use the first five modes.<br /><br />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. ---+++++ Repeat Mode Tag<a name="RepeatModeTag"></a> The repeat mode tag displays the five different repeat modes in the digits "0-4". The order is, 0 = Off, 1 = All, 2 = One, 3 = Shuffle, 4 = A-B. The tag is as follows: | Tag | Action | | %mm | Repeat mode | The tag can also be used as a conditional, which is used in this way:<br /> "%?mm<Off|All|One|Shuffle|A-B>" ---+++++ Hold Switch Tags<a name="HoldSwitchTags"></a> | Tag | Action | | %mh | Shows "h" if hold is on | | %mr | Shows "r" if remote hold is on | <br />These tags can be used as conditionals, for example, "%?mh<Locked|Unlocked>". ---+++++ Crossfade Tag<a name="CrossfadeTag"></a> <br />There are six modes of crossfading, the crossfade tag displays them in the digits 0-5. The order is as follows, Off, Automatic Track Skip Only, Manual Track Skip Only, Shuffle, Shuffle or Manual Track Skip, Always. | Tag | Action | | %xf | Displays crossfade mode | <br />The "%xf" tag can also be used as a conditional, in this way:<br /> %?xf<Off|Automatic Track Skip|Manual Track Skip|Shuffle|Shuffle or Manual Track Skip|Always> ---+++++ Power Related Information<a name="PowerRelatedInformation"></a> <br />These tags are related namely to the battery and charging. | Tag | Action | | %bl | Shows battery level in number %* | | %bv | Shows battery level in volts | | %bt | Shows estimated battery time left | | %bp | Shows a "p" if charger is connected* | | %bc | Shows a "c" if currently charging* ** | | %bs | Shows time left on sleep timer | *Can be used as a conditional. For "%bl", "%?bl<-1|0|1|2|...|N>" where "-1" is when battery level is unknown (it usually is known), and "|...|" filled with as many sections as desired. For "%bp" use "%?bp<-|->; for "%bc" use "%?bc<-|->".<br />**only on targets that have software charge control or monitoring<br /><br />An example (using simple text) for a battery meter:<br />"%?bp<%?bc<Charging|Connected>|%?bl<|10|20|30|40|50|60|70|80|90|100>>"<br /> In the above example, if the charger is plugged in, then it asks the question, "is the battery charging" if yes, then it displays "Charging", if it is not charging, but is plugged in, then "Connected is displayed. If the charger is not connected, then a battery level meter appears which displays power level in 10's. ---+++++ Drive Actvity Tag<a name="DriveActivityTag"></a> | Tag | Action | | %lh | Shows a "h" when drive is active | <br />The "%lh" tag can also be used as a conditonal, in this way:<br /> %?lh<active|idle> ---+++++ Runtime Database and Replay Gain<a name="RuntimeDatabaseAndReplayGain"></a> | Tag | Action | | %rp | Shows number of times song has been played | | %rr | Shows song rating using "0-10"* | | %ra | Shows database autoscore for the song | | %rg | Shows Replay Gain value in use (x.ydB)* | *Can be used as a conditional. For "%rr", "%?rr<0|1|2|3|4|5|6|7|8|9|10>" is used; for "%rg", "%?rg<Off|Track|Album|TrackShuffle|AlbumShuffle|No tag>" is used. ---+++++ Real Time Clock<a name="RealTimeClock"></a> | Tag | Action | | %cc | Is there an RTC? | | %cd | Day of month (01-31) | | %ce | Day of month, blank padded (1-31) | | %cm | Month (01-12)* | | %cb | Abbreviated month name (Jan-Dec) | | %ca | Abbreviated weekday name (Sun-Sat) | | %cu | Day of week (1-7), 1 is Monday* | | %cw | Day of week (0-6), 0 is Sunday* | | %cf | Conditional for 12/24 hour format* | | %cH | Hour (00-23) | | %ck | Hour (0-23) | | %cI | Hour (01-12) | | %cl | Hour (1-12) | | %cM | Minute (00-59) | | %cS | Second (00-59) | | %cy | Last digits of year (00-99) | | %cP | Upper-case AM or PM indicator | | %cp | Lower-case am or pm indicator | *Can be used as a conditional. "%cm" is used as "%?cm<January|February|March|April|May|June|July|August|September|October|November|December>"; "%cu" is used as" %?cu<Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday>"; "%cw" is used as "%?cw<Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday>"; "%cf" is used as %?cf<24 hour stuff|12 hour stuff>. ---++++ Images<a name="Images"></a> <br />Before we dive into images, take a look at these notes:<br /><br /> -Images must be in a Rockbox compatible format (see table below for model specific BMP compatibility).<br /> -The x and y coordinates for image location must repect the player's LCD screen limits. (see table below)<br /> -An image tag must be on its own line.<br /> -There is a buffer limit on how many bitmap pixels can be loaded in to memory which is calculated as such: ((LCD_HEIGHT*LCD_WIDTH*LCD_DEPTH/8) + (2*LCD_HEIGHT*LCD_WIDTH/8)). This means that the total visual size of all of the bitmaps used cannot exceed the total of this calculation. For 16-bit targets, this comes to 2.25 times the size of the screen.<br /> -The coordinates define the position relative to the viewport the corresponding display bitmap tag (%xd) is in.<br /> -Some image loading tags contain an indicator (a-z or A-Z), this indicator is used by display tags to load the image. ---+++++ LCD Screen Sizes and BMP Compatibility<a name="LcdScreenSizesAndBMPCompatibility"></a> | 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 | 128x64 | 1-bit | | iriver H10 (5/6Go) | 128x128 | 1-bit, 24-bit | no remote | n/a | | iriver H10 (20Go) | 160x128 | 1-bit, 24-bit | no remote | n/a | | Archos Recorders | 112x64 | 1-bit | no remote | n/a | | Archos Ondio | 112x64 | 1-bit | no remote | n/a | | iPod Nano | 176x132 | 1-bit, 24-bit | no remote | n/a | | iPod 4G Grey | 160x128 | 1-bit | no remote | n/a | | iPod 4G Color | 220x176 | 1-bit, 24-bit | no remote | n/a | | iPod 5G Video | 320x240 | 1-bit, 24-bit | no remote | n/a | | iPod Mini/Mini2G | 138x110 | 1-bit | no remote | n/a | | iAudio X5 | 160x128 | 1-bit, 24-bit | 128x96 | 2-bit (4 gray levels) | | Toshiba Gigabeat Fxx | 240x320 | 1-bit?, 24-bit | ? | ? | | Toshiba Gigabeat Xxx | 240x320 | 1-bit?, 24-bit | ? | ? | | SanDisk Sansa e200 | 176x220 | 1-bit?, 24-bit | no remote | n/a | | SanDisk Sansa c200 | 132x80 | 1-bit?, 24-bit | ? | ? | ---+++++ Basic Image Tags<a name="BasicImageTags"></a> <br />In the tags below, "-" represents the images filename (see File Location above for correct placement), "~" represent an image's indicator (a-z or A-Z) | Tag | Action | | %X|filename.bmp| | Loads a backdrop image for the WPS. This image must be exactly the same size as your LCD. | | %Xd | Disables the backdrop | | %x|~|-.bmp|x|y| | Loads and always shows the image | | %xl|~|-.bmp|x|y|#oftiles| | Preloads an image for display (useful when images are displayed conditionally) | | %xd~* | Displays a preloaded image | *For bitmap strips (see below) the tag becomes "%xd+indicator+subindicator". Example, %xdGb or %xdce<br /><br />The following examples implements some of the common image tags:<br /><br /> %X|background.bmp|<br /> %x|a|static_icon.bmp|50|50|<br /> %xl|b|rep_off.bmp|16|64|<br /> %xl|c|rep_all.bmp|16|64|<br /> %xl|d|rep_one.bmp|16|64|<br /> %xl|e|rep_shuffle.bmp|16|64|<br /> %?mm<%xdb|%xdc|%xdd|%xde><br /><br />In the example, the first line loads "background.bmp" and sets it as the backdrop; the second line loads "static_icon.bmp", displays it at 50,50 and shows it constantly; the third, fourth, fifth and sith line load images at the same position and give them indicators b,c,d and e; in the seventh line, images b,c,d and e are loaded in a shuffle mode conditional, each shuffle mode will now load a different image. (See next section for this example redone using bitmap strips)<br /><br /> %xl|a|volume.bmp|0|0|<br /> %V|78|25|10|10|-|-|-|<br /> %xda<br /><br />In this example, an image is loaded as defined as image "a", and is positioned at 0,0. In the the second line, a viewport is created at 78,25. In the third line, image "a" is displayed, but!!! since the image display tag is under a viewport declaration, the image's coordinates are now relative to the viewport's coordinates (so the image will appear at 78,25 on the screen). ---+++++ Bitmap Strips<a name="BitmapStrips"></a> <br />A Bitmap strip is an extremely convenient way to store multiple images in one .bmp file. The individual iamges (equally sized) are tiled veritcally then saved a a single .bmp file. The individual images are then loaded as subimages using subindicators. <br /> For exmaple, "%xl|R|repeat.bmp|16|64|4|" - "%?mm<%xdRa|%xdRb|%xdRc|%xdRd>", the first code splits image "R" into 4 images (...|4|) along the y axis (assuming the image were 25px wide, 100px tall, it would split it into four 25px*25px sections). The second code loads the image's four parts using subindicators, so "%xdRa" loads the first part, "%xdRb" loads the second, etc.<br />Since this method cuts down on the number of images used in a WPS or SBS, it's advisable to use them wherever possible (espcially for images that load in the same spot, like a repeat mode icon).<br /><br />This is the first example in the Basic Image Tags section, redone using a bitmap strip and subindicators.<br /><br /> %X|background.bmp|<br /> %x|a|static_icon.bmp|50|50|<br /> %xl|R|repeat.bmp|16|64|4|<br /> %?mm<%xdRa|%xdRb|%xdRc|%xdRd><br /><br />The first two lines are the same as the previous verison of the example, but now "repeat.bmp" is a bitmap strip with four sections (the "|4|" at the end). The last line displays the the four sections of the image using subindicators. "%xdRa" loads the top 1/4 of image "R", "%xdRb" loads the second 1/4 (just below the first 1/4), and so on. ---+++++ Album Art<a name="AlbumArt"></a> <br />You can display Album Art using the following tags. Album Art will be cropped to the "|maxwidth|maxheight|" dimensions if they are larger than those dimensions (more information about AA here, AlbumArt ). | Tag | Action | | %Cl|xpos|ypos|maxwidth|maxheight| | Loads Album Art *More Details* | | %C | Displays Ablbum Art *More Details* | <br />There are two conditional tags for album-art, "%?C" and "%?Cn". They indicate whether bitmap files have been found for the current (%?C) and next tracks (%?Cn). They work exactly like usual conditional tags, "%?C<a|b>" ---++++ Other<a name="Other"></a> ---+++++ Recording Screen Tokens<a name="RecordingScreenTokens"></a> !!Base Skin Only!! | Tag | Action | | %Rp | Does target have recording? (If not, the "true" of this conditional is ignored so don't worry about recording tags on non recording targets | | %Rm | Currently recording in mono | | %Rf | Recording Frequency/Samplerate* | | %Re | Encoder being used (in the order WAV, AIFF, WV, MP3. SWCODEC only!) | | %Rb | Bitrate; SWCODEC and MP3: %?Rb<8|16|24|32|40|48|56|64|80|96|112|128|144|160|192> HWCODEC: Quality setting.. 0-7 inclusive | *Conditional always uses the values; HWCODEC: %?Rf|44|48|32|22|24|16> ; SWCODEC: %Rf<96|88|64|48|44|32|24|22|16|12|11|8> (remember, your target may not support all of these). ---+++++ Current Screen<a name="CurrentScreen"></a> | Tag | Action | | %cs | Screens from 1-4, in the order: Menus, WPS, Recording screen, FM Radio screen | <br />Example use:<br /><br />You are in the %cs<Main menu|WPS|Recording screen|FM Radio screen> ---+++++ Touchscreen<a name="Touchscreen"></a> !!WPS Only!!<br /><br />These tags are only applicable to touch screen targets. | Tag | Action | | %T|x|y|width|height|action| | Invoke the action when the user presses in the touchscreen area | <br />If action starts with "&", the area must be held to invoke the action.<br /><br />In the "%T" tag, action can be:<br /><br /> play - play/pause playback<br /> stop - stop playback, exit the wps<br /> prev - prev track<br /> next - next track<br /> ffwd - seek forward<br /> rwd - seek backwards<br /> menu - go back to the main menu<br /> browse - go back to the file/db browser<br /> shuffle - toggle shuffle mode<br /> repmode - cycle the repeat mode<br /> quickscreen - go into the quickscreen<br /> contextmenu - open the context menu<br /> playlist - go to the playlist viewer<br /> progressbar - seeks to the appropriate position based on the touch<br /> volume - sets the appropriate volume based on the touch<br /> pitch - go into the pitchscreen<br /> voldown - decrease volume by one step<br /> volup - increase volume by one step | Tag | Action | | %Tl | Indicates that the touchscreen is pressed | Can also be used as a conditional or with conditional viewports. <br /><br />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 (%Tl2.5 will give a 2.5 second timeout) between the touchscreen press being released and the tag going false. If no number is specified it will use a 1 second timeout. ---+++++ Other Settings<a name="OtherSettings"></a> | Tag | Action | | %St|setting name| | Indicates value of the specified setting | <br />Can be used as a simple tag %St|skip length| or with conditionals %?St|eq enabled|<Equalizer is enabled|Equalizer is disabled><br /><br />!!!!!!Needs usable settings list!!!!!! ---+++++ Other Tags<a name="OtherTags"></a> | Tag | Action | | %% | Displays a "%" | | %< | Displays a "<" | | %| | Displays a "|" | | %> | Displays a ">" | | %; | Displays a ";" | | %# | Displays a "#" | ---+++++ Tools<a name="Tools"></a> <br /><strong>EZWPS</strong><br /><br />The EZWPS Visual Basic application can help beginners on Windows to create a WPS file.<br /><br /><strong>The UISimulator</strong><br /><br />You can use a 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.<br /><strong><br />The checkwps tool</strong><br /><br />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.<br /><br />Usage: checkwps [OPTIONS] filename.wps<br /><br />OPTIONS:<br /> -v verbose<br /> -vv more verbose<br /> -vvv very verbose<br /><br />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.<br /><br /><strong>Vim</strong><br /><br />In the Vim text editor, a script here provides syntax highlighting for WPS files.
E
dit
|
A
ttach
|
P
rint version
|
H
istory
: r1
|
B
acklinks
|
V
iew topic
|
M
ore topic actions
r1 - 17 Feb 2010 - 01:11:15 -
ThomasKirkpatrick
Copyright © by the contributing authors.
