7.3.1 Here’s one I tried to make earlier

We are going to create this:

Foliage theme for panelsUI

It’s pretty simple, and mediumly (new word) attractive, but it will do.

7.3.2 New layout

Firstly, head to the preferences (Ctrl+P), and then to the Display section. Make sure PanelsUI is selected. If it doesn’t appear in the drop-down menu, you’ve been a muppet, and have started a PanelsUI tutorial without having PanelsUI. So download it. Head to the PanelsUI sub-menu, and create a new layout. Call it something. I called mine “foliage”, during a brief lapse of imagination. Now, download my little images pack:

download me please

This contains all the images you need for the layout. Unzip it somewhere convenient on your hard drive, such as “C:\foobar\”. Now go back to the PanelsUI preferences page, where you created the new layout, and click on the “User Globals” button. Then add the line

$puts(imgpath,C:\foobar\foliage\)

on a new line in the box. If you unzipped the images somewhere else, modify the line to show the path of the containing folder. If you can’t find the user globals page it should look something like this:

Panels global variables

This allows us to call on a variable each time we want to find our images folder, rather than writing out “C\foobar\…” each time. You can do this with anything, such as fonts or colours. Since this is a simple layout, we won’t do any more.

7.3.3 Writing the code

Now we’re going to edit the code for the first time. Click on “Edit Layout” on the PanelsUI preferences window, and select all the code from the new box that appears. Delete it. All of it. Show it no mercy. Click apply, and everything will disappear, probably giving you a black screen. The box you have before you contains the information for the layout. Within this section you can “call” on other panels, which sometimes have their own edit window, and those panels will be incorporated into the layout. In the top right corner of the edit window you should see something like this:

This box shows you which panels you currently have associated with that layout. Since we’ve deleted everything, they’re not doing much, so we can delete them too. Select each one and click delete to the right. Now you have a clean sheet. The first step is going to be adding the background. Write (or copy) the following text:

// Background
$drawrect(0,0,%_width%,%_height%,brushcolor-255-255-255 pencolor-null)
$imageabs2(1200,1000,0,0,0,0,$eval(%_width%-1200),$eval(%_height%-1000),$get(imgpath)background.png,)

The top tag tells foobar that everything following it is in the “Background” category, and therefore doesn’t need to update dynamically. Saves some processing power. The $drawrect function is a box that fits the entire size of the layout, and creates a white background (as opposed to the default black). This function can confuse people, but it is literally just drawing a rectangle and colouring it in. The $imageabs2 function is our background image, and I’ve used a little bit of maths to place it. The image is 1200 by 1000, and it is positioned at the full width minus 1200 (i.e. the far right edge of the layout) and the full height minus 1000 (i.e. the bottom edge of the layout). So the leaves will always be in the bottom right corner of the layout. This allows us to have a stretchy layout, that still looks good. The $get(imgpath) is referring to the user global that you set earlier, and leads to the image path. Click apply; if the image doesn’t appear, make sure the user global is correct.

7.3.4 Adding panels

Next we’ll add some panels. This layout uses only three panels: Single Column Playlist, Track Display and Quick Search (see components page, first two included with panelsUI). Again, the positioning of these panels involves a bit of maths to create a fluid layout that stretches. They need to be under the “Globals” tag, so type the following code:

// Global
$panel(Playlist,Single Column Playlist,50,45,$eval(4*%_width%/9),$eval(2*%_height%/3),)

The single column playlist (named as “Playlist” in this case) is positioned at 50px from the left, 45px from the top. The width is 4/9 of the overall width of foobar. The height is 2/3 of the overall height. If the foobar is stretched, the panel will stretch with it. Click “Apply” and the following will appear:

Foliage theme stretched

You should also notice that the panel gets listed in the top right box on the edit panel. If it doesn’t appear… something’s wrong. Er… email me.

Now, we’ll add the track display panel, which is a very versatile tool for showing current information, displaying pics, etc.

$panel(Display,Track Display,$eval(%_width%/2+30),60,$eval(4*%_width%/9),$eval({2*%_height%/3}-15),)

This is positioned at half the width plus 30px, and 60px from the top. The width is 4/9 of the width of the foobar, and 2/3 of the height, minus a little bit. Click “Apply”. The result will look like this:

Pretty, innit? We’ll make it a bit nicer.

7.3.5 Single Column Playlist editing

First we’ll make some changes to the single column playlist. Select the panel in the top right section of the edit window, and click “settings”. You should then see a window that looks like this:

Single column playlist editor

The only part of the window we’re interested in is the section called “layout settings”. The single column playlist has two sections: the group display and item display. The group display is for showing information such as album and artist title, and the item display shows each track within that group. You can change the height of the items in the top left of the layout settings. The default is 18 pixels, and we want ours to be 21 pixels. You can also change the height of the group display, and it is a multiple of the item height. The default is 2, and we want to have it as 5. Click apply, and you should see the playlist dimensions expand.

Group display

Currently the information in the group display is a bit ugly, so we’ll just start again from scratch. Make sure that the group display button is selected in the layout settings section, and delete all the code. Then add the following code:

// Background
$imageabs2(%_width%,400,0,0,0,0,0,0,$get(imgpath)box.PNG,nokeepaspect)
$drawrect(20,$eval(%_height%-10),$eval(%_width%-40),2,brushcolor-null pencolor-50-140-50)

As you’ve probably picked up, the // Background tag means that the following code doesn’t have to update regularly. The $imageabs function places an image of a rounded-corner box in our group display. The $rect function draws a green line which will just provide a nice green line to underline all the information we’re about to display. Click apply to see the changes (in fact, just do this whenever you change stuff from now on – I’ll stop saying it).

Next we’ll write out information about the album, such as the artist, album name and genre. It’s also preferable to show the album artwork, but it depends on 1) whether you have any, and 2) how organised you’ve been with it. I have all of my album artwork sitting within the folder which contains my music files for that album, and I’ve always called it “cover.jpg”. Others have all their artwork within one folder, and the name of the image is related to the album title. I prefer having everything within one place. If you don’t have album artwork then just skip this code. Otherwise, write this:

// Global
$drawrect(20,10,80,80,pencolor-150-150-150 brushcolor-null)
$alignabs(20,10,80,80,center,middle)no image
$imageabs2(80,80,0,0,0,0,20,10,$replace(%path%,%filename_ext%,cover.*),)

