(WinCDG Classic, WinCDG-Pro 1, Pro 2 and Pro 2.5)

Note: Not applicable to WinCDG Classic 2!

Modified: July 25/2002

Introduction

Skins let you totally change the look of the program to almost anything you want. Skins are replacement images for all the buttons text and digits in the window.

This guide covers skins for all WinCDG products (Except WinCDG Classic 2), however, please note that not all features are available on all products. When a feature requires a specific version it will be marked:

• [Pro] - Works on WinCDG Pro 1 or higher
• [Pro 2] - Works on WinCDG Pro 2 or higher
• [Pro 2.5] - Works on WinCDG Pro 2.5 or higher

How to make your own skin

A skin consists of two or three files:

1. The "skin" file. A text file that defines the placement of elements of the skin.
2. A "main" bitmap that represents the graphical "up" and "off" state of all the elements.
3. An optional "resource" bitmap that contains the "down" or "on" state of each element PLUS other images, such as digits.

A basic skin only needs the first two files, however it will have limited user feedback (ie: when you click on a button the image does not change) and you are limited to standard text. By including the optional resource bitmap you can define the look of each button when depressed plus you can define graphic digits for the time, track number, or clock.

You are not limited to a rectangular form. In the skin file you can also define an irregular-shaped outline region for your skin or specify a "transparent colour" for the main bitmap.

Tip: Look at the "default.skin" file. It is an example of an advanced skin using just almost all of the different skin features (except regions). First, think about the layout of your skin. Where will the elements go? How big will the buttons be? Do you want your own digits or are standard text fonts okay?

There are a few different elements that will make up your skin. All elements are optional. If you don't define them they will not appear.

These are the different types of elements available:

The elements are placed in the program "window" which we will refer to as the "form". The background (static graphics that do not change), and buttons will be drawn on the main form. Other elements (such as text) will be placed on the form in the position you specify. Text placed on the form will have no background of its own (IE: your graphics will show through).

You can use just about any graphics editor to create the bitmap(s). Bitmaps can be saved in either BMP, GIF, or JPEG format and can contain from 16 to 16 million colours. Keep in mind that if you try to display 16 million colours on a 256 colour or less screen mode, Windows95 will adjust the image and it may not appear as you intended! Also, note that JPEG images are good for life-like images with lots of colour but are not good for text or cartoon-like images. For these type images use GIF.

The Main Bitmap

The main bitmap is the image that appears on your form and gives the skin it's look. This is where you can draw whatever you want and it will appear as-is on the form.

Draw all the buttons in their "up" state. You could create buttons with labels on them or you could put the label beside the button. If all your buttons were the same size and you put the labels on the form instead of inside the button you could save some work since you would only need to draw one "down" button on the resource bitmap. If each button is labeled you will need to draw the "down" version of each button in the resource bitmap. Buttons can be any shape you want. They do not have to be rectangular, however the definition for the button area will be rectangular so you need to be careful how the buttons are placed so that the area doesn't overlap another button. Overlapping buttons are possible but you would need to do some creative drawing in the resource bitmap...

The Resource Bitmap

The "resource" bitmap contains all the buttons in their "down" state. An easy way to make the resource bitmap is to copy the main bitmap then modify the buttons to look depressed. A common technique with "standard" buttons is to reverse the highlighting. IE, in the "up" button the top and left are light coloured, whereas the bottom and right are dark. When depressed those are reversed so that the top and left are now dark and the others are light. Another common technique is to make the button darker and to slightly offset the label down and to the right to give the appearance of being pushed in.

The resource bitmap does not need to be the same size as the main bitmap. If you have a large-sized form with large areas and/or you need to create room for the digital display digits then you might need to re-arrange the "down" buttons on the resource form. If you do this you will need to specify the new coordinates in the skin file.

To create the digital display digits, draw each digit in a single line like this:

Make sure ALL characters are all exactly the same width. The "space" character can be blank, a "zero", or the segments that make up the digit in an "unlit" state. The "." and ":" are special cases. Even though they take the same width in the bitmap as the others they can be thinner than the other digits by specifying their width (w2) in the parameter list (they will need to be aligned to the left).

The Skin file

