Modern Contact List Layered
Skin development guide (13-sep-2005).

Based on version clist_modern.dll v.0.3.1.198

Common definitions

Skin engine is based on next definitions and concepts:

• Object – component of skin. All skin objects are created during module loading.
• Objects describes what and how is need to paint as reply to Request. Glyph –  Some image.
• Now time are supported BMP, JPG and PNG (with transpaancy, imagedecoder.dll library is needed for).
• Size of glyph is defined by image size.
• Glyph picture loads to memory only at first attempt to paint it and is kept in memory till module unloading or other skin loading.

• Rule – rule which Object is correspond to Request
• Request – request from module (this or other) to paint one of corresponding objects at specific place and size.

Work Algorithm

Skin engine sequence is next:

• Module generate request string as soon as it needs to paint something and give it to skin engine.
• Skin engine try to find first rule that correspond to given request and select an object that pointed by this rule.
• If selected object is Solid type: The requested area is painted by corresponding color with specified alpha.
• If selected object is a Image: such image is transformed to requested region size and paints

Rules and Request.

Rule consists of:

1. Number
2. Name of object to point
3. Couple of parameters delimited by ‘,’.

Each parameter is a union of:

• Parameter’s name (first parameter has name ‘Module’ and that always skipped).
• Condition (= - ‘is equal’, ^ - ‘is not equal’)
• Parameter value.

Request has the same part as rule except number.

The rule corresponds to the request if:

• Request contains all the rule’s parameters. (also request can contain the parameter that is not mention in rule)
• All values of common parameters are the same if rule’s parameters condition is ‘equal’ and not the same if rules condition is ‘not equal’.
• Rule parameter values can contain wildcards ‘*’ and ‘?’.

Rule parameter’s names and values can contain up to 24 chars.
Values can not contain ‘,’ (comma) all commas are replaced by ‘.’ (dots)
Names and values are CASE SENSITIVE.
First parameter name should be skipped when points.

Glyph transformation

Example: We need to paint glyph with sizes 70х70 at the rectangle size 100х100.

Define for margins: Left, Top, Right, Bottom.
These margins divide glyph at 9 areas:

1. 4 corners
2. 4 edges
3. center

Transformation rules:

• Corner areas of glyph are painted as-it-is at the destination corners without any resizing.
• Edge parts transforms in direction along their nearest edges and keeping perpendicular to edge size as is.
•  Center area transforms in both directions

 
After transformation (StretchBoth mode)

There is 4 transformation modes:

1. StretchBoth – stretch at both directions
2. TileHorz – Tile horizontal, but stretch vertical
3. TileVert – Tile vertical but stretch horizontal
4. TileBoth – Tile at both directions

Skin definition

Skin is union of skin description file (*.msf) and folder with graphic resources.
Folder name should be the same as the name of descriptor file (without extension). All files inside descriptor should be referenced without path

Descriptor file is the common ini file with changed extension. All keys imports to DB during skin loading. File formats is next:

[db_section_name]
; comments
Key=#Value
Key2=#Value2

Here  «#»  is placeholder for one of key type data marks. They can be one of following

1. «b» - BYTE
2. «w» - WORD
3. «d» -  DWORD
4. «s» - STRING

All modern skin objects and rules are kept in [ModernSkin] section with string type value. So in this section all keys have ‘s’ after ‘=’ e.g.:
$hotopengroup=sGlyph,Image,hotopengroup.png,StretchBoth,2,2,2,2,250
@0=s$window:Main,ID=Background

Spaces inside are not allowed (only for string parameters like …,Name=First Name,…).

Objects description.

So skin consists from several parts. One of they describes Objects.

Objects are described in next way:

$object_name=sGlyph,object_type,parameters,…

Here    object_name – object name used to point from rules
            object_type – one of types Image or Solid
параметры,… –parameters.

for Solid type:
$object_name =sGlyph,Solid,RedValue,GreenValue,BlueValue,AlphaValue

for Image:
$object_name =sGlyph,Image,File_Name,Fit_Mode,Left,Top,Right,Bottom,AlphaValue