The $rect function draws a little grey box where the album artwork will sit, which you should only see if the album artwork is missing. It’s better than having a white space! The $alignabs function creates an invisible box which you can use to align text with respect to the left and top of the containing box. For instance, this box is 20px from the left, 10px from the top and is 80x80px in size. The text is aligned in the center of the box, and says “no image”. Again, this will only appear if there is no image to display. The image function is obviously the one that displays the artwork, but the path is a bit more complicated. The $replace function basically adds “cover.*” (where * is an extension wildcard, i.e. jpg, gif, png…) to the path of the album. If your album artwork is called anything else then just change “cover” to whatever. Now we’ll move on to displaying the album information.

// Global
$font(verdana,14,,90-90-90)
$alignabs(110,10,$eval(%_width%-20),%_height%,left,top)
$ifgreater($len(%artist%),$eval({%_width%-150}/10),$padcut(%artist%,$eval({{%_width%-150}/10}-2))...,%artist%)
$char(10)

Note – you only need to write // Global if you didn’t include the album artwork bit above. Firstly, the $font function sets the font, which I’ve defined as Verdana, 14pt and a darkish grey. The font will remain as this until it’s redefined. The $alignabs function draws an invisible box to place the text (see above). If you didn’t include the album artwork, set the value for x-position (i.e. 110) to about 30. Otherwise, keep it the same.

The next function looks extremely evil, but I’m actually quite proud of it. It cuts the artist’s name depending on the width of the box, e.g. “Dave Matthews Band” would become “Dave Matthe…” if there isn’t enough room to display it. Remember that our layout is fluid, so increasing the size of your foobar will increase the size of the single column playlist, and the cutting will adapt automatically. The final function, simply $char(10) is an ASCII character return, meaning new line. Next we’ll do similar stuff for other information.

$font(verdana,12,,90-90-90)
$ifgreater($len(%album%),$eval({%_width%-150}/8),$padcut(%album%,$eval({{%_width%-150}/8}-2))...,%album%)
$char(10)
$font(verdana,8,uppercase,140-140-140)
%genre%
$char(10)
%codec% - %bitrate%kbs

These functions have all been covered, and should make sense. They just show the album name, genre and then codec and average bitrate for the album. Now we’ve finished with the group display.

Item display

Next we’ll move on to the “item display” section – click the appropriate button in the playlist edit window to change. Then delete all the code in the box, and write the following lines in:

// Global
$if(%_selected%,$drawrect(12,0,$eval(%_width%-24),0,brushcolor-20-120-20 pencolor-null))
$if(%_focused%,$drawrect(12,0,$eval(%_width%-24),0,brushcolor-null pencolor-SYSCOL-6))
$if(%_selected%,$textcolor(225-255-225),$textcolor(60-60-60))

The top $if function draws a green rectangle, almost the width of the playlist, if the item is selected. The second function draws a black outline round an item if it is focused upon, which is slightly different. To see the difference just select several items by clicking on an item, holding SHIFT and clicking on another item. Several are selected, but only one shows the black border. The third function defines the colour of the text when selected (white in this case) and unselected (dark grey). Next bit of code:

$imageabs2(%_width%,$eval($meta(TOTALTRACKS)*20+22),0,$eval(%tracknumber%*20),0,0,0,0,$get(imgpath)box.png,nokeepaspect)
$padding(20,3)
$align(right,top)%title%
$align(left,top)%tracknumber%.

The image function is pretty complicated here. The image is a round corner green box, and this function draws a little section of it for each of the items. Each item in the single column playlist is treated as an isolated element, so drawing an image will draw that image on each item. But this function offsets the position of the image with each item, and it depends upon the tracknumber and the total number of tracks in the album. If the track number is equal to the total number of tracks then the end of the image is shown, which shows the curved corners (don’t worry if you don’t get this).

This is another function I’m kind of proud of, although the problem is that the image gets squashed or stretched depending on the number of tracks in the album, which isn’t ideal. Also, if your track information isn’t complete, for example if you don’t have the number of tracks in the album (you can add it in the track properties dialogue), it won’t display properly. The align functions display the track title (on the right) and the track number (on the left).

Congratulations, your single column playlist is complete! It should look like this:

Completed single column playlist editor

Finally, in the top right of the single column playlist edit window, where it says “Edge style”, change it to “none”. Now close the single column playlist edit window, to return to the main edit window.

7.3.6 Track display editing

Open the track display panel edit window using the box in the top right corner of the window. You should see this:

Track display panel

Song description

This code makes the track panel look pretty ugly. Delete everything in the central text box, and replace it with the following:

$padding(2,4)$alignabs(0,250,%_width%,$eval(%_height%-50),center,top)
$font(Verdana,22,,70-70-70)
$if(%_trackinfo_notrack%,
No track
,
%title%$char(10)
$font(Verdana,15,,80-80-80)%artist%$char(10)
$font(Verdana,15,,90-90-90)%genre%$char(10)
$font(Verdana,10,,100-100-100)%codec% - %bitrate%kbs
)
$imageabs2($eval(%_width%-80),10,0,0,0,0,40,15,$get(imgpath)bar.png,nokeepaspect)

I’ll walk you through it. The first two commands, $padding and $alignabs, are defining the dimensions and position of a bounding box, in which we can put text, etc. The $font command is self-explanatory, and we’ve seen it before. The $if function works out whether a track is playing, and displays “No track” if there isn’t. Otherwise, it displays the song title, artist, genre and track information in that order. Finally, the $imageabs2 function displays the image that we’ll use for the progress bar.

Progress bar and artwork

Adding the progress bar is a relatively complex step, and requires the powerpanels component. This is now pretty hard to get, since the official site seems to have gone down (as of 04/02/2009). However, I will provide a link to it here, and will continue to do so until someone complains:

Power Panels foobar component

Plonk this in your components folder in the foobar directory, and restart foobar. Go back to the track display edit window as previous, and add the following code:

// PerTrack
$drawrect($eval(%_width%/2-100),40,200,200,pencolor-0-100-0 brushcolor-null)
$imageabs2(200,200,0,0,0,0,$eval(%_width%/2-98),44,$replace(%path%,%filename_ext%,cover.*),nokeepaspect)

