The Simple Guide To WPS Making

Let’s start with something simple. Let’s say you want to display the artist, album, and track on separate lines. The code that is used is a system of two letter “tags” preceded by a percentage symbol. So you would use %ia, %id and %it for this WPS. These are among the most basic tags.

Your code should look like this:

%ia
%id
%it

Adding Scrolling

Now, say you want the lines to scroll (they will scroll only if there is too much text to fit on screen, and this will obviously vary based on which font you select for your WPS). The scrolling tag is %s. We place this immediately in front of the other tags on the line, with no space in between them.

Your code should now be:

%s%ia
%s%id
%s%it

Alignment Tags

Next we’ll review the alignment tags. By default the text is aligned to the left. But this can be changed by using the three alignment tags: %al (aligned left), %ac (centered) and (aligned right) %ar. These tags work very similarly to the scrolling tag. We’ll center our text. (Feel free to correct me if I’m wrong, but I don't think it matters which order the scrolling/alignment tags are placed. I always put the scrolling tags first, and this works well for me). Also, you can have multiple alignment tags on one line. so if you want the current time and remaining time to be displayed, you can use %ar%pc %al%pr This displays the current time aligned on the right, with the remaining time aligned on the left.

Code now looks like this:

%s%ac%ia
%s%ac%id
%s%ac%it

<--top two lines visibly centered, as is the bottom line (you can't see it because it's scrolling)

Next Song Info

Now we’re going to cover the next song tags. One of the fantastic things about Rockbox is that it allows you to display the next song information in the WPS. To do this, capitalize the first letter of the two-letter tag you are going to use. For example, the next artist tag would be %Ia, next album info would be %Id, etc.

We’ll leave a line blank and add artist, album and track information for the next song, also scrolling and centered.

Code:

%s%ac%ia
%s%ac%id
%s%ac%it

%s%ac%Ia
%s%ac%Id
%s%ac%It

Fairly simple so far, isn't it?

Up until now we've left the status bar alone (it is on by default). Now we're going to disable it, as you'll soon be learning techniques that will enable you to create your own custom status bar, should you choose to. There are two very simple tags, %we which enables the status bar, and %wd which disables it. This way, you can have the status bar enabled in the menus, and have in disabled in your WPS, or vice-versa.

Code:

%wd
%s%ac%ia
%s%ac%id
%s%ac%it

%s%ac%Ia
%s%ac%Id
%s%ac%It

Conditionals

Here things get a bit tricky. Conditionals are commonly used for alternatives. It works for current song info as well as next song info. Let's say your collection of songs isn't tagged well. Some songs have information, some don't. Normally, if the artist/album/track/whatever field is blank, nothing will be displayed. This leaves a blank screen...rather unattractive. So to prevent this from happening, we can use a conditional tag. The conditional syntax: %?xx<true|false>. We're going to add a conditional value for each field.

%wd
%s%ac%?ia<%ia|Artist Unknown>
%s%ac%?id<%id|Album Unknown>
%s%ac%?it<%it|Title Unknown>

%s%ac%?Ia<%Ia|Artist Unknown>
%s%ac%?Id<%Id|Album Unknown>
%s%ac%?It<%It|Title Unknown>

This can get confusing, especially with the other tags. So let's ignore them for a minute and focus on one part. %?ia<%ia|Artist Unknown> What makes it a conditional is the question mark (?). This says that a conditional follows and differentiates it from a normal artist tag. Next we use the <|> to include the true/false information. The first half (between the < and |) contains the %ia tag. This says "If the artist information is known, display it." The next half (between the | and >) is the "else" part of the tag. We're using "Artist Unknown" as our "else." This says "If the artist information is not known, display Artist Unknown. Overall we're left with "If the artist information is known, display it, and if it is not known, display Artist Unknown." This works the same way for other tags as well.

Additionally, if there is no else value, you can leave that field blank. For example, %?ia<%ia> will display the artist if the information is known, and will display nothing if the artist information isn't known.

Alternating Sublines

An alternating subline allows you to alternate what a line displays. It is particularly useful for players with limited screen space or for WPS's that use big fonts. So, if you want to display artist info and album info on one line, you can. The tag used is %t followed by the number of seconds you want the information to appear (it is 2 seconds by default, and the minimum is .01 second). To separate the items alternating, we use ; Here's a simple example: %t3%ia;%t4%id This displays the artist for 3 seconds, and then switches to the album, which is displayed for 4 seconds. then it repeats. You can also add multiple items. %t3%ia - %it;%t4%id displays Artist - Track Title for 3 seconds, then switches to Album for 4 seconds, then repeats, and so on. Scrolling and centering can be added, but keep in mind, if you want both sides to be centered/scroll then you must put those tags on each side of the ; Example: %s%ac%t3%ia - %it;%s%ac%t4%id For the WPS we've been working on, we'll add the genre and the year on the same line for the current song and do the same for the next song, using conditionals.

%wd
%s%ac%?ia<%ia|Artist Unknown>
%s%ac%?id<%id|Album Unknown>
%s%ac%?it<%it|Title Unknown>
%ac%t3%ig;%t%iy

%s%ac%?Ia<%Ia|Artist Unknown>
%s%ac%?Id<%Id|Album Unknown>
%s%ac%?It<%It|Title Unknown>
%ac%t3%?ig<%ig|Genre Unknown>;%t%?iy<%iy|Year Unknown>

This code may look intimidating, but if you go back through the previous steps, you can see the additions made, and how it is grown. when you break it down it really isn't as complicating (in fact, simply removing the scrolling/alignment tags would make things much cleaner/simpler).

Images

Images are a great way to freshen up a WPS, and make it more stylish.

How to start adding images

To add images to your WPS, the first step is to take a screendump. To do this, go to Menu-->Info-->Debug-->Screendump. This will enable you to take a screendump. Now go back to the while playing screen, and plug in the USB cable. The hard drive will spin up, and a file called dump_0001.bmp will appear in the root directory. Go back into the menu, doing the same as you did before to disable screendump mode, and connect your player to the computer like you normally would. You can now use this screendump to create images based on where the text is. Create your images (paint works well for grayscale targets) and make sure they are saved as grayscale .bmps (background images must be monochrome).

Image Tags

The syntax for images is %x|n|filename.bmp|x|y| There are four types of image tags: %x, %xl, %xdn and %X and they each have different uses. The 'n' part of the tags must contain a letter from a to z. This way, you can use up to 52 images (26 lower-case, 26 upper-case). Each image gets a different letter. The filename.bmp ie simply the name of the bitmap that you are using. The |x|y| values are the coordinates at which the image will be placed. The top left corner is 0,0. For our WPS, we'll add a simple background image, and a shuffle tag. First, a breakdown of the image tags by type.

Tag 1: Permanent display

%x will permanently load an image. This means that if you have a background image, that you want displayed all the time, you should use %x|a|background.bmp|0|0| This also works for other images as well, not just background images.

Tag 2: Loading an image

%xl will load an image. If want to use an image, but not display it permanently, use %xl. Example: %xl|b|shuffle.bmp|0|0| See Tag 3 to learn when this is useful

Tag 3: Displaying a loaded image

%xd is used to display images that have been loaded with %xl For example: if you have %ps<%xdb> it will display the 'b' image that has already been loaded (In this case, the appropriate shuffle image). This conditional says "If shuffle is on, display the pre-loaded shuffle image, and if it is not, display nothing." The %xl and %xd tags are always used together, and are particularly useful when using conditionals

Tag 4: Using a backdrop

%X loads a backdrop. At the moment, this is for color targets only, and it's likely it'll stay that way, as it's hard to see grayscale backdrops.

Image File Structuring

For a WPS to correctly display images, not only must they be in the correct image format, but they must also be located in a certain place. In .rockbox, there is a folder titled 'wps.' This is where WPS files are kept. If the WPS has images, a folder must be created with the same name as the WPS file. For example, if your WPS is titled RockboxWPS.wps, you need to create a folder titled RockboxWPS This is where WPS images are to be placed. If they are not placed here, they will not be displayed.

%wd
%x|a|background.bmp|0|0|
%xl|b|shuffle.bmp|75|1|
%?ps<%xdb>
%s%ac%?ia<%ia|Artist Unknown>
%s%ac%?id<%id|Album Unknown>
%s%ac%?it<%it|Title Unknown>
%ac%t3%ig;%t%iy

%s%ac%?Ia<%Ia|Artist Unknown>
%s%ac%?Id<%Id|Album Unknown>
%s%ac%?It<%It|Title Unknown>
%ac%t3%?ig<%ig|Genre Unknown>;%t%?iy<%iy|Year Unknown>

That's pretty much the extent of the current WPS tags. Not as difficult as you thought, ehh? To conclude our WPS-making, we'll break down our WPS line by line...

line 1: %wd - Disables the status bar

line 2: %x|a|background.bmp|0|0| - Displays the background image

line 3: %xl|b|shuffle.bmp|75|1| - Loads the shuffle image, at the X coordinate of 75, and the Y coordinate of 1. (Defined in the format |X|Y| at the end of the tag).

line 4: %?ps<%xdb> - A conditional which displays the shuffle image if shuffle is turned on, and displays nothing if it is not.

line 5: %s%ac%?ia<%ia|Artist Unknown> - Displays the artist, centered and scrolling. If the Artist is not known, Artist Unknown is displayed.

line 6: %s%ac%?id<%id|Album Unknown> - Displays the album, centered and scrolling. If the album is not known, Album Unknown is displayed.

line 7: %s%ac%?it<%it|Title Unknown> - Displays the track title, centered and scrolling. If the track title is not known, Title Unknown is displayed.

line 8: %ac%t3%ig;%t%iy - Displays the genre for 3 seconds (centered) and then displays the year for 2 seconds, then repeats, etc.

line 9: we left this line blank

line 10: %s%ac%?Ia<%Ia|Artist Unknown> - Displays the next artist, centered and scrolling. If the next artist is not known, Artist Unknown is displayed.

line 11: %s%ac%?Id<%Id|Album Unknown> - Displays the next album, centered and scrolling. If the next album is not known, Album Unknown is displayed.

line 12: %s%ac%?It<%It|Title Unknown> - Displays the next track title, centered and scrolling. If the next track title is not known, Title Unknown is displayed.

line 13: %ac%t3%?ig<%ig|Genre Unknown>;%t%?iy<%iy|Year Unknown> - Displays the next genre (centered) for 3 seconds (unless it is unknown, in which case Genre Unknown is displayed) then displays the next year for 2 seconds (unless it is unknown, in which case Year Unknown is displayed)