WINAMP 3: SKINNING TUTORIAL WEBPAGE

By: Ken Chen

[email protected]

Version 08.14.2002

TABLE OF CONTENTS
WINAMP 3: SKINNING TUTORIAL WEBPAGE......1
Winamp3 Skinning Tutorial.....................................................4
Tutorial Status Report ..................................................................................................... 4
Contact Us....................................................................................................................... 5
Skinning FAQ - Frequently Asked Questions ............................6
Frequently Asked Questions ........................................................................................... 6
Skinning FAQ - Answers ................................................................................................ 6
Winamp3 Skinning Glossary....................................................8
Frequently Asked Questions ........................................................................................... 8
Part 0. Intro to Winamp3......................................................10
Why do we need Winamp3? ......................................................................................... 10
Winamp3 Components? ................................................................................................ 10
Part I. Winamp 2 to Winamp3 ...............................................12
OUTLINE ..................................................................................................................... 12
W3 Skinning Tutorial - 2.1 Start Here!...................................13
Simple Tutorial Skin ..................................................................................................... 13
Text Editing Programs .................................................................................................. 14
A graphics program....................................................................................................... 15
Contact Us..................................................................................................................... 16
W3 Skinning Tutorial - 2.2 XML Introduction .........................17
1. So what is XML? ...................................................................................................... 17
2. XML Hierarchy......................................................................................................... 18
3. XML & Winamp ....................................................................................................... 19
W3 Skinning Tutoria l - 2.2 XML Introduction .........................20
1. Winamp3 Skin Directory Hierarchy ......................................................................... 21
2. Simple Tutorial Skin - Graphics Files ...................................................................... 23
3. Simple Tutorial Skin - skin.xml ................................................................................ 23
4. Simple Tutorial Skin - player.xml ............................................................................ 25
W3 Skinning T utorial - 2.4 Container.....................................30
Layout ........................................................................................................................... 30
W3 Skinning Tutorial - 2.5 Group ..........................................32
1. What is a group? ....................................................................................................... 32
2. Simple Tutorial: Using groups .................................................................................. 32
3. Simple Tutorial: Playback Buttons Group Definition (line 19 -64) .......................... 34
4. Simple Tutorial: Song File Information and Visualization Group Definition (line 65 107) ............................................................................................................................... 36
W3 Skinning Tutorial - 2.6 Relative Position ..........................38
1. What is a relative positioning? .................................................................................. 38
2. RelativePos.xml ........................................................................................................ 39
3. Relative Position 1: defining X&Y Coordinates ...................................................... 39
4. Relative Position 2: Specify the Height and Width .................................................. 42
5. Relative Position 3: RelatX & Negative X Coordinate ............................................ 43
6. Relative Position 4: RelatY & Negative Y Coordinate ............................................ 45
2

7. Relative Position 5: Relatw and RelatH.................................................................... 47

W3 Skinning Tutorial - Part III. Complex Tutorial Skin...........49
Complex Tutorial Skin.................................................................................................. 50
Contact Us..................................................................................................................... 50
W3 Skinning Tutorial - 3.1 Non-Rectangular Players ..............51
1. Introduction............................................................................................................... 51
2. Complex Tutorial Skin - The Break Down ............................................................... 52
3. Player.XML - Part 1: SimpleTutorialXML.xml ....................................................... 53
4. Player.XML - Part 2: Graphic Elements ................................................................... 54
W3 Skinning Tutorial - 3.2 Layer Composition .......................55
1. Layer Composition.................................................................................................... 55
2. Complex Tutorial Skin.............................................................................................. 55
W3 Skinning Tutorial - 3.3 Alpha Channels ............................57
1. Alpha Channel........................................................................................................... 57
2. Complex Tutorial Skin.............................................................................................. 58
W3 Skinning Tutorial - 3.4 Animated Layer............................60
1. Animated Layer ......................................................................................................... 60
2. Complex Tutorial Skin.............................................................................................. 60
W3 Skinning Tutorial - 3.5 Snap Points..................................62
1. Snap Points................................................................................................................ 62
2. Boxor Example ......................................................................................................... 62
3. Default Player Example ............................................................................................ 63
4. XML Example ........................................................................................................... 64
W3 Skinning Tutorial - 3.6 Drawers.......................................65
1. Drawers ..................................................................................................................... 65
2. Complex Tutorial Skin.............................................................................................. 65
W3 MAKI Tutorial - Part IV. Skin Scripting (MAKI) .................70
1. Scripting Engine (MAKI) ......................................................................................... 70
2. MAKI Script Organization........................................................................................ 70
Contact Us ...........................................................................71
MAKI Tutorial - 4.1 Drawer Scripting Example .......................72
1. Scripting .................................................................................................................... 72
2. Compiling a MAKI script ......................................................................................... 73
3. MAKI Script - triangle.m.......................................................................................... 75
MAKI Tutorial - 4.2 Animating Through Script........................78
1. Animating Skins........................................................................................................ 78
2. MAKI Script - anim.m.............................................................................................. 78