// PerSecond
$if(%isplaying%,$puts(l,$eval($eval(%_width%-80)*%playback_time_seconds% / %length_seconds%))
$imageabs2(38,39,0,0,0,0,$eval(18+$get(l)),0,$get(imgpath)slider.png,nokeepaspect)
,)

The first two functions, i.e. $drawrect and $imageabs2, draw a square border and place the track artwork respectively. The functions under the // Per Second group work out the length of the song, the current position, and place the image of the slider along the progress bar accordingly. You can follow my maths through if you want, but I won’t.

That’s all for the track display panel: almost finished! After applying the changes you’ve just made, your foobar should look pretty close to this:

The (almost) finished product

Although you probably won’t be playing anything from Lizard by King Crimson.

7.3.7 Final adjustments

Exit the track display edit window, to get to the main configuration window. Here, the most recent things you added were the bits of code that called the track display and single column playlist panels. Everything in this section can be placed after these commands.

Quick search toolbar

This requires the Quick Search Toolbar component, which you can download here:

Quick Search Toolbar

You know what to do. After putting it in your components directory, add the following code to the configuration screen:

$panel(Searchbar,Quick Search Toolbar,50,$eval(2*%_height%/3+55),$eval(4*%_width%/9),23,)

This places a search toolbar underneath the single column playlist. Right click on the toolbar to change the fields that you search for, and use it to quickly grab things from your library. You can edit it in the preferences.

Some rectangles

We’re going to draw some boxes around the playlist and track display. Just add the following code to the configuration window:

$drawrect(48,43,$eval(4*%_width%/9+4),2,pencolor-0-100-0 brushcolor-null)
$drawrect(48,$eval(2*%_height%/3+45),$eval(4*%_width%/9+4),2,pencolor-0-100-0 brushcolor-null)
$drawrect(48,45,2,$eval(2*%_height%/3),pencolor-0-100-0 brushcolor-null)
$drawrect($eval(4*%_width%/9+50),45,2,$eval(2*%_height%/3),pencolor-0-100-0 brushcolor-null)
$drawrect($eval(%_width%/2+28),43,$eval(4*%_width%/9+4),2,pencolor-0-100-0 brushcolor-null)
$drawrect($eval(%_width%/2+28),$eval({2*%_height%/3}+45),$eval(4*%_width%/9+4),2, pencolor-0-100-0 brushcolor-null)
$drawrect($eval(%_width%/2+28),45,2,$eval(2*%_height%/3),pencolor-0-100-0 brushcolor-null)
$drawrect($eval(%_width%/2+30+{4*%_width%/9}),45,2,$eval(2*%_height%/3),pencolor-0-100-0 brushcolor-null)

Although this may look complicated, it’s just drawing a series of 2px solid lines, at the edge of the single column playlist and track display panels. It requires a little bit of working out to determine where the edges are, but it’s a simple idea.

Power Panel

Finally, we’re going to add the power panel, which is an invisible seekbar that can be used to navigate through a track. You have to define the dimensions, but the panel works out all the difficult stuff. The way to use it is to place it underneath the progress bar that we’ve created for the track display. Put in the following code in the configuration window:

$panel(Seekbar,Seek Panel,$eval(%_width%/2+70),70, $eval(4*%_width%/9-80),20,)

Now play a song, and click anywhere along the progress bar. You should (hopefully) find that the song jumps depending on where you click the bar. If that doesn’t work, check that the component has been successfully installed (Preferences -> Components -> Seek Panel). If it says it is, send me a message and I’ll try and figure it out.

7.3.8 Final words

You should now have a working PanelsUI skin. It’s pretty basic, and not particularly pretty. But it does the job! Hopefully I’ll get round to making some attractive skins, if other stuff doesn’t get on top of me. Here is the complete PUI file, and the images pack again.

PUI file
Image pack

All that, just to listen to music?!

This section is pretty large, and potentially confusing, so you can use these links to jump to any point on the page.

1. Introduction
2. Basic functions
3. Panel function
4. Redraw types
5. Text, font and aligning
6. Buttons
7. Appearance functions
8. Persistent variables

7.2.1 First impressions

The code for PanelsUI is pretty much the same as the general foobar2000 code. However, there are several extra functions, the introduction of “persistent variables” and some usage differences. I’ll be referring to code for versions 0.13.x on this page, as it is the most stable.

First of all, you need to bookmark this site. It has all of the PanelsUI-specific titleformatting for version 0.13.x (use this page for version 0.14.x). You should also bookmark the track info panel wiki page, which gives more useful information. You can find information about the single column playlist here.

Practical differences

A very useful difference is that carriage returns, etc. don’t affect the result of the code. For example, you could have:

$ifequal (
    a
    b ,
    %result%,
    %alternative_result%
)

The spaces will not be read, where they would be normally. This is great, simply because you can lay your code out neatly and make it readable, by separating a long function out across several lines, for example.

7.2.2 Basic functions

Mathematical evaluation, $eval(…)

In PanelsUI you can use mathematical functions within the $eval(...) function. For example,

$eval( 5 * 6 )

returns 30. The operators that $eval() supports are “*” (multiply) “/” (divide), “+” (add), “-” (subtract) and “@” (modulus, returns remainder after division). You can use { and } as brackets for mathematical priority. E.g.

$eval ( { { 9 / 3 } + 5 } * 2 )

returns 16.

Defining position and size

There are two ways of defining the position or size of an object using PanelsUI.

The first way is to use pixels, which defines an absolute, static value. This is the result of defining a rectangle 400 pixels by 20 pixels, located at 50px from the left hand side and 70px from the top:

The other method is to use ratios. The width and height of the panel is given by %_width% and %_height%, and these variables return a pixel value. If you combine these with the $eval function (above), you can define position and size as a ratio of the total width and height. For example,

$eval( %_width% / 3 )

returns the pixel value of the total width, divided by three. If the total width was 600, it would return 200. This is useful for creating layouts that can be resized without affecting the appearance.

7.2.3 Panel function

Panels are inserted into code using the following function:

$panel ( id,
    panel,
    x , y ,
    width, height,
    ,
)

