The VideoLAN Forums

.:: JoeTheZombie's VLC Skin Tutorial ::.


Basics : XML (And no, it's not a football league or T-shirt size)

At the heart of a custom skin for VLC is the theme.xml file. This file contains all the necessary tags to define a skin. Since it is an XML file, we have to (oddly enough) understand how XML files work before we can create our own. There are many XML primers on the Interwebs, so we won't get into too much detail here; we'll only cover enough to get us skinning. For those adventuresome enough to really tackle the XML specifications, here are some links to other XML resources:

• An XML primer - A very basic easy to understand guide (necessary reading!)
• XML Tutorial - Take XML school from w3schools.com (a somewhat complex guide)
• The XML FAQ - The FAQ on XML
• Extensible Markup Language (XML) 1.0 (Fourth Edition) - For the truly brave!

Out of those links, for our purposes only the first one, An XML primer, is necessary reading and should provide enough explanation to get us started. So without any further delay, let's jump right into our skin's XML file.


Step 1 : <!DOCTYPE>

First off, let's create a directory to hold our skin. C:\tskin\
Using your favorite text editor, create a text file in this directory called theme.xml. Be careful not to accidentally create a theme.xml.txt file. This is especially problematic if using Windows, and Windows is set to hide file extensions. Some text editors try to automatically add .txt extension to our filename, so be warned. And now we can enter the first line of our skin: Simply put, this tells us what tags our theme.xml file can contain and is the exact same line for all VLC skins. Basically it is saying this document is a public theme document and can only contain tags as defined in VLC's skin.dtd. You can actually look at the DTD here. It contains all the building blocks we can use to make our skin. It should be noted that the <!DOCTYPE> must always be the very first line of the document. When VLC loads a skin, it looks at this line to make sure the file really is a skin file.


Step 2 : <Theme>

Now, enter these next two lines: The first line is saying we are going to create a new theme based on skins version 2. The second line says we are done creating our theme. You can think of them as the covers on a book. All of our tags for creating a new skin will need to be inserted between these two lines, to keep them in the "book". The <Theme> tag also supports several other attributes which you can read about right here. The only required attribute is version, but we can use the other attributes to change other aspects of our skin. For instance, if we look at the magnet attribute we read

magnet

Allows to select the range of action (in pixels) of magnetism with borders of the screen: when the distance between the border of the screen and an anchor of a window is less than this value, the window will stick to the border. 0 disables magnetism with the screen borders.

Default value: 15

This tells us that by default, if a skin gets within 15 pixels of the border of the screen, the window will snap to the border. Well, what if we don't want our skin to snap to the borders of the screen? Well, we can change the <Theme> tag to: Now our <Theme> tag is specifying that it is a version 2 skin, and also our skin won't snap to the edges of the screen when we get close. However, I like that snap to functionality, so for this tutorial, we won't alter that attribute from the default. Instead, how about we cause our skin to become slightly transparent when dragging the window around the desktop. Can you spot the attribute that will help us do this? Look at the <Theme> definition one more time and go over each of the attributes. If you guessed "movealpha" as the correct attribute, then give yourself a pat on the back. But now can you correctly alter the <Theme> tag? Now our <Theme> tag is specifying that it is a version 2 skin, and also our skin will become slightly transparent (255 = solid, 0 = invisible) when we are moving the interface around. You also probably noticed the alpha attribute. If you wanted your skin to always be slightly transparent, you could define this attribute as well like this: Now our <Theme> tag is specifying that it is a version 2 skin, it will be slightly transparent on the desktop, and will be even more transparent when we are moving the interface around. Of course, we haven't yet created our interface, so there is no way to test it...

For reference, here are all the attributes we can use with <Theme>, with required attributes highlighted. You can find out more about each attribute by referencing the <Theme> section of the skinning guide, just as we did before.

• version
• tooltipfont
• magnet
• alpha
• movealpha

Step 3 : <ThemeInfo>

Now enter this next line. Remember, it needs to go in between the covers of our "book": If we look at the <ThemeInfo> section of the skinning guide, we see that <ThemeInfo> has the following attributes:

• name
• author
• email
• webpage

None of these attributes are marked as required, so we can choose which ones we want to include. Currently, VLC doesn't use any of the <ThemeInfo> data. It's only purpose would be for people looking at the .xml file to see who created it, and how to contact them. Future versions of VLC may use this data in a "about skin" type dialog.

One final note about <ThemeInfo> is that it does not contain other tags, so it does not have a closing partner. Instead, we just include the final forward slash at the end of the line (before the >) as to tell us we are done with <ThemeInfo>.


Step 4 : <Font>
<Font> is used to select which TrueType (.ttf) or OpenType (.otf) font we want to use to present text. If we look at the <Font> section of the skinning guide, we see it requires two attributes, with a third (size) having a default value of 12:

• id
• file
• size

The first thing we must do is copy the actual font file (.ttf or .otf) to our directory where we are creating the skin. In this case, C:\tskin\. Here I'm using the publicly available Lacuna font. It's file name is LACURG__.TTF which I have copied to our C;\tskin\ directory. Once there, our skin can access it: Our first attribute is id. This is what we are going to name our font/size pair. Our second attribute is file. This is the filename of our .ttf or .otf font file. Finally, the size attribute is used to determine what size the font will be. In this case, 11. Now, look carefully at the <Font> section of the skinning guide. You'll notice the size attribute is not a required attribute. What happens if we don't include it in our definition like this?: Since we didn't include it, the default size of 12 will be used. Even though we named our font with the id of "lacuna-11", it would now be a size 12 font because we didn't include the size attribute, and thus the default will be used.

If you wish to use two different fonts or font sizes in your skin, we need to have multiple <Font> lines. An import note is that no two ids can be the same, so when we choose which fonts to use, make sure you give them different ids. Here we'll be using two sizes of the same font. The first font we've named lacuna-small and will be a size 10 font. The second font we've named lacuna-big and will be a size 11 font.


Summary

In this section of the guide, we've learned how to start creating a skin. We haven't actually created an interface yet, but have our directory and theme.xml file created, and any fonts copied to our skin directory. We've also made sure that VLC will know this is a theme file (using the <!DOCTYPE> tag). At this stage, our directory (C:\tskin\) should contain two files:

theme.xml
LACURG__.TTF

Our theme.xml file should look like: { more to come... }

{ reserved }

{ reserved }

{ reserved }

{ reserved }

I don't have the time to read this all right now, but I'm sure this is going to be very useful. Thanks for this. Oh, ah... you should be warned too. I'm kinda slow to understanding certain things and I don't fully understand the technobabble, so I'll probably be asking a lot of dumb questions, more then the usual.

I'm almost sure I've seen "XML" advertised on TV somewhere. "NEW Gatorade XML. Drink Big!"

@JoeTheZombie: Thanks a lot for this beginning. If you need more posts, just PM-me and I'll clean this thread.
What is the future licence of this Tutorial ?

Hi,

Nice tutorial.

Currently, VLC doesn't use any of the <ThemeInfo> data. It's only purpose would be for people looking at the .xml file to see who created it, and how to contact them. Future versions of VLC may use this data in a "about skin" type dialog.

This isn't entirely true. The theme info data is printed in the VLC messages log (as an Info message, so that you always see it if you launch VLC from a terminal window on everything but Windows).

Good start of a tutorial. When is Part 2 coming out?

Part 2 should be out in a couple of weeks. It's actually all written, with the supporting files, but needs a bit of refinement.

Another problem, is my tutorial references http://www.videolan.org/vlc/skins2-create.html , which is currently not working. Until that is fixed, there's not much I can do.

could u put this on the wiki

Nice tutorial. When next?

Yeah i did all of this part, i wait for the next instruction !!!

Thanks for the tutorial !!!

Well, until VLC gets skinning support back for Windows versions sometime soon, I'm afraid I'm not going to put any more time into this.

Well, until VLC gets skinning support back for Windows versions sometime soon, I'm afraid I'm not going to put any more time into this.

That is arriving for the 1.0, if everything works correctly.

I have tried to use Windowblinds a few times and have to keep un-installing it. I has a habit of messing up Video LAN and a couple of other things on my PC.

I have a tech ticket set up with the support people there but they are not the most helpful. I had VLC working for a while with a really great skin, but then the buttons stopped working. So I had to go and unload Windowblinds once again. If the skinning of VLC and Windowblinds could work out the problems there would be a large number of skins to use.

cool tnx