Skin Making Documentation. Revision 3.
New! Updated for Vista glass and shadow skin elements
This document is about skin writing for CrystalPlayer. The details of
skin creation, interoperability and example are here. No any programming
knowledge is needed to understand it.
Skins are described in XML format, chosen as most perspective and flexible one.
You can write dynamic XML skin having really no knowledge of programming.
The only needed things are graphics editor (like Photoshop) and text editor
for editing actual .xml file.
Skins are based on so called "finite state machine", mostly
because it's well known and bug-free technology. You may find more about this technology
Finite state machine approach allows dividing skin on parts those can be in several
determined states. For example: control panel with Start, Pause, Stop
buttons may be hidden in case it's unneeded, but in other case, can extend,
showing additionally forward and backward. It means that panel can
be in 3 states. Developer defines all 3 states and defines the rules
of transition between them. For example, he can hide panel when mouse
leaves its borders and show additional buttons if user clicks on the
panel twice. Every logically individual part of skin (e.g. panel mentioned
above) becomes finite state machine, and each state of it – the state
of finite state machine.
Finite state machines (FSM) can interact. For example, there can be help
button (with sign '?') on expanded, pulled out panel, by clicking on which,
the other panel (with help text) pulls out. This panel becomes individual
FSM with states hidden and pulled out. This way, help button, defined
in extended state of 'control panel' FSM defines arc, leading help window
FSM to pulled out state. This is very flexible possibility and
it's implemented without introducing programming languages at all. It's completely
enought to develop obvious transitional graph and to write it in some
The example of transitional graph
Transitional graph illustrates the interaction between individual
parts of the skin – FSMs.
Here below the example of transitional graph describing control panel
and help panel behaviour is displayed.
Logical units – FSMs – are marked with bright color. Every FSM can be in only
one of its states (e.g. for Control Panel they are: Hidden, Pulled Out, Expanded).
In every state, the control elements are defined (most dark color) – these can be buttons
or textures. Also, in state field several properties of applications are defined,
for example, the color of playlist. There are transitions chained with control
elements – pressiong of Hide button of Control Panel FSM in expanded state will lead
Control Panel FSM to pulled out state – so panel is reduced and several
additional buttons are not more shown. We'll describe syntax of defining FSM
structure of skin below.
Skin detailed syntax
XML format was chosen for describing FSM structure of skin. XML looks mostly
like HTML and has tree like structure. Every point of it is described using opening
and closing tags:
<TAG [parameters]> tag body </TAG>
There can be child tags in tag body. If the tag does not have child tags,
it can be written as:
[parametes] – is the optional field in which several parameters of the tag
can be specified. The syntax is:
param1 = "value1" [param2 = "value2"] ...
here param1 is the parameter with name 'param1' and with value 'value1'.
Here is the example of paired tag with two params:
<thetag param1="value1" param2="value2"> ... </thetag>
The whole skin is described between <SKIN RequiredVersion="Version">
and </SKIN>, so it's described in tree like structure with 'SKIN' root.
The obligatory parameter "RequiredVersion" – is the minimal version of CrystalPlayer
supporting this skin. For example:
<SKIN RequiredVersion="120"> ... </SKIN>
means that minimal CrystalPlayer version supporting this skin should be not lower
that 1.20. It's done for supporting compatibility between more recent, extended
formats of skins. This format was extended twice as for now – new features were
added and skins, written for old versions worked correctly. But loading new
skins in old CrystalPlayer will be unseccessful – CrystalPlayer will refuse to interpret it correctly.
In skin body there can be title tag, where the description and authors of skin
can be specified. Example:
<TITLE author="John Smith">My super skin</TITLE>
Finite state machines
FSMs in skin are described using SWITCH tag:
<SWITCH name="SwitchName"> FSM body </SWITCH>
SwitchName is the name of FSM – it's unique identifier within skin. At least
one FSM should be in skin. FSMs may or may interact or may exist individually.
The appearance of the CrystalPlayer is built by the all FSMs consequently.
In FSM body the states of this FSM are described. The first state becomes
initial state, FSM starts its life in it.
The state is described by STATE tag:
<STATE name="StateName"> state body </STATE>
StateName – is the name of the state, its unique identifier in the FSM.
There should be at least one state in each FSM. For the whole time,
FSM is in one of states and active state is the only determinator for
behaviour and appearance of FSM. The description of the state is in 'state body'.
The standart element with the help of which the state is described is control
element – the rectangle area, which has associate appearance and associate
actions. It's described as follows:
<CONTROL topleft="TLCoord" bottomright="BRCoord"
TLCoord – is the coordinate of left top corner of control. Coordinates
are specified conserning one of the four corners of base window – the window
of the video output. The coordinates are: TL(x,y), TR(x,y), BL(x,y), BR(x,y) –
top-left, top-right, bottom-left and bottom-right corners correspondingly.
The displacement (x,y) can have negative numbers and the counting stats
from left top corner. Example: topleft = "BR(-10,15)" means that
top left corner of the control is 10 pixels left and 15 pixels below
the right bottom corner of the video output window. BRCoord specifies
coordinates of right bottom corner of the control.
ChitMode defines the way the control influence the movements and size
of video window. Possible values:
- client – standard way. Also default one if 'ChitMode' is not specified
in 'CONTROL' tag;
- title – dragging control will drag the whole window – in fact,
the behaviour is the same like dragging title of the window;
- top – dragging control will lead to res