|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Comprehensive Yet Comprehendible Customized Display GuideDescription / General Info File Creation File Location Themes WPS and SBS Tags Positioning Alignment Scrolling Alternating Sublines Conditional Tag Viewports Conditional Viewports Info Viewport Base Skin on/off Id3 Tags Current Id3 Tags Upcoming Id3 Tags File Tags Current File Tags Upcoming File Tags Playlist Tags Progress Bar Playlist Viewer Playback Mode Tag Repeat Mode Tag Hold Switch Tags Crossfade Tag Power Related Information Drive Actvity Tag Runtime Database and Replay Gain Real Time Clock Images LCD Screen Sizes and BMP Compatibility Basic Image Tags Bitmap Strips Album Art Other Recording Screen Tokens Current Screen Touchscreen Other Settings Other Tags Tools Description / General InfoThe 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. This guide is based on the "CustomWPS" guide. Another, less-featured but much simpler guide is found here, "SimpleGuideToWPSMaking". File CreationThe .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 LocationWhile 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. 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. 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. ThemesTheme 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. wps: /.rockbox/wps/example.wps sbs: /.rockbox/wps/example.sbs font: /.rockbox/fonts/example.fnt foreground color: FFFFFF background color: 000000 statusbar: custom backdrop: /.rockbox/backdrops/example.bmp line selector start color: FFFFFF line selector end color: FFFFFF selector type: bar (gradient) iconset: /.rockbox/icons/example_small.bmp viewers iconset: /.rockbox/icons/example_small_viewers.bmp line selector text color: 000000 filetype colours: /.rockbox/themes/filename.colours ui viewport: ???????????????????????? 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 SBSAll 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.TagsPositioningThe following codes are applicable to text and in some cases images.Alignment
Scrolling
Alternating SublinesItems 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.
%t4%ia;%t0.5%id;%it 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. 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. %s%t4%ia;%t0.5%id;%s%it Futhermore, sublines can be used with conditionals (conditionals explained below). Here is an example (this will make more sense if you understand conditionals first): %?ia<%t4%s%ia|%t0>;%?it<%t4.5%s%it|%t%s%fn> 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 TagThis 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:%?--<a|b> ~ %?ia<%ia|Artist Unknown> ~ %?in<%in|%pp> 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). 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)'". 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)'". 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: %?mm<Off|All|One|Shuffle|A-B> 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. Hopefully that helped you. ViewportsBy 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.The code for viewport declarations is as follows:
Notes: If any viewports are defined, text can no longer be loaded into the default viewport (use it for images). Viewports should not overlap. If part or all of them should, however, the latest viewport covers the previous one. 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. i.e. ( %V|0|0|-|-|-|-|-| ) The |x| and |y| vaules can be negative, negative values are measured from the right side (x axis) or bottom (y axis) The |width| and |height| vaules can also be negative. These are also measured from the far sides. The default width/height is the remaining part of the screen The default font is the user font (from .cfg) The default shade (greyscale LCD) is black fg, white bg The default colors (color LCD) are the theme colors (from .cfg) Conditional ViewportsViewports 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:
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!!Base Skin (.sbs) only!!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. ^ Tag ^ Description ^ ^%Vi|x|y|width|height|font|...^for "..." see note below conditional viewport table^ Base Skin on/off!!WPS (.wps) only!!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.
Id3 TagsThese 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
**Version 1.0, 1.1, 2.2, 2.3, 2.4 or empty if no ID3 tag present Upcoming Id3 TagsTo 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 TagsFile tags are relative to the file itself, rather than the audio you hear.Current File Tags
**If bitrate is variable, then tag displays "(avg)", if it is constant, nothing is displayed. ***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 TagsSame 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
*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.) **Archos Play/Studio only Progress BarThe 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 "-".
Playlist ViewerThe 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:
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. The "show if id3" section is used for tracks which have been buffered. You can insert any of the following tags into that field. playlist position "%pp", any tag beginning with "%i", most tags beginning with "%f", track length "%pt", and "%s" (scrolls ENTIRE viewer) 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. 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. 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 TagThe 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:
"%?mp<Stop|Play|Pause|Ffwd|Rew|Rec|Rec pause|FM|FM pause>" 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. 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 TagThe 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:
"%?mm<Off|All|One|Shuffle|A-B>" Hold Switch Tags
These tags can be used as conditionals, for example, "%?mh<Locked|Unlocked>". Crossfade TagThere 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.
The "%xf" tag can also be used as a conditional, in this way: %?xf<Off|Automatic Track Skip|Manual Track Skip|Shuffle|Shuffle or Manual Track Skip|Always> Power Related InformationThese tags are related namely to the battery and charging.
**only on targets that have software charge control or monitoring An example (using simple text) for a battery meter: "%?bp<%?bc<Charging|Connected>|%?bl<|10|20|30|40|50|60|70|80|90|100>>" 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
The "%lh" tag can also be used as a conditonal, in this way: %?lh<active|idle> Runtime Database and Replay Gain
Real Time Clock
ImagesBefore we dive into images, take a look at these notes: -Images must be in a Rockbox compatible format (see table below for model specific BMP compatibility). -The x and y coordinates for image location must repect the player's LCD screen limits. (see table below) -An image tag must be on its own line. -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. -The coordinates define the position relative to the viewport the corresponding display bitmap tag (%xd) is in. -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
Basic Image TagsIn the tags below, "-" represents the images filename (see File Location above for correct placement), "~" represent an image's indicator (a-z or A-Z)
The following examples implements some of the common image tags: %X|background.bmp| %x|a|static_icon.bmp|50|50| %xl|b|rep_off.bmp|16|64| %xl|c|rep_all.bmp|16|64| %xl|d|rep_one.bmp|16|64| %xl|e|rep_shuffle.bmp|16|64| %?mm<%xdb|%xdc|%xdd|%xde> 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) %xl|a|volume.bmp|0|0| %V|78|25|10|10|-|-|-| %xda 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 StripsA 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. 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. 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). This is the first example in the Basic Image Tags section, redone using a bitmap strip and subindicators. %X|background.bmp| %x|a|static_icon.bmp|50|50| %xl|R|repeat.bmp|16|64|4| %?mm<%xdRa|%xdRb|%xdRc|%xdRd> 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 ArtYou 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 ).
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>" OtherRecording Screen Tokens!!Base Skin Only!!
Current Screen
Example use: You are in the %cs<Main menu|WPS|Recording screen|FM Radio screen> Touchscreen!!WPS Only!!These tags are only applicable to touch screen targets.
If action starts with "&", the area must be held to invoke the action. In the "%T" tag, action can be: play - play/pause playback stop - stop playback, exit the wps prev - prev track next - next track ffwd - seek forward rwd - seek backwards menu - go back to the main menu browse - go back to the file/db browser shuffle - toggle shuffle mode repmode - cycle the repeat mode quickscreen - go into the quickscreen contextmenu - open the context menu playlist - go to the playlist viewer progressbar - seeks to the appropriate position based on the touch volume - sets the appropriate volume based on the touch pitch - go into the pitchscreen voldown - decrease volume by one step volup - increase volume by one step
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
Can be used as a simple tag %St|skip length| or with conditionals %?St|eq enabled|<Equalizer is enabled|Equalizer is disabled> !!!!!!Needs usable settings list!!!!!! Other Tags
ToolsEZWPS The EZWPS Visual Basic application can help beginners on Windows to create a WPS file. The UISimulator 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. 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. Usage: checkwps [OPTIONS] filename.wps OPTIONS: -v verbose -vv more verbose -vvv very verbose 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 here provides syntax highlighting for WPS files. r2 - 02 Apr 2021 - 20:46:06 - UnknownUser
Copyright © by the contributing authors.
|