• id is a name of your choice for the panel, which has to be unique, e.g. “mypanel1″
• panel is the name of the panel, e.g. “Track Display” or “Single Column Playlist”: the drop-down menus under tools at the top of the window show the panels available
• x and y define the position of the panel from the top left corner of the containing panel, in pixels/ratio
• width and height define the size of the panel, in pixels/ratio

As an example,

$panel(Playlist,Single Column Playlist,20,20,450,300,)

creates a playlist panel, 450 x 300 pixels, 20 pixels from the top left corner:

Don’t forget the comma after the panel height. Technically there should be options at the end of the function, but none exist. The function will display nothing if you miss it out though!

7.2.4 Redraw types

A very important feature of PanelsUI is the redraw function. The redraw types tell foobar how regularly the proceeding code should be updated, i.e. every second, or every track, etc. They appear to be comments, in that they are written after two forward slashes, “//”. The redraw types are as follows:

• // Background – not updated dynamically, use for static objects
• // Global – anything that doesn’t need regular updating can quite happily go here
• // PerTrack – information that needs to be updated every track, such as %artist%
• // PerSecond – information that needs to be updated every second, such as %time%

These are also helpful for dividing your code up into sections. If your code isn’t displaying properly, just check that it is under the right redraw heading.

7.2.5 Text, fonts and aligning

text

If the panel supports it (e.g. Track Display panel), you can just write text and it should appear on the panel. You can use titleformatting on the fly, such as “The artist’s name is %artist%“.

For a carriage return, use $char(10), which is a unicode return.

font

Font is defined by the function:

$font ( font,
    size,
    options,
    colour
)

• font is the name of the font, e.g. “MS Sans Serif”
• size is the font size, e.g. 13
• options can be found on the panelsUI titleformatting page
• colour is in RGB format, e.g. 132-35-45

An example of this could be:

$font(Calibri,12,,255-255-255).

All the text that proceeds this statement will have those properties.

Align with $ALIGNABS

Text will be automatically aligned, but if you want to move it to a particular position you can use the $alignabs(...) function. You define an invisible rectangular area, of particular size and position, within which the text will fit. The function follows this format:

$alignabs ( x , y ,
    width, height,
    h-align, v-align,
)

• x and y define the position of the top left corner of the rectangular area, in pixels/ratio
• width and height define the width and height of the rectangular area, in pixels/ratio
• h-align defines the horizontal alignment of the text in the rectangle, i.e. left, center or right
• v-align defines the vertical alignment of the text in the rectangle, i.e. top, middle or bottom

As an example, the following function with text following it:

$alignabs(50,20,400,200,center,middle)hello

creates a rectangle at x = 50, y = 20, 400 x 200 pixels, with the text aligned in the center (I’ve drawn a rectangle around it to show the box):

$alignabs example

You can also use $alignrel(h-align, v-align) to quickly realign the text horizontally or vertically.

7.2.6 Buttons

There are two types of buttons in PanelsUI, font buttons and image buttons. They can be any size, in any position and perform almost any action. This allows for a lot of freedom!

Image buttons

Image buttons are created by the following function:

$button ( x , y ,
    hotspot-x, hotspot-y,
    hotspot-w, hotspot-h,
    image, hover image,
    command,
    options
)

• x and y are the position of the button, in pixels/ratio
• hotspot-x and y are the position within the button of the clickable region, leave 0 for whole button to be clickable
• hotspot-w and h are the width and height of the clickable region, leave 0 for whole button to be clickable
• image and hover image are the paths of the images when unactivated and activated, e.g. “C:\images\image.jpg”, without quotes
• command refers to the action performed by clicking on the button: the drop-down menus under “Tools” at the top of the window show these actions, also go to the panelsUI titleformatting page for special actions
• go to the titleformatting page for options, main option is TOOLTIP:”text”, providing a mouseover tooltip

When your mouse hovers over the button, it will change from the image to the hover image. Clicking it activates the command.

Text buttons

Text buttons are created by the following function:

$button2 ( x , y ,
    hotspot-x, hotspot-y,
    hotspot-w, hotspot-h,
    text, hover text,
    command,
    options
)

• x and y are the position of the button, in pixels/ratio
• hotspot-x and y are the position within the button of the clickable region, leave 0 for whole button to be clickable
• hotspot-w and h are the width and height of the clickable region, leave 0 for whole button to be clickable
• text and hover text refer to the text shown when activated and unactivated
• command refers to the action performed by clicking on the button: the drop-down menus under “Tools” at the top of the window show these actions, also go to the panelsUI titleformatting page for special actions
• go to the titleformatting page for options, main option is TOOLTIP:”text”, providing a mouseover tooltip

When your mouse hovers over the button, it will change from the text to the hover text. Clicking it activates the command.

7.2.7 Appearance functions

Rectangles

PanelsUI provides a rectangle draw function, with which you can draw a rectangle of any colour and size, and at any position you choose. The function is written as $drawrect(...), and follows this format:

$drawrect ( x , y ,
    a , b ,
    brushcolor-xx pencolor-xx options
)

• x and y define the position of the top left corner of the rectangle, in pixels/ratio
• a and b are the width and height of the rectangle, respectively, in pixels/ratio
• brushcolor is the fill colour of the rectangle, where “xx” can be in the form of “R-G-B”, with a 0 to 255 value for each colour, or “SYSCOL-??” (two digits)
• pencolor is the outline colour of the rectangle, in the same form as brushcolor
• see the panelsUI titleformatting reference for all the options

An example of this:

$drawrect( 40 , 40 , 300 , 20 , pencolor-255-0-0 brushcolor-255-255-255 )

This creates a rectangle 40 pixels from the top left corner of the panel, 300 pixels long by 20 high, with a red outline and white fill:

Images

PanelsUI has a two brilliant image display functions, written as $imageabs(...) and $imageabs2(...). They can display an image at a specified size and position, allowing some beautiful layouts if used well. I find that $imageabs2 tends to be more reliable, and gives you far more control over your image display, so it’s best just to use that. It is pretty complicated, but I’ll try to describe it as well as I can. The format is as follows:

$imageabs2( a , b ,
    left , down ,
    width, height,
    x , y ,
    path,
    options
)

