Plugin:Clist modern/en/Skin development guide

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

1. Module generate Request string as soon as it needs to paint something and give it to skin engine.
2. Skin engine try to find first rule that correspond to given request and select an object that pointed by this rule.
3. If selected object is Solid type: the requested area is painted by corresponding color with specified alpha.
4. 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:

1. Request contains all the rule's parameters. (also request can contain the parameter that is not mention in rule).
2. 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:

• 4 corners;
• 4 edges;
• center.

Transformation rules:

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

After transformation (StretchBoth mode)

There is 4 transformation modes:

• StretchBoth — stretch at both directions;
• TileHorz — tile horizontal, but stretch vertical;
• TileVert — tile vertical but stretch horizontal;
• 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 database during skin loading. File formats is next:

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

"#" is placeholder for one of key type data marks. They can be one of following

• "b" — byte;
• "w" — word;
• "d" — dword;
• "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,…

object_name — object name used to point from rules

object_type — one of types Image or Solid

parameters,… — parameters.

for Solid type:

$object_name =sGlyph,Solid,RedValue,GreenValue,BlueValue,AlphaValue

RedValue, GreenValue, BlueValue, AlphaValue — red, green, blue and alpha transparency values.

for Image:

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

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

Rules are described in next way:

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

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

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

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 call service as user press button, or "-" wait till he release it.

MinWindowWidth, MinWindowHeigh — minimal window size to show button (otherwise hide it).

HintText — tooltip 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 (database 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:
   • a. Paint contact list background
     CL,ID=Background
   • b. Paint row background (request forms according to row content)
     CL,ID=Row,Type=Contact,Selected=True,…
   • c. Paint common selection if selected
     CL,ID=Selection
   • d. Paint common hottracking if hot
     CL,ID=HotTracking
   • e. Draw row content (avatar, text, icons)
   • f. Paint row overlay (request forms according to row content)
     CL,ID=Ovl,Type=Contact,Selected=True,…
   • Repeats b.—f. for each row
5. Paint scroll bar in next
   • Paint scroll bar background
     Main,ID=ScrollBar,Part=Back
   • 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

Param		Value	Description
Module		Main	Main window parts
	ID	Background StatusBar FrameCaption	Window back Status bar back Frame caption back
	ID	ScrollBar	Scrollbar
	Part	Back UpLineButton DownLineButton Thumb	Scroll bar parts
Module		CL	Contact list objects
	ID	Row Ovl	For each row back is generated with param ID=Row, for overlay with ID=Ovl
	Type	Group Contact MetaContact SubContact Divider Info	Type of row: group name, contact, metacontact etc.
	GroupPos SubPos	First First-Single Middle Last	Position of contact in parent group or position of subcontact in metacontact and its parent meta in group
	Open Selected Hot Odd	True False	Collapse, selection, hot and odd values of row
	Index Indent	Number	Number of line in list Indent of row (0 – in root, 1-in first leveled group etc.)
	Status	OFFLINE ONLINE AWAY DND NA OCCUPIED FREECHAT INVISIBLE IDLE	Status of contact
	Protocol Name GroupName	Text	Names of protocol, nick (row text), parent group (parent row text) (commas replace to dots)
	ID	GreyAlternate Selection HotTracking	Common objects for Selection, Hot and Odd
Module		MButton	Buttons
	ID	Text	Button name (without ‘#’)
	Down Hovered	0 1	Pressure and hot states
	Value	Text	Value of associated with triggered button DB key