VB-Amp Skins (updated)
============

NOTE: This is a preliminary specification, subject to change!

Intro
-----

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.

A skin consists of two or three files:

1) 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.

VB-Amp is not limited to a rectangular form. In the skin file you
can also define an irregular-shaped outline region for your skin.


How to make your own skin
-------------------------

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:

  * Buttons
  * Text
  * Digital Display
  * Playlist
  * Slider
  * Album Cover Bitmap

  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
16, 256, or 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 indended! 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 BMP.


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:

  0123456789 .:

  Make sure ALL characters are all exactly the same width. The "space"
character can be blank, or be 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 specifiying 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!

* Line1 must contain only the exact string: "VB-Amp Skin"
* Line2 is a line for the skin name, your name, copyright etc that will
	be displayed in the info tab
* Line3 are 3 pairs of Width/Height sizes corresponding to the size
	of the normal form, extended form and small form like this:
		w1,h1,w2,h2,w3,h3
	NOTE: All dimensions are in pixels!
* Line4 contains the filenames of the main and resource bitmaps.
		file1,file2
	Files must be bmp, gif, or jpeg formats. If you don't have a
	resource file (file2) then use the same filename as "file1"
* Line5 contains option settings:
	Bmode,ScnPos,xx,xx,xx,xx,xx,xx

	- Bmode: Defines the action when the mouse pointer
	  goes over a button on the form:
		0=No action
		1=Draw border rectangle
		2=Display down-button image
	- ScnPos: Defines if the skin should appear in a specific
	  position on the screen:
		0=No change (use last position)
		1=Top Left corner
		2=Top Right corner
		3=Bottom Right corner
		4=Bottom Left corner
		5=Centred
	- xx: extra elements for future use (use "0" for now)

  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:

  * B - Buttons
  * L - Labels
  * S - Slider
  * D - Digital display
  * I - Indicator Light
  * C - Pictures
  * X - Other (listboxes etc)

The following are possible parameters:

  * X, Y	- Coordinate of the top left of an element.
  * W, H	- The Width and Height of an element.
  * X2, Y2	- Coordinate of corresponding image in resource bitmap.
		  (if you use 0,0 then the main X,Y coordinates are used)
  * W2,H2	- Extra Width and Height (ie: for a sub-image).
  * key		- The Keyboard command.
  * tooltip	- Text that appears when the mouse is over the element.
		  NOTE: if the text contains a comma you must enclose the
			entire string in quotations!
			Tooltips starting with "~" will not be displayed
  * r, g, b	- The Red,Green,Blue colour components (Range is 0 to 255).
  * pt		- The Point Size for the font.
  * font	- The Font Name.
  * f		- Numeric Format type.

  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.

  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

	B01 - Power button
	B02 - Minimize (hide) window
	B03 - Toggle Large Mode (window size 2)
	B04 - Toggle Small Mode (window size 3)
	B05 - About/Preferences
	B06 - Select Skin
	B07 - Volume Down
	B08 - Volume Up
	B09 - Volume Mute
	B10 - Stop
	B11 - Pause
	B12 - Play
	B13 - Eject
	B14 - Previous Track
	B15 - Next Track
	B16 - Info
	B17 - Delete Track
	B18 - Move Track Down
	B19 - Move Track Up
	B20 - Clear Playlist
	B21 - Load Playlist
	B22 - Save Playlist
	B23 - Add Track
	B24 - Add Directory
	B25 - Toggle Intro
	B26 - Toggle STP
	B27 - Toggle Repeat
	B28 - Toggle Shuffle
	B29 - Show Mixer
	B30 - Set A point
	B31 - Set B point
	B32 - Reverse
	B33 - Forward
	B34 - Toggle Cover Window
	B35 - Visual Playlist Selector
	B36 - Play/Pause Toggle
	B37 to B48 - Reserved for future use


(B) Special 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.

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

	B49 - Skin Link Button #1
	B50 - Skin Link Button #2

  Skinname = The name of the skin to load (do not specify path!).


(C) Pictures
------------

  This element is for the album cover bitmap on the main form.

Format: Cnn,x,y,w,h,ToolTip  

	C01 - Album Cover bitmap


(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

	L01 - Time (elapsed/remain)
	L02 - Track Title
	L03 - Current Time
	L04 - Track Number
	L05 - Snooze Time indicator
	L06 - Full Date
	L07 - Day of week
	L08 - Mute indicator 
	L09 - AM/PM indicator (blank when in 24hr mode)
	L10 - Kbps
	L11 - KHz
	L12 - Stereo/Mono
	L13 - Total Track Time
	L14 - Playlist Title
	L15 * General messages (ie: volume or position change status)
	L16 - Total entries in playlist
	L17 * Total time of all playlist entries
	L18 * Volume (0-99)

	* = [NI] Not implemented yet

(D) Digital Display Digits
--------------------------

 These are digital displays using graphics digits of any size. 

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

	D01 - Track Time
	D02 - Track Number
	D03 - Current Time

Notes:	- Digits must be arranged on one line like this: 0123456789 .:
	- w,h are for a SINGLE digit
	- w2 is the width of the period and colon.
	- s is additional spacing for destination [NI]
	- f is the display format number (0 to 8):
		0="99:99" (elapsed time)
		1 to 7=number of digits
		8="HH:MM" (time)


(S) Sliders
-----------
 These are analog sliders that can be dragged to any position.

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

	S01 - Playback position
	S02 - Main Volume [NI]
	S03 - Main Balance [NI]

Notes - x,y are the position of the top left of the slider
	w,h determine the length of the slider. One MUST be zero!
	x2,y2,w2,h2 is the position of the slider image in the res bitmap.

(I) Indicator Lights
--------------------

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

	I01 - Stereo Indicator Light
	I02 - Stop Light
	I03 - Pause Light
	I04 - Play Light	
	I05 - Intro Light
	I06 - STP Light
	I07 - Repeat Light
	I08 - AB Repeat Light
	I09 - Shuffle Light


Notes:	- shape values are:
		0=Rectangle 1=Square 2=Oval 3=Circle
	  	4=Rounded Rect 5=Rounded Square


(X) Other Elements
------------------

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

	X01 - Playlist


How to make a non-rectangular skin (Window Region Coordinates)
--------------------------------------------------------------

  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. Points are connected by
straight lines, so to make a circular section you will need to specify
many points.

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

	Nnn	- Where "nn" is the total number of points

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 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).


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#49 and/or Button#50 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 button#49) then in the second skin link back to
the original skin (also with button#49). 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.

  Finally, if you think of a new or innovative way to improve the skin
capabilities, don't hesitate to e-mail me.

Thanks!
Steve.