• a and b define the area taken up by the image, and the image will expand or shrink to fit it
• left and down define the position within the image, i.e. left is how many pixels left from the upper left corner, etc. Rarely needed, so setting both to 0 produces no effect
• width and height define the cropping width and height. If they are the same as the image size, nothing changes. If they are set to 0 then there is no cropping. If they are set to less than the width or height of the image, the image is cropped to that size
• x and y define the position of the top left corner of the image from the top left of the window or panel, in pixels/ratio
• path is a reference to the image location on your computer, e.g. “C:\images\image.jpg”, without quotes
• see the track panel info page for all the options, some include rotating and flipping the image, applying transparency and choosing to retain aspect ratio when resizing

An example of this in use would be something like this:

$imageabs2(250,250,0,0,0,0,20,20,C:\foobar\cdcase.png, nokeepaspect )

This displays “cdcase.png” at 250 x 250 pixels, placed at x = 20, y = 20 in the panel, with no cropping and ignoring aspect ratio:

An example of $imageabs2 in use

The best way to learn this function is by trying it out with different options and cropping. A good use is in displaying artwork within the single column playlist or track display panel.

7.2.8 Persistent variables (PVARs)

PVARs are variables that, dammit, just won’t go away. If they are assigned a particular value, they have to be explicitly told if that value is to change. In any section of the layout the PVAR can be called upon, and its value will remain consistent. It is useful for creating multiple scenarios within one layout. For instance, you could create a mini-layout and a full-screen layout, and a button click could swap between them. The button click will change the value of the PVAR, and your code will be seperated into two sections, with each section functioning only when the PVAR has a particular value. This may sound confusing, but we’ll do some practical stuff in the next section so you can pick it up.

A PVAR is defined with the following:

$setpvar( mypvar, value )

and recalled with:

$getpvar( mypvar ).

Next section: 7.3 Creating a PanelsUI layout

A quick note

I know that development for PanelsUI has been paused, quite possibly stopped. Please don’t email me telling me that my guide is pointless! I still believe this is currently the best UI for foobar, and it is by far the most versatile. There were issues with the 0.14.x release, but the 0.13.x release works beautifully, so you’ll have very few issues if you use that. And, just in case the developer(s) of panelsUI happen to read this, please start development again!

Downloading, installing and setting it up

You can download panelsUI version 0.13.x from here. Place it in your components directory as you would with any other component, and when you next start foobar you should get a dialog asking you to choose your UI. Select panels, and you should see your foobar looking something like this:

PanelsUI default view

Looks pretty naff, I know. But this is merely to throw you off guard, as you have not yet supped the raw power under the bonnet.

Layout

The layout is made up of certain panels, such as the “Track Display” panel at the top, showing the song title and artist. Just beneath this is the “Single Column Playlist”, which shows the queued tracks (or your entire library if unfiltered) organised into albums. Both of these two components come with panelsUI, and are very powerful. The track display panel in particular opens up almost endless possibilities. Below these panels are the buttons and the progress bar (not seek bar yet, as it isn’t clickable), which are self-explanatory. This layout takes up negligible RAM, but you do pay for it in terms of usability!

With the playlist display, all your tracks are grouped into albums. Each album has a group title on a header or banner, called the “group display”, followed by the tracks listed one by one, the “track display”. The tracks in an album can be selected by clicking on the header once.

Settings

The settings for PanelsUI is in the expected place on the preferences page, in the display tab. Selecting this will produce a window like the following:

PanelsUI settings

Here is where you can choose the layout, and create new ones. You can also define global variables that can be used throughout all sections of the layout. For the moment, we’ll stick with the default layout and just make a couple of aesthetic changes. Just in case something goes wrong, it’s best to create a new layout as a copy of the default. Click “new” and name your layout, and your layout will be an identical copy of the default layout. Now click “Edit Layout” to bring up the editing window.

What the…?

Yes, it looks a little confusing. The first time I opened this up, I gave up on the spot. And I couldn’t for the life of me find a guide on the internet on how to use it (hence this one)! But after a while I gave it another go, and gradually came to understand it.

Panels configuration panel

What you see in front of you is the main layout editing window. From here everything about the layout is controlled. At the top left of the window, under “Tools”, are reference tools for things like menu options, available panels and various things that foobar performs. They don’t actually do anything, they’re just for jogging your memory for certain options, so you can ignore them for the time being.

To the right of the tools is a display of panels that are included on this layout page. As I showed earlier, there is a track display (called “Playing”) and a single column playlist (called “Playlist2″). Each of these can be selected, enabling the “settings” button to the right. Clicking on settings brings up a similar window, but this window contains the layout for that particular panel.

Panel configuration

And that’s how panels works. Code is broken down into sections, with lots of panels performing different jobs and the main layout referring to each of these panels, and placing them at the right place. As you’ve probably guessed, the main section of the window is taken up by the code, which describes the layout.

Appearance changes

Just so that the dullness of the default layout doesn’t make your eyes bleed much longer, I’ll give you a few neat little changes to apply. Wherever the word SYSCOL-xx appears, you can replace this with any colour you want (rather than a boring greyish theme). This is done by replacing the word SYSCOL-xx with an RGB value R-G-B, with the dashes. For example, pencolor-SYSCOL-13 becomes pencolor-255-255-255 for a white border.

Play around with these to find a nice colour scheme. If you want a quick fix, I’ve made a black and orange themed default layout, which you can get here (click the image):

Download the black and orange panelsUI theme

Download this file and move it to your foobar directory, to the PanelsUI folder. Restart foobar, and on the panelsUI main preferences window it should appear in the drop-down layout menu.

In the next section I’ll go into detail on the code syntax and special panelsUI functions, allowing you to really understand what’s going on in these windows and giving you the opportunity to make major tweaks.

Next section: 7.2 PanelsUI code

• 7.1 Finding your way around PanelsUI
  • Provides a basic tutorial on using PanelsUI for the first time, and navigating the various sectionsof the interface
  • Very basic appearance tweaks will be covered
• 7.2 PanelsUI code
  • The code syntax for panelsUI will be explained
  • The differences between standard title formatting code (see previous page) and panelsUI code will be highlighted
  • Particular focus rectangle, image and button functions
  • Introduction to persistent variables (PVARs)
• 7.3 Creating a layout
  • Creating your first layout with panelsUI and some basic graphics editing

A lot of this tutorial is fairly advanced, and if you are new to foobar2000, it is recommended that you start at the beginning! Otherwise, onwards…

