View source for Plugin:TabSRMM/Skinning format/en

<languages/>
The format of a TabSRMM <tt>.tsk</tt> skin.

== A skin definition contains the following elements ==

* skin elements
* assigned image items
* independent image items
* a settings section

{{TNT|Note|A skin does not need to be complete. TabSRMM supports partially skinning, so you can define a skin which only changes the look of a few elements (buttons for example).}}

'''Skin elements''' specify the skinnable parts of the message window. These elements must start with a <tt>%</tt> character and the name must be one of the recognized element names. A skin element usually defines a color value or color gradient and can (optionally) have rounded corners and transparency. For more flexibility, image items can be assigned to defined skin elements. In that case, the color values are ignored and the image item will be rendered.

== List of known element types ==

The order in which they appear in the skin file doesn't matter. Each skin element is a single section in the <tt>.tsk</tt> file, enclosed in square brackets and the section name corresponds to the name of a skin item. The item names are case-sensitive.

*Container
*Button
*Buttonpressed
*Buttonmouseover
*InfoPanelBackground
*Titlebutton
*Titlebuttonpressed
*Titlebuttonmouseover
*Tabpage
*Tabitem
*Tabitem_hottrack
*Tabitem_bottom
*Tabitem_hottrack_bottom
*Tabitem_active
*Tabitem_active_bottom
*Frame
*FrameInactive
*InputArea
*MessageLog
*Statusbarpanel
*Statusbar
*Userlist

=== A sample skin element ===

<pre>[%Container]
ALPHA=100
COLOR1=F5F5F5
COLOR2=F5F5F5
COLOR2_TRANSPARENT=0
TEXTCOLOR=202020
CORNER=0
GRADIENT=none
RADIUS=0
Left=1
Right=1
Top=1
Bottom=1</pre>

Items which are not configured in the skin definition file are ignored by the skinning engine (that is, these items are then rendered unskinned and will look like in any other TabSRMM window which does not use a skin).

Item records contain information about the item itself. It offers similar options like the skinning system in {{Plugin|Clist nicer}} There are default values for each of these parameters; most of them are using system defaults (like default background color and such).

=== The meaning of the parameters ===

{| class="wikitable"
|COLOR1
|First color
|-
|COLOR2
|Second color (only needed when a gradient should be rendered)
|-
|TOP/LEFT/RIGHT/BOTTOM
|The item margins (in pixels). These margins will be clipped from the target rectangle where the item should be rendered
|-
|ALPHA
|The transparency value (alpha). Values go from 0 (completely transparent) to 100 (completely opaque – values are therefore in percent)
|-
|GRADIENT
|Set this to one of <tt>up</tt>, <tt>down</tt>, <tt>right</tt>, <tt>left</tt> (without the quotes) to specify the gradient direction. Default is no gradient. The gradient direction is defined by <tt>COLOR1</tt> → <tt>COLOR2</tt>
|-
|CORNER
|A string which may contain the values <tt>tl</tt>, <tt>tr</tt>, <tt>bl</tt>, <tt>br</tt> (again, w/o quotes). Separate multiple entries by commas. <tt>tl</tt> = top left, <tt>tr</tt> = top right, <tt>bl</tt> = bottom left, <tt>br</tt> = bottom right. Example: <tt>Corner=tl,tr</tt> (will result in rounded corners for the top left and top right corner)
|-
|COLOR2_TRANSPARENT
|Set it to 1 if you want to have the second color transparent, so that the gradient will blend with the background
|-
|RADIUS
|A numeric value specifying the corner radius when rounded corners are used
|}

It is possible to skin only some items and leave the others unskinned. If a skin is loaded, items which are left out by the skin definition will be rendered in a standard way, so they will look like ordinary windows screen elements.

== Image items ==

Image items are separated from the normal skin elements definitions. This allows to re-use a single image for multiple skin elements. Images are optional, because the skinning engine can work without them and draw skin items in a traditional way, using gradients only.