The skin file is a text file that ties everything together. In the skin file you define everything that makes the skin work. You define the size of the form in it's normal, expanded, and small modes. You define the location of the buttons and text, their sizes, colour, and font etc. You define where in the resource bitmap the digital digits are located and what size they are. You can also define all the points that make up the outline of the form if you choose to make your skin non-rectangular.

The format:

The first FIVE lines must be in the following format. NO extra comments or blank lines can appear above them!

The rest of the file defines the elements in the skin. If you wish to add comments to the file put a semi-colon followed by a comma (";,") at the beginning of the line. Everything after the comma upto the end of the line will be ignored.

You can include skin comments, which are displayed in the "info" tab of the preferences screen by starting the line(s) with "/," characters. Eg:

/, This is a skin comment
/, This is another comment

Comments will be appended one after another and displayed exactly as entered on the line.

Elements

Different elements are defined using a unique identifier consisting of a letter and number (for example: B12). Following the identifier are one or more parameters depending on the type of element.

The following are the element codes:

The Following are control codes:

The following are possible parameters:

NOTE: All coordinates and dimensions are in PIXELS!

If you DO NOT specify an element it will NOT appear. If you set the width and/or height of an element to zero it will also not appear.

Element Reference

The following describes the format of the parameters for each element and the function of each element:

(B) Buttons

Format: Bnn,x,y,w,h,x2,y2,key,tooltip

(K) Link Buttons

These buttons perform special functions when pressed. The "Skin Link" buttons let you load a specific named skin. They can be used when you want to switch between your favorite skins or to have elements appear to move around etc. The "Web Link" buttons take you to the specified URL using your default browser.

Format: Knn,x,y,w,h,x2,y2,key,tooltip,link

link = The name of the skin or URL to load
(Note: Skin links should include the extension but not the path!)

If you link to a "full-screen" skin and you have created a skin for each screen resolution you may use the format "name*" for the skinname. The current screen width will be substituted into the name when the button is clicked. Example:

Element definition: K01,.......,"deluxe*"

...and so on

Make sure you have a skin that matches your screen resolution otherwise you will get an error message.

(L) Labels

These are text labels that have a transparent background so that the graphics on the form show through.

Format: Lnn,x,y,w,h,r,g,b,pt,font,tooltip

* = Not implemented yet [NI]

(D) Digital Displays

These are digital displays using graphics digits/letters of any size.

Format: Dnn,x,y,x2,y2,w,h,w2,g,s,f,ToolTip

Notes:

• w,h are for a SINGLE digit
  
• w2 is the width of the period and colon.
  
• g is the source bitmap format:
  
  • 0=Numeric Only (0123456789 .:)
    (the space can be blank, a "zero", or "unlit" form of the digit) (cannot be used for element D6!)
  • 1=Alphanumeric (Full ascii)
  • 2=Alphanumeric (Uppercase ascii)
  • 3=WinAmp Standard (Uppercase ascii)
• s is additional spacing for destination
• f is the display format number (0 to 8):
  
  • 0 = "99:99" (elapsed time)
  • 1 to 7 = number of digits
  • 8 = "HH:MM" (time)
  • 9 or higher = length of track title

(S) Sliders / Graphic Indicator

These are analog sliders that can be dragged to any position and Graphic Indicators whos width or height changes proportionally in sync with another slider.

Format: Snn,x,y,w,h,x2,y2,w2,h2,tooltip

(I) Indicator Lights

Format: Inn,x,y,w,h,r,g,b,shape,comment

(X) Other Elements

Format: Xnn,x,y,w,h,r,g,b,pt,font,tooltip

Import skins

Import skins are standard skins with additional commands to read bitmap files and assemble them into a WinCDG-compatible format. To indicate an import skin, line 4 of the skin definition file must start with a "*".

Format: *,directory,filter,defaultfile

• The directory is the default location for importing.
• The filter determines the type(s) of files to show.
• The defaultfile is the name of the main file.

There are three temporary bitmaps (0 to 2) that you can use:

• 0 - Corresponds to the main bitmap
• 1 - Corresponds to the resource bitmap
• 2 - Temp bitmap. Used as the source for blitting to 0 or 1.

The following extra commands are available:

The "R" command reads in a bitmap from the import path. You can use the "?" commnad to test if the read command was successful (1=yes,0=no). The command can be used to skip other commands/elements that depend on the bitmap existing (ie: blit commands and buttons). Example:

R1,playlist.bmp	;read the playlist bitmap file
?0,skip		;if it doesn't exist (0=false) 
		;jump to the line labelled "skip"
...		;do whatever you need here
		;(ie: blit and define elements)
:skip		;this is the label it jumps to if false
...		;continue normal processing

Note: The "?" command only jumps FORWARD. Labels do not have to be unique.

How to Make a Non-Rectangular Skin

Method 1: Bitmap with "transparent" colour

For the main bitmap pick a colour, then draw any area to become transparent in that color. Make sure you do not use that color anywhere in the bitmap that you want to be visible. In the skin use the letter "O" command to specify the transparent colour like this:

O,r,g,b
Where r,g,b are the red/green/blue values of the transparent colour

Note: This method is good for very complex shapes, but slows down with large bitmap files.

Method 2: Vector Region Co-ordinates

If you do not specify Region coordinates in the skin file your main form will be rectangular. To make a non-rectangular form you must define all the points that make up the bounding area (region) or areas. Points are connected by straight lines, so to make a circular section you will need to specify many points. If you specify multiple regions that overlap a "cutout" (or hole) will be produced.

For Single Regions you must first specify the number of points in the region, like this:

Nnn
Where: nn is the total number of points

For Multiple Regions you must specify the number of points in total, the number of regions and the number of points in EACH region, like this:

Mnn,xx,R1,R2...Rxx
Where:	- nn is the total number of points
- xx is the number of regions
- R1 to Rxx are the number of points in each region

Then, you must follow with the appropriate number of coordinate points in a list like this:

Px,y
Px,y
Px,y
etc...

Coordinates are specified in pixels. If you list extra coordinates they will be ignored. If you list fewer coordinates the entire region(s) will be ignored!

Note: Your form should be bigger than the entire region, otherwise points outside the form rectangle will not produce the desired effect (the edge will be straight where the form ends). This could also be a good thing if used properly (for example with the "toggle large" button).

In a Single region skin the last point will automatically be joined to the first point. In multiple region skins you must join them yourself in EACH region!

Note: This method is good for simple shapes or large skins

Ending the skin

The skin file must end with the single line: END

Linking Skins

There may be a situation where you need to "link" skins together to achieve the desired look for your skin.

Example 1:

You want to have a simple skin with minimal controls but sometimes need the ability to use the other controls, which you want to be located to the right. You could use the "toggle large" button to make the window wider but what if you had the power button in the "title bar" at the top right of the normal window? The button would now be in the middle of the titlebar and wouldn't look right. What you need to do is move the power button back to the top right, which means you need new coordinates. You can do this by creating a new skin and "linking" the first skin to the new skin, then the second skin links back to the first one.

Example 2:

You would like to have the album cover bitmap normally visible but then when you click on a button you want the cover to be replaced by the playlist and the playlist editing buttons (move up/down del etc). You need to create two skin files each linking to the other.

Example 3:

You have a really outrageous non-rectangular skin, and like example#1 you want to display some controls only occasionally. One skin can't have two different region outlines, so you must link two skins.

To link skins use Button K01 to K10 in the skin file. These buttons are just like the other buttons with the addition of the name of the skin file to link added to the end of the parameter list. The complete name of the skin file must be specified, however the name does not have to end in ".skin" (this lets you "hide" the skin from the standard select skin requester box). In the main file you link to the second skin (ie with K01) then in the second skin link back to the original skin (also with button K01). In this way pressing the button appears to cause a transformation of the skin. For complicated skins you may need to use both link buttons.

Some final tips when creating a skin

• Use a bitmap editor with a pixel coordinate info display. Have the skin file open at the same time and use the mouse to help you locate the points for your elements.
• By using the selection tool you can select a single "button" image to find out it's width and height.
• Try to avoid moving the buttons around in the resource file. Remember, large areas that don't contain buttons can be used for the digital display digits.
• The resource bitmap can be larger than the main bitmap. You can increase the width or hight of the resource bitmap to make room for the digital display digits.
• If the main bitmap is large with lots of open areas you can also decrease the size of the resource bitmap by rearranging the elements into a small area. This will also reduce the memory requirement of the skin, however it means you will need to specify the new coordinates of each element (those that are moved only) in the skin file.