Know your friends

Before you do anything else, you need to bookmark this site: http://wiki.hydrogenaudio.org/index.php?title=Foo….

There is no chance that you can remember all of the hundreds of functions and field references, and there is no shame in having them all in one handy place. There is also a similar page for panelsUI-specific commands: http://wiki.hydrogenaudio.org/index.php?title=Foob…, but there will be more on panelsUI code later.

Syntax introduction

Foobar’s code is known as “title formatting”. The declarations can be divided into two main categories: field references and functions. Field references are things which you can call upon to return a value, such as the name of the artist of the current track or the length of a song. Functions will perform a particular action on something, such as converting a word to uppercase letters or defining a colour.

Field references are within two percentage symbols, e.g. %artist%, which would return the name of the artist. You can find and edit some of these if you go to the properties page of a track, such as %title%, %album%, %genre%, etc.

Functions are written with a dollar symbol beforehand, and brackets enclosing the functionee, e.g. $upper(%artist%), which would return the name of the artist but in uppercase letters. You can have functions within functions, and field references within functions are essential to editing.

Strings are also an important concept. They simply mean words, i.e. a string of letters, so, for example, %artist% returns a string.

Sound simple? Well it is, at the moment. This is just the tip of the iceberg, Timmy.

One quick note: I won’t really be providing any sort of context for the code on this page. This will be about getting you familiar with the way the code works, and I’ll put it in context on the respective columnsUI and panelsUI pages.

If statements

If you are familiar with any programming language then you will know about if statements. I’ll explain them anyway. They are extremely instrumental in all languages, and allow for programs, or foobars in this case, to make intelligent decisions. They work by saying “if this is true then I’ll do this, but if it isn’t true I’ll do this instead”.

Let’s take the following example: I want one of my columns in my foobar to display the artist name, but if there is no artist then I want it to say “No Artist” rather than just saying nothing. Foobar’s if statement looks like the folloing:

$if( condition, thendothis, otherwisedothis )

The statement will always treat the “condition” as true or false, 1 or 0, so it needs to be the right kind of variable. So I could put %artist% in the condition part and the evaluate part, and that would be fine. My code will look like this:

$if(%artist%,%artist%,'No Artist')

If you are using the default UI or columnsUI, you will have to put words that are in functions (like above, with ‘No Artist’) within single quotes. PanelsUI allows for no quotes.

There are several variants on the if statement with foobar, such as:

$ifgreater(a,b,one,two)

If a is greater than b then carry out one, otherwise two

$if3(a,b,c,d... else)

This will keep evaluating any arguments until one is found to be true, and then it returns that value; otherwise returns else

The other $if related statements can be found on the title formatting web page.

Variables

Foobar allows for the use of variables, a basic building block of programming. I won’t spend time explaining what a variable is, but I’ll give an example. A variable is defined by using the $put or $puts statement, which does what it says: it “puts” something (a word, number, field reference, etc.) into storage for later use. You can then recover this variable with the $get statement. The $put or $puts statement works like this:

$put(myvariable,something)

“something” will then be stored in a variable called “myvariable”. To return the variable at any time, we would use $get(myvariable). This would give the output of “something”. E.g.:

$put(doo,foo)
$put(dah,bar)
get(doo)$get(dah) = foobar

$put and $puts work differently in that $put will always output whatever you give it as well as storing it, whereas $puts will only store it.

Colours and pretty things

You can define a colour for text using $rgb(r,g,b,r1,g1,b1), where r, g and b define the normal colour in red, green and blue and r1, g1 and b1 define the colour when the text is selected. Useful for specific visual styling. For other methods of defining colours see the title formatting page.

Colours can also be blended using the $blend function:

$blend(colour1,colour2,x,total)

where x is however many “parts” of colour1 and total is the total number of “parts”. Therefore the number of parts of colour2 will be total-x. The result will be a mixture of the two colours, much like mixing a drink. Nine parts gin, one part tonic…

Strings can have a colour transition applied to them, using the $transition function:

$transition(string,color1,color2)

As a bit of an unattractive example, choosing %artist% as the string and the colours as red and blue, you would get something like the following:

Unfortunately, it’s hard to make that function look good. So go for subtle transitions if you are going to use it.

String functions

There are loads. You can do almost anything with your words, if you know how – this is another great strength of foobar. So check out the title formatting page (I can’t be bothered to keep putting a link on that, just look at the top) and scroll to the strings bit. Here are some of Jon’s top string functions:

• $upper(s) – converts string s to uppercase
• $len(s) – calculates length of string
• $char(x) – inserts unicode character (list here), but you need it in decimal mode, so use this site
• $progress(pos,range,len,a,b) – creates progress bar where pos would be %_time_elapsed_seconds%, range is %_time_total_seconds%, len is how long you want the bar to be, and a and b are characters/strings that will make the physical appearance of the bar

There are plenty more, such as functions that cut strings up into pieces, compare two strings to each other and move prefixes such as “A” and “The” to the end of the string.

Mathematical/boolean functions

If it really gets you going, you might like to do a bit of maths while listening to your music. And I’m happy to report that foobar can accomodate you, you weirdo.

• $add(a,b), $mul(a,b) – adds/multiplies a and b
• $div(a,b), $sub(a,b) – divides a by b, subtracts b from a
• $greater(a,b) – if a is greater than b returns true (i.e. “1″), otherwise false

Etc. The others are listed… guess where?

Boolean functions such as AND, OR, NOT are also supported by foobar.

Final words

Well that’s it my friends. You will soon enjoy a total dive into social isolation as you realise how stupidly addictive it is just to tweak even the tiniest settings of your foobar.

Enjoy.

Next section: 7. PanelsUI

To do this section you will need to be familiar with foobar’s code syntax. If you aren’t then take a look at part 6 first, then come back here.

Editing the title bar

We’ll start off nice and easy. Under the “main” tab of ColumnUI’s preferences, at the bottom of the window, you’ll find a box entitled “Main window title format script”. You can freely edit what it says at the top of your foobar using titleformatting, instead of having just the default “foobar2000″. I like to have it display the song title, artist name and the playback time and length, so the script will look like this:

foobar 2000 - %artist%: %title% '('%playback_time%/%length%')'

