Email:  
  Register  /  Login  
Home
CrystalPlayer
Company
Русский
OverviewSkinsSupportForum

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.

Introduction

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 at is.ifmo.ru. 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 text format.

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:

    <TAG [parameters]/>

[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>

Header

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

Controls

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"
    chit="ChitMode" gradient="ControlGradient"
    normal="NormalBitmap" mouse="MouseBitmap"
    leftdown="DownBitmap" 
    leftaction="ControlAction" rightaction="RightAction"
    mouseaction="MouseAction"/>

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