Winamp3 Skinning Tutorial

WINAMP3: SKINNING TUTORIAL WEBPAGE

by: Ken Chen

MISSION STATEMENT:
o The goal of this we b page is to describe the skinning process to someone with
graphics background and little programming experience. By creating this tutorial,
we hope to generate excitement and loyalty for Winamp 3.

KEY CONCEPTS TO CONVEY:

o How has the skinning process fun damentally changed from Winamp 2
o How does the graphics engine work: describe the whole process.
o How does the layering work with XML: Alpha channels explained, Basic
grouping explained.
o How to map control to behavior using MAKI scripts within the Winamp system.
o Encourage usage of the forum: links to the discussion

SPECIAL THANKS TO:

o PixelPusher for his contributions.
o Naamloos.

Tutorial Status Report

14-August-2002
Section 2.6 done.
30-july-2002
Clean up Section 2-3.
Section 4.1, 4.2 done.
25-july-2002
Section 3.1-3.6 completed.
19-july-2002
Complex Tutorial Skin completed.
17-july-2002
Section 2.1-2.5 - Simple Tutorial Skin section done.
6-july-2002

 Simple Tutorial Skin completed.

Contact Us
Please email Ken Chen if you have any suggestions.

Skinning FAQ - Frequently Asked Questions

If you have any links that you think would be helpful, plea se email Ken Chen. Thanks!

Frequently Asked Questions

I want to skin, where should i start?

I can't open this WAL file. What's wrong?
I can't find Skin.XML file.
Can I get your tutorial in a single file.
I got a skin idea. Can you make this for me?
Is there a program that I can download that I can use to make a skin?
Is there Winamp3 for other languages?

Skinning FAQ - Answers

I want to skin, where should i start?
I have made a tutorial on how to skin Wina mp3. You can read it here:
http://www.winamp.com/nsdn/winamp3x/skinning/tutorials/.The tutorial is a work in progress.
Please send me feedbacks on it or suggestions on how to make it better
I can't open this WAL file. What's wrong?
Don't try to open WA L file with Notepad or other text editing program. You need to do the
following:
1) Rename your skin file from .WAL extension to .ZIP extension.
2) Use Winzip (http://www.winzip.com) to extract the files from inside.
3) Edit the files

I can't find Skin.XML file.

You need to extract the file from your skin (the WAL file). Here's what you need to do:
1) Rename your skin file from .WAL extension to .ZIP extension.
2) Use Winzip (http://www.winzip.com) to extract the files from inside.
3) Edit the files

Can I get your tutorial in a single file?

The tutorial site is not done yet. We're still adding more sections to it. Once it's complete, we'll
make a downloadable version (probably PDF). Please check back later.

I got a skin idea. Can you make this for me?

Please post this question/Request in the forums. There are people in the community who can help
you. http://forums.winamp.com/forumdisplay.php?s=&forumid=123.
I have made a tutorial on how to skin Winamp3. You can read it here:
http://www.winamp.com/nsdn/winamp3x/skinning/tutorials/.The tutorial is a work in progress.
Please send me feedbacks on it or suggestions on how to make it better.

Is there a program that I can download that I can use to make a

