Modern Skins

Simple Skin Example

We will begin with a simple skin example. I'll give you the essential parts of the skin. In the next section, I'll demonstrate important Winamp3 concepts using this skin. The topics that I'll go over are:

1. Winamp3 Skin Directory Hierarchy
2. Simple Tutorial Skin - Graphics Files
3. Simple Tutorial Skin - Skin.xml
4. Simple Tutorial Skin - Player.xml

1. Winamp3 Skin Directory Hierarchy

a) Skin Hierarchy

Before you start playing with a skin, you have to know where everything is. Above is a picture of the Winamp directory. If you open that directory ("C:\Program Files\Winamp") with Windows Explorer, it should look pretty similar. The section in blue is the "Skin" directory and the directory that we care about. Within the "Skin" directory, there are sub-directories and files. Each sub-directory and WAL files are a skin. WAL is Winamp3 skin format. Next section talks about how to manipulate it.

b) .WAL files

Instead of a directory for a skin, you may see only one file with a .WAL extension. Don't worry. WAL (Winamp Abstraction Layer) is Winamp3 skin format. It is basically a zipped file of the skin directory. We do this to save space and to make it easier to distribute the skins. To make changes to that skin, do the following:
  1) Rename the .WAL file to .ZIP
  2) Open that file with Winzip. If you don't have it, you can get it here. www.winzip.com
  3) Unzip the content into a directory.

c) Required file

Lets take a look at what's in a skin directory. We'll use the "Simple Tutorial" as an example. Keep in mind that other skins may contain other files and directories that are not shown. What we're showing here is the bare minimum example.

Within the "Simple Tutorial" skin directory, there are three items: 1) Skin.xml file, 2) "Player" directory, 3) "XML" directory. The only required file for a skin is the Skin.xml file. It is the file that the Winamp3 skin engine looks for. You can say that it is the entry point for the skin. From that file, all the fun starts. =) I will dissect that file later on.

The "Player" directory contains all the graphics files for the skin. The files are in .PNG (Portable Network Graphics) format. The "XML" directory is usually where all the XML files are located. Because our skin is relatively simple, there is only one file in that directory.

d) #include in XML files

One more thing I want to go over is the <include file="xml/player.xml"/ > tag. When the Winamp skinning engine parses this XML file and encounters that tag, it grabs the file specified within that tag and pastes whatever code is inside that file into the current file. So in this example, we're looking at the skin.xml file. The skinning engine will grab player.xml file in the xml subdirectory and paste whatever code that is inside player.xml into skin.xml. This process is recursive. This means that if there's any include file tag inside player.xml, it will get those code also.

2. Simple Tutorial Skin - Graphics Files

These are the graphics that I've used in creating Simple Tutorial skin. One thing to notice is that we like to use PNG file format. Please also use that format too. The graphics files are the parts that we're going to use for our skin. We will define them as elements and link them into our XML code later in order to use them.

3. Simple Tutorial Skin - skin.xml

The required file for any skin is the Skin.xml file. You can locate this file in your "C:\Program Files\Winamp\Skins\Simple Tutorial" directory. The content of that file is posted above. I'll go over all the parts. I have listed line numbers on the left and code on the right. You can open your version and follow along.

a) <?XML> (line 1)

The first line of the Skin.xml file should be the line shown above. The line identifies Skin.xml as an XML file. It is important to remember that you need that line only once in Skin.xml. If you divide your xml into several files, do not include that line in other xml files. Subsequent xml files will be pasted into Skin.xml file by the skin engine.

b) <WinampAbstractionLayer> (line 3)

The WinampAbstractionLayer tag is used to specify which skin version you're following. The version that "Simple Tutorial" skin is made for is 0.8. This tag is used to track compatability. We will keep compatability as long as possible. But sometimes when we introduce a new funcitonality and change an existing one, compatability is broken and we will increment the version number. You will need to update the skin to conform to the new standard. If the skin engine finds your version number is different than the current version, you will see the warning below. However, this does not mean that your skin will no longer work. If functionality that has been changed is not implemented in your skin, you skin will continue to function.

c) <skininfo> section (line 4-12)

The tags are all pretty self-explanatory. But lets go over them anyway for fun.

d) <include> section (line 13-20)

I have discussed <include> functionality above. Note that we're borrowing skins from the Default skin. The only component's appearance we're overriding is the main player. The specification for that is in player.xml (line 14). We'll go over that file next.

4. Simple Tutorial Skin - player.xml

a) Name and comments (line 1-3)

The first section of your XML should be a comment section that briefly explains the functionalities of the file. This way it will be easy for others to read and understand your code.

b) Elements definition (line 4-18)

This section defines all the elements in your skin. This is the part that links the graphics to a "bitmap id" that other XML code can refer to. For example, line 11 links a bitmap id, "blue-player.button.previous", to a graphics component in "player/blue/blue-previous.png" file. That bitmap id is also linked to a gamma group called "Buttons". After linking that object to a gamma group, user can adjust the color variance of that object in the preference menu. Therefore, even if that object is blue right now, you can change it so that it'll appear to be a different color.

As your skin becomes more complex, you will have many elements defined in your skin. It will be useful to break the <Elements> definitions into different files. Typically, one would define all the elements in each component in separate files. For example, elements in the main player will be in "player-elements.xml" and elements in the playlist will be in "pledit-elements.xml".

c) Playback Buttons Group Definition (line 19-64)

Sometime a group of objects naturally belong together or are located next to each other. If you move one of them, chances are that you'll be moving the rest of them. The playback buttons is an excellent example. If you want to change the location of those button, rather than moving each element independently, you can define a group and move the group together. A group is a set of objects that can be referred to and manipulated as a whole. It is a like a bag to throw your stuff into. It first must be defined by a <groupdef> tag, then can be located with a <group> tag. In section 2.5, we're going to dissect it even more.

d) Song File Information and Visualization Group Definition (line 65-107)

SongInfo group is another group definition just like the Playback Buttons group. As you can see that the elements defined inside this group is different from the previous one. In this example, we're using elements other than buttons. We're using the layer to set the background color of two areas. A layer is basically an image. Layers can overlay on top of each other. It is similar to a layer in Adobe Photoshop. "Songinfo" and "infoline" are text objects displaying information stored within Winamp3 runtime variables.

e) Main Window: Container and Layout (line 1-3)

Previous sections are all about defining objects. Now we get to start using them. If you read the code, you'll see that there is a container object, a layout object and two group objects. Container is at the top of hierarchy because everything else "lives" in it. Within the container, we have defined a layout and, within the layout, we're using the groups we defined earlier.

Container, layout and group are important concepts and we will go more in depth in subsequent sections. Read on...

Simple Modern Skin Tutorial (Continued)