This gives a title bar that looks like this:

Window title bar

The title bar format area will read everything you put in, including spaces, and doesn’t require quotes for words and most letters. Certain letters such as $ and ( or ) need to be enclosed in apostrophes to show.

At one point I made a little progress bar that appeared in the title bar, and though it can look a bit naff the code would be something like this:

|$progress(%_time_elapsed_seconds%,%_time_total_seconds%,100,#,-)|

Window title progress bar

Lovely, no? You can change the length of the bar by changing “100″ to whatever number you like, and can change the characters that make up the bar.

Would love to hear if you come up with anything inventive and attractive to put in the title bar!

Global variables

An important concept in ColumnsUI is the global variable. This works by setting a variable that can be called upon anywhere within the columnsUI appearance preferences. They are set in the globals window, under “playlist view”, and in the variables tab:

Playlist view global variables

Global variables follow the same structure as normal variables, i.e.:

$set_global(myvariable,something)

In this case, “something” is put into “myvariable”. They can then be called by using:

$get_global(myvariable)

This is very useful for defining a set of colours that you will use regularly, particularly when it comes to using the “Columns” tab (top of the window, I’ll go through that soon). For instance,

$set_global(mycolour1,$rgb(233,0,20))

sets a reddish colour as a global variable “mycolour1″ that I can call upon any time.

Columns editing

This is where columnsUI gets really good. You see all those columns in the columns playlist on your foobar? You can edit all sorts of things about them, such as what they display, their visual style and the way they sort (though I won’t touch on that, I think they sort fine). On the “playlist view” page in preferences head to the “columns” tab at the top of the window, and you’ll see something like this:

Columns in playlist view

Yours, however, will look different as I have a silly number of columns, for different occasions.

More coming soon…hopefully. Although I wrote this about 3 years ago.

Next section: 6. Code Syntax

Required components

To create a basic iTunes layout, the following components (not included with columnsUI) are required:

• Album art panel (foo_uie_albumart)
• Music browser (foo_browser)
• Quick search toolbar (foo_uie_quicksearch)

To create the advanced iTunes layout, the additional components are required:

• PanelsUI (but you don’t need to know how to use it!)
• Power Panels (foo_uie_powerpanels)
• (Optional) Channel spectrum panel (foo_uie_vis_channel_spectrum)

5.2.1 Creating a basic version

Basic layout

Create a new preset in the columns UI preferences window, layout tab. The basic layout is as follows:

Basic itunes layout

This gives you the shape, though there’s plenty of tweaking to be done.

Firstly, remove the captions for everything except the playlist switcher, album art and browser panels by clicking on each item in the layout and unclicking “Show caption” in the item details menu. Click on the first browser panel in the layout list, and in the item details menu click “configure” near the bottom. In the pop-up menu that appears, choose “Genre”. Then click “Use custom title” and type in “Genre”. Do similar things for the next two, but replace genre with artist and then album.

For the album art to work, you need to place the cover image file in the folder that contains the album, and name the file “folder”, “cover” or “front” plus the extension. You can call them something else, but you have to add the name in the album art preferences by right clicking on the panel and moving to the “Sources” tab.

Colours and fonts

Go to the “Colours and Fonts” sub-section of columnsUI preferences, and go to the fonts tab.

Colours and fonts panel

For the element “Common (list items)”, select Custom from the mode selection menu. Then choose Microsoft Sans Serif, 9pt as the font. Do the same for “Columns Playlist (items)”, except 8pt.

Under the colours tab, use the following tables to apply the red-green-blue colours for the elements “Playlist Switcher” and “Global”. For each element you modify, you have to select “Custom” from the the mode selection menu.

Then head to the “Playlist view” subsection of Columns UI preferences, and then the “Globals” tab, then the “Style” sub-tab on that page:

Global style variables

Select everything in the style window, and replace it with:

$ifequal($mod(%playlist_number%,2),0,
$puts(back,$rgb(240,240,255))
,
$puts(back,$rgb(255,255,255))
)
$puts(back-selected,$rgb(80,113,226))
$puts(back-selected-no-focus,$rgb(172,172,172))
$set_style(back,$get(back),$get(back-selected),$get(back-selected-no-focus)))

You don’t need to know what that means yet. It should provide a nice alternating white and very light blue background for the playlist, just like iTunes. Oooh, itunesy.

Browser

You can change the colours of the browser panels by going to “Preferences -> Media -> Browser”:

Browser playlist panel

Tick the custom selection colours box, and use the following colours to get the right combination:

Again, use Microsoft Sans Serif 9pt for font.

You should also select “Automatically Activate” on the browser. You can rename the “*Browser*” playlist to anything else, such as “My Music”. And finally, check “Hide Column Headers”, which will mean that all your panel captions are of the same format. This looks especially good in Vista.

One thing I find useful is to map a keyboard shortcut to  refresh the browser contents. When you start using the browser, you narrow your libray down and effectively make your playlist smaller, but you can bring your whole library back by refreshing the browser contents. This can be done in the main menu, or, as is my preference, by mapping a keyboard command to it. This is done in the preferences window, under “General -> Keyboard Shortcuts”. Click “Add New”, then type in “refresh” in the filter box, then select the command. With your new shortcut still selected, put in a suitable keyboard command. Then save.

5.2.2 Creating a more advanced version

The finished result will hopefully look something like this:

iTunes style layout

The advanced layout makes use of the “Track Display”, which is a component that comes with panelsUI. Having unzipped panelsUI to your components folder, make sure you load your foobar with columnsUI.

Firstly, create the following layout, following with the steps shown in the basic section to configure the panels:

iTunes advanced layout

Then download the following rar file containing images (that I’ve created to mimick iTunes, completely from scratch to avoid copyright issues):

Download myitunes.rar

Extract this to a memorable directory: I chose C:\foobar\myitunes as the directory for my images, and it will be very easy for you if you do the same, otherwise you will have to follow the steps in italics below. (Edit: how Windows-biased was I back then?)

Go to the layout page. For the first track display panel, select it and click configure at the bottom right of the window. You will get a window with lots of code in. Delete all the text in the window that comes up, and copy and paste the code from the following text file:

top track display

You will end up with this (hopefully):

Track display script

Ignore this if you used C:\foobar\myitunes as the image directory