skin?
We currently do not have a skin au thoring tool. I have made a tutorial on how to skin Winamp3.
You can read it here: http://www.winamp.com/nsdn/winamp3x/skinning/tutorials/.The tutorial is
a work in progress. Please send me feedbacks on it or suggestions on how to make it better.

Is there Winamp3 for other languages?

We're working on International Language support for Winamp3. Please check for this feature in
future versions of winamp3.

Winamp3 Skinning Glossary

This page contains definitions for Winamp3 Skinning terminology. You can look up terms that are
foreign to you, thereby understanding and adopting those terms. If you want any term defined,
please email Ken Chen. Thanks!

Frequently Asked Questions

PS:
PSP:
Alpha Channel:

Interlace:

PNG:
XML:
XML Hierarchy:

Root File:
Studio.xnf File:
X&Y Coordinates:
Elements:
Bitmap ID:
Group:
Container:
Component:

Graphics
Short for Photoshop
Short for PaintShop Pro
An alpha channel represents the transparency information on a per -pixel
basis. You can read more here:
http://www.w3.org/pub/WWW/TR/PNG-DataRep.html#DR.Alphachannel
Interlacing produces a "layering effect" so that a grainy version of the
image is sent first, and on subsequent passes is "resolved" into the final
image. This process allows people to get an idea of wha t the image
contains before it is fully loaded.
Short for Portable Network Graphics.
XML
Extensible Mark-up Language. Used as the base for the winamp3
abstraction layer.
The manner in which XML tags may be nested within one ano ther to
form a hierarchical, recursive 'tree' structure, with parent tags enclosing
multiple child tags, which may themselves be parent tags as well. See
XML section for example.
skin.xml, this is where the interaction with xml starts.
the file with all your preferences and last known state.
As pertaining to layout code: position of the element in the layout, X
being distance from the left and Y being Distance from the top.
Winamp3 Terminology
Defining an element within a skin to be used later. Usually linking a
bitmap id to a picture or text or fonts, etc.
The identification given to an element in the elements file and the id
used in layout for said element.
A set of objects tha t can be referred to and manipulated as a whole. It
first must be defined by a <groupdef> tag, then located with a <group>
tag.
A container represents a window. It is an object that holds multiple
related layouts.
In global winamp t erms, a component is an advanced form of plugin,
which can provide nearly any kind of new functionality to the core
system. In skinner's terms, a component is the xml identity which
represents the interface for the actual component (plug -in). Not all
components will necessarily provide an obvious (or any) xml identity
(cnv_dshow.wac, for instance)

Layout:

Gamma:

Gamma controls:
Layer:
MAKI:
M file:
Maki File:
Maki Monkey:
Drawer:

A special kind of group, which shown inside a container. You can define
multiple layouts for a container but only one layout can be visible at a
time. An example is the normal mode and windowshade mode in the
Default skin.
Most common activity for a skinner is to adjust the color of an element
to "just right" to achieve the desired effect. While it is possible to adjust
an element's color using a graphics program, Winamp 3 allows you to
link an element to a gamma control and change them in the preference
menu.
Define a gamma control so the color of that gamma group can be
changed in the preference menu.
A layer is basically an image. Layers can overlay on top of each other. It
is similar to a layer in Adobe Photoshop.
MAKI stands for Make A Killer Interface.
An uncompiled Maki file containing the readable source code
A compiled M file, also known a s a script.
Someone who knows how to write M files well.
A Drawer is an animated layer that is normally hidden but can be shown
when triggered by a user event (often a mouse click).

Part 0. Intro to Winamp3

Why do we need Winamp3?

Winamp3 Components

Why do we need Winamp3?

Limitations of Winamp 2.x

o Skins only consist of static bitmap replacement. The app cannot be deployed
with radically different interfaces or behaviors.
o Plugins cannot publish interfaces to each other, th ereby limiting their ability to
leverage one another.

Winamp 2.x was not built with portability in mind.

Winamp3 Components?
Features of Winamp3:

Skin system:
o XML-based format
o freeform
o scripting
o emulation of Winamp 2.x skins
o on-the-fly bilinear filtered scaling of any winamp piece
o animations, realtime transformations
o alpha transparency
o color correction of any skin
Component architecture:
o allows any kind of plugin you can think of
o components become part of the system and extend it
o components can interoperate without even knowing who they are talking to
o component windows and interfaces are skinnable
o components are built with the same C++ library as the main product for
consistency and to enable developers to quickly create powerful addons
o using a dispatchable interface to make interaction of multiple plugin versions
easier
New audio playback system:
o crossfading
o "dsp" plugins can be stacked
o gapless output (even for cd playback)

10

Playlist:
o XML-based format
o ability to queue up files in playlist out of order (hold down alt)
o Media library
Database:
o caching
o queries
o multiple indexes and views on tables

11

Part I. Winamp 2 to Winamp3

OUTLINE
Transitioning from Winamp 2 and venturing into the new world of Winamp3!

Basically a quick start for Winamp 2 Pros

Purpose
o Explain how has the skinning process fundamentally changed from Winamp 2
o Difference in the engine and philosophy
Highlighting the key areas to consider and emphasizing the new dynamic nature of the
player.
Include/Link to: an overview of new components with the new Winamp3. Maybe doing a
comprehensive list of all the Components (top to bottom) would be helpful.
Maybe even a definition/glossary of all the components along with a detailed outline of
the functionality of each component would also come in handy. Perhaps a FAQ. An
example would be a definition of what the "Thinger" is and what it functionality is and
maybe even to go so far as to what it's limitations are.

12

W3 Skinning Tutorial - 2.1 Start Here!

In section 2, I will show how to make a simple skin and teach you the basic Winamp3 In section
2, I will show how to make a simple skin and teach you the basic Winamp3 terminologies.
Before you start, you will need these items.

Simple Tutorial Skin

We're going to show you how to make a simple skin like the one shown below. Download
the "Simple Tutorial Skin" example
(http://download.nullsoft.com/winamp/skin-dev/SimpleTutorial.wal)

When you save the file, make sure that the type of the file is selected to "All Type" and
NOT "Winzip" filetype. You should save the file into your skin subdirectory in your
Winamp3 directory. For most people, that path is "C: \Program Files \Winamp3\Skins".

13

Text Editing Programs

You can use any text editing program to write XML and MAKI script files.
1) The plain Windows Notepad will do. It is under "Start Menu" => "Programs => "Accessories =>
"Notepad". Here's what it looks like.

2) However, if you intend to do alot of coding rather a quick editing, we recommend you to use
something like EditPlus. EditPlus will automatically color your HTML and XML code. The coloring
makes it easier for you to see your code and find missing closing tags. Here's what it looks like.

14

You can select the type of coloring by going to "Document" menu => "Change File Type..."

A graphics program
We recommend Adobe Photoshop (www.adobe.com) or Paintshop Pro (www.psp.com). Here're
some tutorials (http://forums.winamp.com/showthread.php?s=&threadid=93803) if you're new to
graphics.

15

Contact Us
Please email Ken Chen if you have any suggestion.

16

W3 Skinning Tutorial - 2.2 XML Introduction

In this section, I will give a short introduction to XML. You may ask: what does XML have to do
with Winamp? Well, XML is fully implemented in Winamp. From the skinning files to the playlist,
it's all XML based. I will go over XML basics in this section. If you know XML, go ahead and skip
to the next section.
In this section, I will discuss:
1. So what is XML?
2. XML Hierarchy
3. XML & Winamp

1. So what is XML?

XML stands for eXtensible Markup Language (XML). You hear about XML everywhere. We're
going to give you a quick and dirty guide to XML and its relevance to Winamp. XML is just lik e
HTML. If you know HTML, you can pick up XML very quickly. So don't be afraid.
HTML and XML are from the same family of what is called SGML (Standard Generalized Markup
Language). SGML was invented as a text -based language that can be used to mark up dat a that is, add metadata - in a way which is self describing. What does this mean? Basically SGML
is a way for programmers to transfer and display information. The best known application of
SGML is HyperText Markup Language, or HTML. HTML is a universal m arkup language for the
display of information and the linking of different pieces of information. The idea was that any
HTML document (or web page ) would be presentable in any application that was capable
understanding HTML (namely a web browser).
Although HTML has been incredibly successful, it's also limited in its scope: it is only intended for
displaying documents in a browser. It is not particularly useful as a medium to convey information
to other programs. Don't understand? Here let me give you an e xample.
For example, if I want to tell everyone my name, there are many ways I can do this:
a) I can create a text file on a computer that look like this. When I send you this text file, you can
read it or write a program to parse it. By reading "Ken Che n" in the text file, you can guess that
it's my name. But then again, are you sure? It's not really clear, right? Lets look at the next
example.

