Skinning tutorial part 2

From TrillWiki

[edit] Part 2 - The File Structure

Every Trillian skin has to have files. A lot of these files will obviously differ from skin to skin, but there are some core files. I have uploaded a set of files, which can be downloaded here.

[edit] Trillian.xml

The most important file. This file has to be present for the skin to work. This is where everything has to tie into. All code must be linked to it in some way. If you fire up the Trillian.xml file included in the zip you will see a fair amount of stuff. Don't worry though, it's all fairly straightforward.

Ignore the first line, the second line is the first thing to look at:

<!DOCTYPE test SYSTEM "System/trillian.dtd">

This tell's trillian where to find the DTD file for this skin. The dtd file lets us make references to other files, rather than having it all in the same file. Back in the days of 0.63x skinning, there were 6 files, and all the code had to fit in these files, causing much repetition and large files. Then it was discovered, that using dtd files, one could move chunks of code out of the main files and re-use it. More on dtd files in a bit.

Next bit of interest is:

<skindesc

name="SKIN NAME"

author="YOUR NAME"

email="YOUR EMAIL ADDRESS" />

This re-occurs in all your files, so it is advisable to copy/paste it when modified. It basically just lets you stick in some details about you and your skin, so people viewing your code can see who wrote it.

The next line is also VERY useful:

This is a comment, and is useful to help you keep track of what things are, and what they do. It helps you remember which controls are which, and what some icontrols do, if the name doesn't seem clear to you. You can use them, as I have, to help others read your code, and hopefully understand it.

You can add a comment anywhere in your code. To start a comment, you type

Comments are your friend, especially when starting out - if you think you might forget what a piece of code does: comment it.

Comments are also useful to mask out pieces of code to find problems, without deleting the code.

The next bit is part of what helps us minimize typing the same stuff over and over again, and helps us store code in other files, to make it easier to find stuff.

&files;

This tells trillian to insert the "files" replacement text in the code. To put it another way, any time Trillian sees &files; it goes to the dtd file (more on this in a sec), and reads what "files" represents (in this case, it inserts the text from XML/Misc/files.ext). It then copies all of that text, and puts it where &files; used to be.

This is a really confusing example, as I used the "files" file, but it is the same theory for the "message" file etc.

So, basically, if you had a bit of code that looked like:

And you wanted to have it twice, instead of writing:

You could write

&colour;

Obviously, it is more useful for larger pieces of code, such as windows, but hopefully you get the idea. As I mentioned earlier, the place where these &alias; type references are found are in the dtd file. At the top, I said that Trillian.xml was told where to find the dtd file using this line:

<!DOCTYPE test SYSTEM "System/trillian.dtd">

This is so it knows where to look up these aliases (known as "Entities") to see what they mean. Open up the dtd file found in system

Ignore all the <!ELEMENT> stuff at the top, this is not what we change - this has to be here, and is the same for all skins - don't change it! (Howver, if you link into STIXE code, this information will be included in the STIXE\trillian.dtd, so you don't have to include it again... but that's outside the scope of this tutorial.

The bits we want are at the bottom. As you can see, you can use comments here too. The references are contained in these lines:

<!ENTITY files SYSTEM "XML/Misc/files.ext">

The !ENTITY tells Trillian it's replacement text. The bit that says 'files' is the alias - this is what you will put between the & and the ; eg &files;.

The bit in the quotation marks is the path to the file you are referencing - relative to Trillian.xml. So even if your message.xml file AND your trillian.dtd file are in the same directory (eg "pies"), then you will need to put this path as "pies/message.xml" and not just "message.xml".

SYSTEM stays as is -- SYSTEM tells the parser that the replacement text is read from a (system) file. If you just want to insert a string and don't really want to copy a file, you can leave out the SYSTEM. The bit in the quotes would then be the replacement text itself and not a filename.

This is how we split our code up into the files we want. You can have as many or as few of these files as you want, and you can put whatever you want in them. The names you give them do not matter, as long as they don't conflict with other names.

So to go back to our earlier example, to add &colour; we need to create our colour.xml file. In it we add the line

that is all that is contained in the file.

In the dtd file we add the line:

<!ENTITY colour SYSTEM "XML/colours.xml">

Then we can use the &colour; reference in our skin.

3 final things to note on this:

the files we reference can be called anything, and require no set extension - for example you could call your file colours.idontreallycare if you wanted to, but for ease of coding, the recommended extension is either .ext or .xml. (Well, really ".xml" if you want to stick to standards, but a few skinners use ".ext")
We don't actually need the colours.xml file ;)
The reference aliases we set up can be used from any file in the skin, even other files linked with a reference, not just from Trillian.xml. Eg message.xml can call &rect;. Also, they can be used as many times as you like.

[edit] Desc.txt

This is the other major file of note for this section. If you open it up you will see:

NAME OF SKIN GOES HERE

DESCRIPTION ON SKIN GOES HERE

Graphics/splash.bmp

200

700

As you may have guessed, this is the file that tells Trillian info about the skin to display in the Skin Chooser.

As suggested, the first two lines contain the name of the skin and a brief description.

Leave the third line. (It tells Trillian how many images are in the preview if you want to make an animated one.)

And the fourth line, tells trillian where to find a bmp file as a preview of the skin to display in the skin chooser. The image should be 320x240.

The next line is for animating the splash screen, but we won't go into that now.

The final line, 700, tells Trillian that the skin is compatible with Trillian 0.7x and above.

(If you were to make an animated preview, you would increase the number in line 3 and copy lines 4 and 5 for each image. the number in line 5 tells Trillian how long - in milliseconds - to display the image.)

Optionally, there can be another line at the end of desc.txt that tells Trillian where to find a configuration utility, such as /stixe advanced settings (just write 'stixe' there) or The Configurator.

That concludes part 2, part 3 will look at creating your first window - the transfer window!

Back: Part 1 - Introduction

Next: Part 3 - Building A Window

Retrieved from "http://developer.ceruleanstudios.com/index.php/Skinning_tutorial_part_2"

Category: DREADNOUGHT's Skinning Tutorial