Plugin:TabSRMM/Skinning format
The format of a TabSRMM .tsk skin.
A skin definition contains the following elements
- skin elements
- assigned image items
- independent image items
- a settings section
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 % 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 .tsk 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
[%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
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 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
| 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 up, down, right, left (without the quotes) to specify the gradient direction. Default is no gradient. The gradient direction is defined by COLOR1 → COLOR2 |
| CORNER | A string which may contain the values tl, tr, bl, br (again, w/o quotes). Separate multiple entries by commas. tl = top left, tr = top right, bl = bottom left, br = bottom right. Example: Corner=tl,tr (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 $ 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 @ character.
Specifying the image source for an image item
There are 2 ways to do this:
- with the Image=xxx.png statement, you can specify the source file.
- with the Glyph=x,y,x1,y1 statement, you specify the rectangle in the glyph image. The glyphs image is a special item. Its name must be $glyphs 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 Image= 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.
Alpha 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).
Perpixel 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 ItemX=Itemname statement. X is a 0-based index number, so the first assignment has to be Item0=foo, the second Item1=bar and so on. Itemname refers to one of the skin item names listed at the beginning of this document, without the % character.
ColorKey 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.
FillColor 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:
; 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
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.
SbarHeight 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.
FontColor 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.
| 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 $Frame and $FrameInactive. 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 |
[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
The client area section defines the inner padding of the message container. The values Left, Top, Bottom and Right are padding values added to the container itself and the Inner 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 Left, Top, Bottom, Right values to 0 will make the borders as small as possible.
[ClientArea] Left=2 Right=2 Top=2 Bottom=0 Inner=1
The WindowFrame 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 CaptionOffset defines the top offset for the window icon and the title bar text.
[WindowFrame] Left=4 Right=4 Bottom=4 Caption=22 ClipFrame=1 RadiusTL=6 TitleButtonWidth = 12 TitleButtonHeight = 12 TitleButtonTopOffset = 7 CaptionOffset = 6
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:
FramelessMode=1
to the [Global] section. Note that, both items (Frame and FrameInactive) must be properly defined, because the message window will always use both, depending on the active state of the window. When FramelessMode 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 Titlebutton.
When using image items for the frame, you really should use the FillColor 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:
[WindowFrame] Left=4 Right=4 Bottom=4 Caption=20 ClipFrame=1 RadiusTL=6
Left, Right, Bottom and Caption are the widths (in pixels) for the respective border elements (Caption is title bar height).