Ken Chen
b) For the web, I can create an HTML file like this. I can put it on a web site and you can see the
page in your browser. Once again, by just reading "Ken Chen" you're not really sure that it's my
name.

<HTML>
<HEAD><TITLE>Name</TITLE></HEAD>
<BODY>
<P>Ken Chen</P>
17

</BODY>
</HTML>
c) XML is a standard for conveying information. I might create an XML file like this. Looking at this
file, you can see that it looks very much like an HTML file. The style is very similar. The difference
is that in XML, you can design or come up with any tag you want to convey the information you
want. Reading this simple example, you can tell that my first name is Ken and my last name is
Chen.

<Name>
<First>Ken</First>
<Last>Chen</Last>
</Name>
From this simple example you can see why markup language like SGML and XML are called self describing. Looking at the data, you can easily tell that this is information about a <name> and
you can see that there is data called <first> and another data called <last>.
d) You could write a shorter version of the previous XML by using element attributes. l ike so:

<Name First="Ken" Last="Chen" />

and it could equate to the one in C, if the Name element had those attributes (first and last). The
reason for this is that you get tired of typing open and closing tags. Once you open a tag, you can
have attributes for that tag. Many Winamp3 skin XML files are in this style. Here's an example
from the Default skin.

<button
id="Previous"
action="PREV"
x="0" y="0"
image="player.button.previous"
downImage="player.button.previous.pressed"
tooltip="Previous"
/>

2. XML Hierarchy
The beauty of XML is that you can design whatever format you want to describe your data. The
key is that you follow the XML hierarchy (we'll describe in the next section. Other than that, make
sure you close the tag when you one. (ie: make sure you have </name> if you open a <name>
tag.
XML has a hierarchy that you need to follow. This is much like the HTML code where you embed

18

a tag within a tag. By doing that, you're creating another level in the hierarchy. Mak e sure you
close your tags correctly. Check out this example.

<Winamp Employee>
<Name>
<First>Ken</First>
<Last>Chen</Last>
</Name>
<Email>[email protected]</Email>
<Location>San Francisco, CA</Location>
</Winamp Employee>

In this example, we have <Name>, <Email> and <Location> as level 1 tags. Within the <Name>
tag, we have two level 2 tags: <First> and <Last>.

3. XML & Winamp

XML is basically a way to store data. Now we've shown you what XML is, you may ask: what
does that have to do with Winamp? Well, XML is fully implemented in Winamp. From the skinning
files to the playlist, it's all XML based. I've gone over the basics of XML. I'll go over Winamp XML
elements and dissect apart a simple skin example in the next section.

19

W3 Skinning Tutorial - 2.2 XML Introduction

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.
2.
3.
4.

Winamp3 Skin Directory Hierarchy

Simple Tutorial Skin - Graphics Files
Simple Tutorial Skin - Skin.xml
Simple Tutorial Skin - Player.xml

20

1. Winamp3 Skin Directory Hierarchy

a) Skin Hierarchy
Before you start playing with a skin, you hav e to know where everything is. Above is a picture of
the Winamp3 directory. If you open that directory ("C: \Program Files \Winamp3") with Windows
Explorer, it should 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.

21

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 t he skin. From that
file, all the fun starts. =) I will dissect that file later on.
The "Player" directory contains all the graphics file for the skin. The files are in .PNG (Portable
Network Graphics) format. The "XML" directory is usually where all the X ML 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 XM L file and encounters that tag, it grabs the file specified within that
tag and paste whatever code that 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.