At the top of the track display window, there will be a couple of lines starting with “//”, which are comments. After that, you will see $puts(path,'C:\foobar\myitunes\'). Here you should replace the directory in quotes with your directory, also in quotes. Then follow the page down to some more comments, where it says “You also need to change the location of slider.png…”. After the comments, wherever you see C:\foobar\myitunes\ you should replace it with your directory.

Ok, stop ignoring now

Now click “ok” on the track display panel window, then “apply” on the columnsUI window, and the changes will be made. For the second track display panel use the code from this file:

top trackdisplay

Again, replace the directory as required.

If it all works correctly, then that’s great! Chances are that there could be problems with things in the track displays overlapping or not quite fitting. That’s because I’m using a different resolution screen to you – try this one:

top track display – smaller

To configure the spectrum, click on the little button to the left of the seekbar on the top track panel, which will bring up the spectrum meter in default format:

Click this to bring up the spectrum analyser

Right click on the spectrum in the main foobar window and click configure. Choose a light grey foreground1, and black for foreground2 and background. Check “transparent background” and “bar mode”, and choose a bar width of 4. It should look like this:

Spectrum configuration

That should give you a good iTunes style spectrum meter. Play around with the settings of the spectrum, you can get some great effects.

This brings an end to the iTunes layout tutorial. I hope you’ve had success! If you haven’t, email me at jon@joncairns.com and let me know the problem. Next we’ll look at some advanced tweaking.

Next section: 5.3 Tweaking ColumnsUI

Getting started

When you’ve unzipped the columns dll to your foobar components directory and load foobar for the first time, it will ask you which user interface you would like to use – choose columns. A dialog will then come up requesting a quick setup. Choose “Columns Playlist + Playlist Tabs”, as we’re going to make a layout similar to the others, and I don’t want to make it too easy for you. You can use Vista theming if you fancy.

The layout of your foobar will be controlled by from the Preferences, under “Display -> Columns UI” tab. When you click on this tab, a page like the following will appear:

ColumnsUI preferences panel

This is the main page of the columnsUI preferences. On the main page, you can access various tabs, which are described as follows:

• Main – Not hugely important, but the FCS/FCL stuff is about importing and exporting layouts. You can also control the transparency of your window, choosing an alpha value between 0 (invisible) and 255 (opaque).
• Layout – The overall shape of your foobar is controlled from here, and this page will mostly explain how to use this.
• Status bar – This controls the bar shown at the bottom of the window, giving information such as volume, audio codec, bitrate, sample rate, etc.
• Notification area – You can use a windows tooltip to give you track information, and this page also controls tray icon properties.
• Filter – Ah, don’t even bother going here yet.
• Artwork – Or here. You can get better artwork components anyway.

The sub-categories for Columns UI are “Colours and Fonts”, “Playlist switcher” and “Playlist view”, but we’ll get to those later.

Creating a layout

Click on the layout tab, and you’ll see something like this:

ColumnsUI layout preferences panel

We’re going to create a simple layout, with just a playlist selector on one side of the screen, and a playlist display on the other side. The default preset should be “Default”. To create a new layout, click “New” next to the preset selector, and create a name (I’ve inventively called mine “columns”, but the name has no effect on the appearance). By default, the box displaying the layout information contains a single panel called “Columns playlist”.

ColumnsUI works by using vertical and horizontal splitters to divide up the window, and you can place panels within each section that you create. Therefore, right click on “Columns Playlist” to bring up a menu, then go to “Change base -> Splitters -> Horizontal splitter”. Then right click on the splitter, and go to “Insert panel -> Panel -> Playlist switcher”, then right click on the splitter again and go to “Inset panels -> Playlist views -> Columns playlist”. You can find item details for each item on the layout tree, just to the right. You can hide any of the panels, choose not to show the caption, etc.

Click on “Apply” and watch your foobar change! There’s no need to exit the preferences window, as you can click on anything in the main window with it still open (if you are ever worried that you’ve lost the menu, you can use Ctrl+P to bring up the preferences at any time). Your foobar will be split down the middle with your music on the right, and a playlist organiser showing one or two playlists on the left.

Using the layout

On the left, the “playlist switcher” will display any saved playlists you have, and you can add new playlists by right clicking on the panel and going to “new”. The easiest way to add tracks to a playlist is by selecting them and holding the right mouse button, then moving to the playlist and dropping the files on to it. You can also add them by right clicking on the tracks, and going to “Edit other” to find playlist tools.

You can resize splitters by hovering your mouse over the splitter boundaries, an extremely useful property. You can place panels and splitters within other splitters to get some interesting layouts.

You can also move all the buttons and toolbars that are at the top of the window by default. You can do this by navigating to the Main tab of the columns UI preferences and unselecting the “show toolbars” box. Then you can place the seekbar, menu, buttons, etc. wherever you like. For example, try the following layout tree, selecting no caption for each item:

A good columns layout tree

After some resizing, you will have a layout with a playlist switcher on the left, queued tracks on the right, and a seekbar plus toolbar at the bottom. Ha! We have broken the mould of programs with menus at the top.

Have a play around with the layouts, and try different combinations of panels. In the “Colours and Fonts” sub-section, you can can completely customise the… erm… colours and fonts. It’s pretty self-explanatory, so mess around with that and see what you get.

When you’ve got a set-up you can use, click “Save all” at the bottom-right of the preferences window.

In the next section, I’ll go through the steps to create an iTunes-style layout.

Next section: 5.2 Creating a ColumnsUI layout 

• 5.1 Finding your way around ColumnsUI
  • Provides a basic tutorial on using ColumnsUI for the first time, and navigating the columnsUI preferences
  • Goes through the process of creating a simple layout
• 5.2 Creating an iTunes style layout
  • Both a simple and advanced aproach to creating an iTunes style foobar
  • A look at fonts and colours
  • Short tutorial on using foo_browser
  • Image and code downloads for creating the perfect lookalike
• 5.3 Code-based tweaks (advanced)
  • Some more loose ends with columnsUI
  • Editing your toolbar
  • Changing playlist properties
  • Using frames, progress bars, etc.

The third section involves the use of foobar’s scripting language, which is explained more in the next section. If you’re new to this, it’s advised that you miss it out, and maybe come back to it after looking at the code section.