Images have to be 32-bit PNG images – other formats are not supported. They can be partially transparent using per-pixel alpha values.

=== There are 2 types of image items available ===

* assigned image items – these are directly linked to at least one of the skin elements. The name of an assigned image item must start with the <tt>$</tt> character.
* independent image items – these are not linked and their main purpose is to provide the look for custom buttons. The name of an independent image item must start with the <tt>@</tt> character.

=== Specifying the image source for an image item ===

There are 2 ways to do this:
* with the <tt>Image=xxx.png</tt> statement, you can specify the source file.
* with the <tt>Glyph=x,y,x1,y1</tt> statement, you specify the rectangle in the glyph image. The glyphs image is a special item. Its name must be <tt>$glyphs</tt> and it must exist when you use reference the glyph image in any other image item. It's not mandatory though – if you don't want to use it, you can load each image item from an independent .png image using the <tt>Image=</tt> statement. The advantage of using glyphs is that it will provide faster rendering and consume much less resources. The glyph way allows that all skin textures can exist within a single image file.

=== Sizing margins ===

Sizing margins have to be specified as Left, Right, Top and Bottom. These margins divide the image into 9 parts. The corner parts are rendered without stretching or shrinking, other parts of the image are stretched to make it fit the target area. Sizing margins are only valid and used when all 4 margin values are specified.

<tt>Alpha</tt> is a constant alpha value which is applied after perpixel alpha values – this can be used to make a non-transparent image translucent. Alpha values are in percent, so the valid range is from 0 (completely transparent) to 100 (completely opaque).

<tt>Perpixel</tt> is a boolean value (0 or 1). If it is 1 (or any other value different from zero), the image will be rendered with per pixel alpha values.

=== Assign images to actual skin item(s) (assigned image items only) ===

This is done with the <tt>ItemX=Itemname</tt> statement. X is a 0-based index number, so the first assignment has to be <tt>Item0=foo</tt>, the second <tt>Item1=bar</tt> and so on. <tt>Itemname</tt> refers to one of the skin item names listed at the beginning of this document, without the <tt>%</tt> character.

<tt>ColorKey</tt> is a special color value which will be used to make areas of the container transparent (e.g. it can be used for rounded corners). The color key can be any value you want, but remember that any pixel with this color will appear completely transparent. the color key does only make sense for the container skin item and is ignored elsewhere.

<tt>FillColor</tt> is a color value, which, if present, will be used to fill the inner part of the target area. You can use this if you only need the margin areas of the image (one example would be the Tab page which is usually invisible covered by the message log and other message window elements). The advantage is that by using a fill color, rendering will be faster. Only makes sense for a "divided" image item (all 4 sizing margins present).

Let's look at a few examples for image items:

<pre>; Defining the global glyph image

[$glyphs]
Image=glyphs.png
Alpha=100
Perpixel=1

[$Tabitem]
Image=select.png
Right=2
Top=2
Bottom=2
Left=2
Alpha=80
Item0=Tabitem_bottom
Item1=Tabitem_active_bottom

[$Button]
Image=button.png
Right=3
Top=3
Bottom=3
Left=3
Alpha=100
Item0=Buttonnotpressed
Perpixel=1

[$Buttonhover]

;reference the rectangle in the glpyh image
;(top/left, bottom/right corner)

Glyph=10,10,32,32
Right=2
Top=2
Bottom=1
Left=2
Alpha=100
Item0=Buttonmouseover
Perpixel=1</pre>

The global section has some general settings for the skin. The 3 glyphs are used for the min/max/close button on the title bar.

<tt>SbarHeight</tt> is height of the status bar in pixels. Using this, you can override the systems default status bar height and make your status bar "match" the background skin image for the container window.

<tt>FontColor</tt> is the color for text output in the message window which is normally printed with the system text color (black). this affects: the info panel labels, the status bar text, text on buttons and elsewhere.