22

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 the m 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\Winamp3\Skins\Simple Tutorial" directory. The content of that file is posted above. I'll go
over all the parts. I have listed line number on the left and the code on the right. You can open
your version and follow along.

23

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 only 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 wi ll 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 use d to track compatibility. We
will keep compatibility as long as possible. But sometimes when we introduce a new functionality
and change an existing one, compatibility 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 anyways for fun.

24

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)

25

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, "blueplayer.button.previous", to a graphics component in "player/blue/blue-previous.png" file. That
bitmap id is also linked t o 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 differe nt 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. Fo r 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)

26

Sometime a group of objects naturally belong together or are loc ated 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.

27

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 i nside 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 sim ilar to a

28

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 an d, within the layout, we're using the groups we defined earlier.
Container, layout and group are important concept and we will go more in depth in subsequent
sections. Read on....

29

W3 Skinning Tutorial - 2.4 Container

What is a container?
A container is a top level object and it basically represents a window. Nothing holds a container. It
is an object that holds multiple related layouts. Each layout represents an appearance for that
window. You can design different layouts for each window but only o ne can be visible at a time.

Layout
What is a layout?
A layout is a special kind of group, which shown inside a container. Each layout represents an
appearance for that window. Layouts give you the ability to design different looks for the same
container (or window). However, only one layout can be visible at a time. You must toggle among
layouts you defined. An example is the normal mode and windowshade mode in the Default skin.

The top image is using normal layout and the bottom is using t he windowshade layout.

30

Lets look at the Simple Tutorial xml code for layout:

31

W3 Skinning Tutorial - 2.5 Group

1. What is a group?
2. Simple Tutorial: Using groups
3. Simple Tutorial: Playback Buttons Group Definition
4. Simple Tutorial: Song File Information and Visualization Group Definition

1. What is a group?
A group is a set of objects that can be referred to and manipulated as a whole. First must defined
by a <groupdef> tag, then located with a <group> tag. Group is an important c oncept to
understand because a group is such a versatile object.

2. Simple Tutorial: Using groups

Let go back to our "Simple Tutorial" example. As you recall, we have two groups defined:
"player.normal.playbuttons" and "play.normal".

Lets take a look at the code: (player.xml)

32

If we change line 113 and 114: change the x&y coordinates of the group objects, their positions
are reversed. This is a simple change and much more convenient than changing the position of
each element independently.

33

3. Simple Tutorial: Playback Buttons Group Definition (line 19-64)

34

Line 19-64 is a group definition of the playback buttons. This section contains only the definition
of the group or, in another word, it defines which objects are in th e group. Once the group is
defined, you can use it later as we will see later. Lets go over the elements inside the group.

35

4. Simple Tutorial: 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.

36

37

W3 Skinning Tutorial - 2.6 Relative Position

1. What is a relative positioning?
2. RelativePos.xml
3. Relative Position 1: defining X&Y Coordinates
4. Relative Position 2: Specify the Height and Width
5. Relative Position 3: Negative X Coordinate
6. Relative Position 4: Negative Y Coordinate
7. Relative Position 5: Relatw and RelatH

1. What is a relative positioning?

A. Introduction
Built on top of the WASABI platform, Winamp3 skinning offers unparalleled flexibility in element
placement. You're no longer restri cted to specifying X&Y coordinates for an element. Instead, you
can define the position of the element relative to your component. When the component resizes,
the element will stretch or move with the component. This flexibility frees the skin designer fro m
the hassel of retooling or redrawing the graphic assets over and over again to different size and
width. Winamp will do that for you. =)
B. Add relativepos.xml to your SimpleTutorial
For this section, I have made another XML file called "relativepos.xml" that you need to include
in your SimpleTutorial skin. Download the relativepos.xml here. (Please right -click on the link and
choose 'Save As...' or 'Save Link Target As...')
http://www.winamp.com/nsdn/winamp3x/skinning/tutorials/relativepos.xml
Place this file in the same directory as your SimpleTutorial skin directory. For most people, the
path is "C: \Program Files \Winamp3\Skins\SimpleTutorial". Add this line to your Skin.xml in
SimpleTutorial:
This is what your skin.xml should look like after the c hange:

38