here : RedValue, GreenValue, BlueValue, AlphaValue – Red,Green,Blue and alpha transparency values.
File_Name –glyph image file name.
Fit_Mode – transform mode: StretchBoth, TileHorz, TileVert, TileBoth.
Left, Top, Right, Bottom – transform margins.

Examples:
$window=sGlyph,Image,back.bmp,TileBoth,1,1,1,1,150
$closed_miranda_group=sGlyph,Solid,0,0,255,200

Rule description

Next part describes Rules

Rules are described in next way:

@rule_number=s$object_name:Module_parameter_value,param_name=value,parameter_name^value,…

Here: rule_number – number. Numbers should starts from zero and be in sequence without skipping.

Example:
  @0=s$window:Main,ID=Background
  @1=s$closed_miranda_group:CL,ID=Row,Type=Group,Open^True,Name=Mir*a*

For this example object $window (image back.bmp) will be painted if request contain first parameter value «Main» and parameter «ID» value will be «Background».
Object $closed_miranda_group (fill it with blue and alpha 200) will be painted if request will contain first parameter «CL»,  and «ID» equal to «Row», «Type» equal «Group», parameter «Open» NOT equal to «True» and «Name» like «Mir*a*» (e.g Miranda-IM).

Buttons description

Next part describes Buttons

Buttons can be placed in any area of window (but prefer on margins, otherwise they will be covered by frames.

Buttons can be to types Push and Switch.

Push button description is:

#name=sPush,ServiceNameToCall,fromLeft,fromTop,fromRight,fromBottom,Flags,MinWindowWidth,MinWindowHeigh,HintText

Switch button description is:

#name=sSwitch,ServiceNameToCall,StateDBKey,ValueTypeandDefault,fromLeft,-->

<-- fromTop,fromRight,fromBottom,Flags,MinWindowWidth,MinWindowHeigh,HintText

Here is ServiceNameToCall – name of service to be called on key pressure
StateDBKey – name of key to be quoted in request to draw.
ValueTypeandDefault – type of parameter (first char (b,w,d or s) ) and default value
FromLeft,FromTop – position of left-top corner relativity to specified in flags
FromRight,FromBottom – position of right-bottom corner relative to specified in flags
Flags – relativity and behaviour flags is sequence of chars in next order:‘ABCDE’: A-relativity of left edge, B- top edge, C-right edge, D-from bottom  ( value is ‘R’-from right (for A and C), ‘B’ from bottom (for B and D), or ‘-‘ from left (A&C) and top (B&D)), E– can be ‘I’ immediately cal service as user press button, or ‘-‘ wait till he release it.
MinWindowWidth, MinWindowHeigh – minimal window size to show button, (otherwise hide it)
HintText – Tool tip text to show (‘,’ (comma) is not allowed).
             
Then module is need to paint button it form request like (button was desribed like: #statusmenu=sPush,CList/ShowStatusMenu,24,4,40,20,-----,100,0,Show Status Menu)
           
MButton,ID=statusmenu,Hovered=1,Down=0

If switch button is specified it add value: Value=0 (db key value instead of ‘0’)

Modern Paint Request Sequence:

1. Paint backgrounds via request

Main,ID=Background

2. Paint StatusBar, Frame captions backgrounds via

 Main,ID=StatusBar
 Main,ID=FrameCaption

3. Paint buttons via request:

MButton,ID=buttonname,Hovered=x,Down=y,Value=z
MButton,ID=buttonname,Hovered=x,Down=y

4. Paint Contact List in next sequence:
1. Paint contact list Background:

CL,ID=Background

2. Paint Row background (request forms according to row content)

CL,ID=Row,Type=Contact,Selected=True,…

3. Paint Common selection if selected

CL,ID=Selection

4. Paint Common hottracking if hot

CL,ID=HotTracking

5. Draw row content (avatar, text, icons)
6. Paint row overlay (request forms according to row content)

CL,ID=Ovl,Type=Contact,Selected=True,…

7. Repeats b.-f. for each row
4. Paint Scroll bar in next
1. Paint scroll bar background

Main,ID=ScrollBar,Part=Back

2. Paint scroll bar items

Main,ID=ScrollBar,Part= UpLineButton
Main,ID=ScrollBar,Part= DownLineButton
Main,ID=ScrollBar,Part= Thumb

Table of available params and values