{| class="wikitable"
|Version=1
|Mandatory, don't remove or change, or the skin won't load
|-
|Signature=101
|Same – don't remove or change
|-
|FrameLessMode
|If set to a value not equal to zero, containers will enter frameless mode. That means, they do not use Windows theme to skin the border and caption bar. Using this mode, you can define your own border and caption bar look by configuring the skin items <tt>$Frame</tt> and <tt>$FrameInactive</tt>. They are defined in the same way as other skin items. See the next page for more info on skinning the window frame
|-
|LightShadow / DarkShadow
|Simple color definitions to draw "beveled" 3D shadow effects in some cases. They should match your overall skin color theme
|-
|TabTextNormal/Active/Unread/Hottrack
|Defines with which colors tab labels are drawn depending on the state of the tab
|}

<pre>
[Global]
CloseGlyph=close.ico
MinimizeGlyph=minimize.ico
MaximizeGlyph=maximize.ico
;SbarHeight=22
FontColor=000000
Version=1
Signature=101
FrameLessMode=0

LightShadow=F4F4F1
DarkShadow=B0ACA0
TabTextNormal=CCCC00
TabTextActive=0000BB
TabTextUnread=BB0000
TabTextHottrack=00bb00</pre>

The client area section defines the inner padding of the message container. The values <tt>Left</tt>, <tt>Top</tt>, <tt>Bottom</tt> and <tt>Right</tt> are padding values added to the container itself and the <tt>Inner</tt> value is a padding value added to the tab control. Setting it to 0 will make the tab control border invisible, setting one or all of the <tt>Left</tt>, <tt>Top</tt>, <tt>Bottom</tt>, <tt>Right</tt> values to 0 will make the borders as small as possible.

<pre>
[ClientArea]
Left=2
Right=2
Top=2
Bottom=0
Inner=1</pre>

The <tt>WindowFrame</tt> section is only valid in frameless mode (that is, when you are using your own border and caption bar skinning). It defines the width of the Window border(s) – one value per side and one for the caption bar itself.

The other values in this section define the metrics for the title bar buttons – width, height and a top offset and the <tt>CaptionOffset</tt> defines the top offset for the window icon and the title bar text.

<pre>
[WindowFrame]
Left=4
Right=4
Bottom=4
Caption=22
ClipFrame=1
RadiusTL=6
TitleButtonWidth = 12
TitleButtonHeight = 12
TitleButtonTopOffset = 7
CaptionOffset = 6</pre>

== Skinning the window frame ==

This is a somewhat special case. To skin the window frame, you have to define the following 2 items:

* Frame
* FrameInactive

Of course, you can add image items to these skin definitions like everywhere else.

To enable the skinned frame, you need to add:

<pre>
FramelessMode=1
</pre>

to the <tt>[Global]</tt> section. Note that, both items (<tt>Frame</tt> and <tt>FrameInactive</tt>) must be properly defined, because the message window will always use both, depending on the active state of the window. When <tt>FramelessMode</tt> is undefined or set to 0, the frame will appear with the operating systems theme.

When using frame skin definitions, you also have to define the title buttons, that is, you have to valid skin definitions for the 3 items starting with <tt>Titlebutton</tt>.

When using image items for the frame, you really should use the <tt>FillColor</tt> statement to speed up drawing of the inner part which will always be invisible anyway, because the frame is only a few pixels wide. Adjust the sizing margins of the image items in a way that it will properly stretch on the frame, and then setup the window frame metrics:

<pre>[WindowFrame]
Left=4
Right=4
Bottom=4
Caption=20
ClipFrame=1
RadiusTL=6</pre>

<tt>Left</tt>, <tt>Right</tt>, <tt>Bottom</tt> and <tt>Caption</tt> are the widths (in pixels) for the respective border elements (<tt>Caption</tt> is title bar height).

[[Category:Tutorials{{#translation:}}|{{#getdisplaytitle:{{FULLPAGENAME}}}}]]