2. RelativePos.xml

Relativepos.xml uses elements from the SimpleTutorial skin. I am using the "blue -vis-layer.png"
and "red-vis-layer.png" in the Player directory.

3. Relative Position 1: defining X&Y Coordinates

A. register_autopopup="1"
Before we delve into the code, I want to go over one feature. Take a look at this tag:
When you add this tag to a groupdef, Winamp3 automatically wrap a
container and layout around it and allow you to see the group in a separat e window. This is
particularly useful when you want to test the behavior of that group separate from everything else.
To open that window, right click on the Main Player to bring up the menu. Go to the "Windows"
submenu and you'll see the extra windows rel ativepos.xml has created. Open them up and try
them out.

39

B. Defining X&Y Coordinates

Line 11-19 defines a group with a "blue -vis" layer at the coordinate of (20,30). This is probably
what you've been doing all along. As you can see, that the blue -vis layer's location doesn't
change if you resize the window. The position is fixed.

*Small size window

40

*Large size window; Blue-vis layer position did not change

I encourage you to play with this XML file. If you change the X&Y coordinates on line 14 to (-20, 30), your blue-vis layer will disappear. The reason is that the coordinate specified will be outside
the context of your component window and therefore will not be rendered.

*Negative X&Y Coordinates: (-20, -30)

41

4. Relative Position 2: Specify the Height and Width

In group 2, we're defining the height and width of the blus -vis layer that is larger than the image.
When you do that, Winamp will stretch the image to that size. Likewise, if you specify height or
width that is smaller than the image, Winamp will shrink the image to fit to that size.

*RPOS1 window: Height and Width not specified

*RPOS2 window: Height and Width defined

42

5. Relative Position 3: RelatX & Negative X Coordinate

Line 30-39 defines a group wi th a "blue-vis" layer at the coordinate of ( -120,30). Notice that we
have an extra line on line 34: "relatx=1". By setting relatx to 1, you're telling Winamp to start the x coordinate from the right edge of the window. Note that the X -Coordinate should be negative;
otherwise the blue-vis layer will not show up.
This is a convenient feature if you want an element stick to a specific distance relative to the right
edge of the window. Notice that when I resize the window, the blue -vis layer stays fixed distan ce
relative to the right edge of the window.

*RPOS3 window with relatx=1

43

6. Relative Position 4: RelatY & Negative Y Coordinate

Line 40-49 defines a group with a "blue -vis" layer at the coordinate of (20, -80). Notice theline on
line 44: "relaty=1". By setting relaty to 1, you're telling Winamp to start the y -coordinate from the
bottom edge of the window. Note that the Y -Coordinate should be negative; otherwise the blue vis layer will not show up.
This is a convenient feature if you want an element stick to a specific distance relative to the
bottom edge of the window. Notice that when I resize the window, the blue -vis layer stays fixed
distance relative to the bottom edge of the window.

*RPOS4 window with relaty=1

45

*RPOS4 window with relaty=1: window resized

*RPOS4 window with relaty=1: coordinate (20,50)

46

7. Relative Position 5: Relatw and RelatH

Line 50-72 demonstrate the use of relath and relatw. From the beginning of this section we know
that by defining height and width different from the original image size, Winamp3 will
automatically stretch or shrink the image to fit that size constraint. What is powerful (and
awesome) about Winamp3 is that you can also tell Winamp3 to adjust the height and width of an
element with respect to the right and bottom edge of the window. This is accomplished through
"relath" and "relatw".
In our example, we defined a b lue-vis group (lines 52 -60) and a red -vis group that encompasses
the blue-vis group (lines 63 -72). The blue-vis group is defined with no preset x, y, h or w because
we will define them on line 71.
The magic happens on line 71. With relath set to 1 and re latw set to 1, we're telling Winamp3 to
stretch or shrink the blue -vis layer so that it is 50 pixels away from the right and bottom edge of
the window. The blue -vis layer is stretched and the distance is maintained as I expanded the size
of the window.

47

*RPOS5 window with relath=1 and relatw=1

*RPOS5 window with relath=1 and relatw=1; window resized; Blue-vis layer stretched

48