SkinStudio definition files - language specification

The definition files are used with SkinStudio. The overall functionality makes them a powerful tool for editing any ini-based file. It describes the ini file, its functionality, and the format of each attribute and allows the creation of a virtual hierarchy between sections with virtual containers. The definition file also allows Skinstudio to generate on-the-fly documentation for the file it describes.

2 Organization of the file

2.1 SkinStudio definition file format

The main structure of the definition file is the same as any other ini file:

[DefinitionSectionName]

DefinitionAttribute=Value

All strings in definition files are case-insensitive, which means that each of the following words will be treated the same:

TYPE
Type
type

This rule applies to all section names, attribute names and attribute values.

Note: Unlike regular ini files, SkinStudio def files are not limited to 64KB, so not all ini editors will be capable of reading them.

2.2 Types of objects – ‘entities’

The definition sections can serve a few purposes. Those will be described in this paragraph. Do not worry if you do not understand the insides of each section. This chapter describes the formatting of the section name; the text between the ‘[‘ and ‘]’ characters. Let’s define a few keywords now:

· word - like a word in regular language. The only acceptable characters are defined in the following set: {‘A’-‘Z’, ‘a’-‘z’, ‘_’} no numbers are allowed.

· number – string of characters in the set {‘0’-‘9’}

· word# - word followed by a number,

· word,word – two words separated by a coma – no spaces or numbers allowed.

· keyword – a word that SkinStudio treats in a special way.

2.2.1 Abstract type (AT)

As in any language we can define abstract types that does not create any particular object or entity but are a base for their creation. An abstract section has the following syntax:

[sectionname]

…

“sectionname” is a word. A good example is the following section defining type for a Boolean attribute:

[Boolean]

Type=Bool

Default=0

All other sections have to comply with the general format (having a coma between two words).

Abstract types are attributes not included in any sections but are here because other attributes inherit from them. Most of the virtual attributes are located in the wb_basics.def which is included in all the current main format definition files. Before creating a new virtual type, please check that it does not exist in wb_basics.def.

2.2.2 Skin section type (SS)

The SS def section describes the actual skin section. This is how you can tell SkinStudio that a section is allowed in the skin format the def file describes. The syntax is

[root,sectionname]

…

where ‘root’ is a keyword and ‘sectionname’ is a word.

2.2.3 Skin attribute type (SA)

The SA def section describes an actual skin section attribute. This is how SkinStudio recognizes the attributes that can exist is particular sections. The syntax is

[sectionname,attributename]

…

where both ‘sectionname’ and ‘attributename’ are words. Each SA depends on the existence of an SS - the SA [sectionname,attributename] needs to have a corresponding SS [root,sectionname] defined in order to be recognized by SkinStudio.

2.2.4 Section Interface (SI) - deprecated!

The SI is a set of SA that does not have the corresponding SS defined. The usage of SI will be defined in the following chapters. For now let’s say it can be treated like an abstract SS. The equivalent for this in the programming languages could be found in Java (interfaces), C/C++ (class templates) or Pascal (classes having abstract methods). Deprecated! The cause of it is that the implementation was a reason of major slowdowns during opening skins using this way of SA generalization.

2.2.5 Section Template (ST)

The ST is a generalization of SS. The usage of ST will be defined in the following chapters. For now let’s say it can be treated like an abstract SS. The equivalent for this in the programming languages could be inheritance of objects. This is the second approach to SS generalizations that appeared to be quite efficient.

3 Definition Object Model - sections inheritance

One of the most important facts to remember is the one that sections are internally treated like objects and so they inherit some of the advantages of object-oriented programming. The most commonly known feature of object-oriented programming is inheritance and property overriding. Let’s see how it works in SkinStudio by defining example ATs ‘GeneralFile’ and ‘Bitmap’ that inherit ‘GeneralFile’:

[GeneralFile]

Name=General File Definition

Type=File

[Bitmap]

Name=Bitmap File

Inherits= GeneralFile

SubType=Bitmap

The way SkinStudio sees the Bitmap specification is:

[Bitmap]

Name=Bitmap

Type=File

SubType=Bitmap

You can see that the ‘Type’ attribute has been inherited by the ‘Bitmap’ AT. The ‘Name’ value, set to “General File Definition” by the parent AT, has been overridden with the “Bitmap File” value in the inherited AT. The ‘Bitmap’ AT also introduces a new property called ‘SubType’.

The possibility of inheritance between def sections makes the def files significantly smaller as some attributes in skin files are similar in many ways.

3.1 Name of the entity – ‘name’ property

The name attribute specifies what to show when a more descriptive version of the defined entity is needed.

Example:

[Bitmap]

name=Bitmap

type=file

3.2 Description of the entity – ‘description’ property

The description attribute specifies the detailed specification of the defined entity. A description is crucial for the automated documentation generator - it also shows in the status bar when the attribute is highlighted in the ‘section view’.

Example:

[TitlebarSkin,SkinName]

inherits=Text

name= Skin Name

default=Skin name

description=Name of the skin. MUST EXIST! Without this, the Personality will not show in the WindowBlinds configuration dialog.

optional=0

3.3 Entity optionality – ‘optional’ property

The optional attribute tells SkinStudio whether the entity is obligatory in the defined skin format or not, and so may be deleted by the user (if the user wishes). If the optional attribute is set to 1 SkinStudio will not limit the user in any way on what is being done with the entity. If the value is 0, SkinStudio will try to protect the entity by not allowing the user to delete it from the skin through the ‘tree view’ or the ‘section view’. Of course there is no way (and no intention) of protecting it in ‘code view’. This applies to both mandatory skin sections and skin attributes.

Example:

[TitlebarSkin,SkinName]

inherits=Text

name= Skin Name

default=Skin name

description=Name of the skin.

optional=0

3.4 SA default value – ‘default’ property

The default def attribute specifies the default value to use when there is no corresponding attribute found in the skin.

Example:

[Colours,ActiveBorder]

name= Window Border - Active

type=ComboColor

default=192 192 192

description=Border color for active window

3.5 SA constraints – ‘constraints’ property

The constraints attribute specifies the limits enforced by SkinStudio on the entity. The format of the constraints attribute varies depending on the value of the entity’s type attribute and will be described separately for each of the attributes in the section describing types.

Type of entity	Format of the constraints
· section	n/a
· string	number - Length of the string (does not currently apply)
· bool	n/a
· int	number-number - The range of allowed attribute values.
· choose	number - The number of available values to choose from.
· colour	n/a – Hard-coded to 0-255.
· combocolour	n/a – Hard-coded to 0-255 0-255 0-255
· file	*.ext – The file format mask
· enumerator	n/a
· group	n/a
· set	number - The number of available values to choose from.
· font	n/a
· ignored	n/a

3.6 Visibility of an entity in generated documentation – ‘hidedoc’ property

Hidedoc is the property to control whether the definition of the entity (either SA or SS) will be visible in the generated documentation. When this option is set to 1 its definition will not be shown in the automatically generated HTML format documentation (see "Help -> Generate documentation" in SkinStudio menu while you have any skin opened to see what the HTML documentation generator does). Again, this property can be set for both section (SS) and attributes (SA) definitions. If this property is not specified it will default to 0.

3.7 Advanced mode only skin attributes – ‘hideinsimplemode’ property

Set the hideinsimplemode property to 1 if you want the attribute not to be listed in the section view when in simple mode (this is for the advanced attributes that can be altered other ways eg. through specialized panels like the ‘image editor panel’ or ‘font editor panel’). If this property is not specified it will default to 0.

3.8 Inter-process communication with the skinning software – ‘sendmessage’ property

Def author may specify the message SkinStudio sends to the process that is a registered receiver after the value of the SA have been altered, Sa have been added or deleted. The value of the property is a word and has to be recognized by the message receiver. It as well may and may not be case sensitive (case sensitiveness depends on the message receiver).

3.9 Attribute grouping – ‘ingroup’ property

SkinStudio may divide attributes into groups. Groups are defined as separate entities and are described in chapter describing group type entities.

3.10 Shadow SAs – ‘shadow’ property

Since SkinStudio 3 attributes may be represented in sections in which they do not exist. Such attribute has exactly the same definition as the original attribute (its definition is inherited) but shows in different section. The if the shadow is 1, the attribute will clone the other SA it inherits but in the section in which it’s defined (here in the example Button.Checkbox).

Example:

[Button.Checkbox,OldImage]

Inherits=Buttons,CheckButton

shadow=1

InGroup=GroupForDeprecations

3.11 Shadowed SAs – ‘shadowed’ property

Since we have defined that the attribute should show in another section, we may wish to hide the original one in the original section. In such case you should use the shadowed property to hide such SA.

Example:

[Buttons,CheckButton]

Name=Check Button

Inherits=Image

shadowed=1

3.12 Types of entities – ‘type’ attribute

Each def section (no matter if it defines AT, SS, SA or SI) needs to have a type specified. The def section type is defined in the following way:

[sectionname]

type=sectiontype

def section types can be one of the following:

· section

· group

· string

· bool

· int

· choose

· color

· combocolor

· file

· enumerator

· set

· font

· ignored

It makes no difference to SkinStudio whether the type is defined in the def section parent (and has been inherited) or in the def sections itself – its type does not need to be duplicated in the inherited entity.

3.12.1 Type ‘section’

The entity with type ‘section’ describes the skin section.

Example:

[root,titlebarskin]

type=section

name=Skin copyright info

The image attribute in the def section of type section tells SkinStudio what the default attribute is for the section (in most cases it is the image attribute). This property is used when user changes a section. On this action SkinStudio automatically selects the default attribute for the section allowing for easy editing in the image panel (center-bottom) or the font panel. This attribute is only applicable when the sef section is of type section.
The enumerated attribute is for sections with increasing section numbers like [Button#].
Such sections can be referred by the enumerator SA
The iconopened property specifies the skin explorer tree icon for when this SS node is selected. If its value is identical to the iconclosed value SkinStudio will paint a magnifying glass when the section will be selected in the tree. Default Value is 9 which show the opened folder icon.
The iconclosed property specifies the skin explorer tree icon for when this SS node is not selected. Default Value is 8 which show the folder icon.
virtual specifies that the SS is a virtual container. A virtual container is a SS that does not contain any attributes and does not even exist in the target format - it's there only to organize the tree in the section explorer (like the [Controls] section in WB).
The parent is the section tree organization pointer; this property sets the node's attach point in the explorer tree. This property should be set to the section name of the SS to which it should be attached.
The implements# attributes in the SS definition are references to interfaces that the skins section should implement. It causes all the attributes implemented by the interface to be imported into this section. Implementing interfaces works only when the implementinterfaces in the [FileFormat] section in the main def file is set to 1. This is the deprecated way of SS generalization.
The template# attributes in the SS definition are references to templates that the SS should incorporate. It causes all the attributes defined by the template to be imported into this section. It will also cause all groups defined in the template to be pulled in to the section. Templates usage takes precedence only when the implementemplates in the [FileFormat] section in the main def file is set to 1. This is the recommended way of SS generalization.
xpstuff is a WB-specific property. This property enables SkinStudio to move the SS to the separate file specified in the [XPTaskbar] section by the File attribute.
enumerated property defines whether the section can occur in the skin file multiple times. Each occurrence of such section has to be trailed with a number.

3.12.2 Type ‘group’

The entity with type ‘group’ describes the group within a section. A group is a virtual entity created to bring order to messy sections like Personality in WindowBlinds format. You can divide such section into smaller groups having a title and user will be available to rollup or unroll such group on will.

Example:

[personality,titlebar]

type=group

name=Titlebar Text

Description=This group contains all attributes that are related to titlebar text

default attribute needs some explanation here. If the default value is set to 0 the group will be rolled up on first open of the section in the skin, 1 will show it unrolled by default. If the default attribute is not present SkinStudio will use 0.

3.12.3 Type ‘string’

The SA defined by the definition section of type string is the most weakly-defined type of SA. Strings can have any text values and are not limited in any way. However most string def sections in the current SkinStudio def files have a constraint property specified which intended to limit the string’s length - this does not apply in current SkinStudio builds and is unlikely to work in the future, however it will be implemented should any of the (current or future) formats supported by SkinStudio require it to be.

Example:

[titlebarskin,skinname]

type=string

constraints=255

name=Skin Name

default=Skin name

description=Name of the skin.

optional=0

3.12.4 Type ‘bool’

The def section of the bool type describes a Boolean value in the skin. A Bool attribute can have one of the following values: ‘0’ or ‘1’. A Bool type is sometimes defined as limited with ‘constraints=2’, but this does not apply to current SkinStudio builds and is no longer needed.

Example:

[buttons,enhancedmode]

type=bool

name=Enhanced Mode

default=0

description=Adds third state to Radio and CheckBox Button Images.

Note: sometimes when the AT name is not self explanatory enough it is better to use the choose AT type, with constraints=2 (values ‘0’ and ‘1’), since for a bool type SA SkinStudio shows the bool value to be ‘Enabled’ or ‘Disabled’, while the choose type AT can have more appropriately described states (like [‘False’, ‘True’] or [‘Show’, Hide’]).

3.12.5 Type ‘int’

The def section defining the int type tells SkinStudio to recognize the SA as an integer value. Int attribute values must be within the set of characters {‘0’ - ‘9’}. Int SAs are limited by the constraints property to the range allowed by the skin format. The default property tells SkinStudio what value should it use when the attribute does not exist in the skin.

Example:

[Button,XCoord]

Name= Horizontal Offset

Type=Int

Constraints=-32767,32767

Default=0

Description=Shift BUTTON image HORIZONTALLY from edge.

Optional=0

3.12.6 Type ‘choose’

The choose type allows SkinStudio to define the range of values having special meaning in the skin format. The values must have granularity 1 and must be defined one after another (without gaps). The constraints attribute specifies the number of values (not the maximal value). For this type there is a special attribute defined: shiftnumericvalue. shiftnumericvalue specifies the value of the attribute defined with the attribute value0 selected – it effectively sets the lower end of the skin attribute range. The upper end is specified as shiftnumericvalue + constraints.

Example:

[Button,Action]

name=Action on Click

type=choose

constraints=47

shiftnumericvalue=-6

default=0

description=ACTION used when BUTTON is pressed

value0=Do nothing. Just show an image.

value1=dll button. Non clickable.

…

value46='Link-To' Toggle

value47='Exclusive Link-To' Toggle

In the above example the values are in the range -6 to 40. As explained in the description of the bool type it may be sometimes better to use the choose type instead of bool.

3.12.7 Type ‘color’

The SA of type color defines one channel of the color. The whole color is defined by a set of three color SAs. The last character of the skin attribute name specifies the channel defined by the SA. The constraints are hardcoded to 0-255. The letters are defined as follows:

R – red channel
G – green channel
B – blue channel

Example:

[personality,menur]

type=color

default=192

name=Menubar Selection Outline - Red Level

description=Red MENU SELECTION OUTLINE color level

[Personality,MenuG]

type=color

default=192

name=Menubar Selection Outline - Green Level

description=Green MENU SELECTION OUTLINE color level

[Personality,MenuB]

type=color

default=192

name=Menubar Selection Outline - Blue Level

description=Blue MENU SELECTION OUTLINE color level

3.12.8 Type ‘combocolor’

Combocolor defines the whole color in one SA. The SA of type combocolor might be used when the format of the color is: number number number, where the numbers define the channels in RGB order.

Example:

[Colours,ActiveBorder]

type=combocolor

name= Window Border - Active

default=192 192 192

description=Border color for active window

3.12.9 Type ‘font’

The Font type allows SkinStudio to use the ‘font selector’ tool to select the typeface name from the list of available system fonts. Starting from Build 385 it also enables the special Font settings panel defined with the following attributes:

fontheight – specifies the font height (the attribute type must be int)
fontunderline – specifies whether or not the text should be underlined (type bool)
fontitalics – specifies whether or not the text should be printed in italics (type bool)
fontweight – specifies the font weight (type set)
fontantialias – specifies whether or not the text should be anti aliased (type bool)
fontangle – specifies the angle at which the text should be displayed (type int)
shadowoffset – specifies an additional attribute for setting for the drawing style (type int)
drawingstyle – specifies the text drawing style attribute (type choose)
fontcolor – specifies the text color attribute (type color or combocolor)

3.12.10 Type ‘file’

The file type is one of the most complex types. It defines the link to an executable, zip file, bitmap files and any other files referred from the skin. Common for all the file attributes are constraints that specify the filter for the supported file type. The format of the constraint is *.ext. The def author may also specify the filters for the ‘Open File’ dialog when user decides to browse for a file. The format for filter is “filtername1|*.ex1|filtername2|*.ex2|All Files|*.*”.

The file list is placed in the combo box for most subtypes. For any subtype but bitmap and animation you can specify the searchinfolder property: this property specify where the file should be searched for. Valid values are:

software – files are relative to the skinning software folder and if the skinning software is installed the file will be searched in the folder of the skinning software. Skinning software is detected automatically basing on the skin format.
skin – the file is searched in the path relative to skin folder.

Default value for this property is skin.

The file can have several sub types. The subtypes and the subtype-specific attributes are described in the following subchapters.

Example:

[generalfile]

name=Any File.

type=file

constraints=*.*

filter=All files|*.*

searchinfolder=software

description=Any file definition

3.12.10.1 Subtype ‘bitmap’

The bitmap subtype is used to include the images in the skin. This subtype has several specific attributes:

The imagecount property specifies the regular number of "image states" (frames) within the image file - SkinStudio uses it in various places, so it is very important to specify this property.
The image# property should be defined as many times as the value specified by imagecount property. The image# property specifies a name for each image frame.
imagecountdef is set for images supporting animations or images that can have variable frame count. The imagecountdef property specifies the attribute containing information about the number of image states (frames) within the image file. If the imagecountdef property is not found, the number specified by the imagecount property will be used.
The verticalstack property specifies how the images are aligned in the file. Set the value of the property to 0 or do not include this property when the images are aligned horizontally. A value of 1 will cause SkinStudio to recognize the image as vertically aligned.
The wizard property, when set to 0, hides the image attribute from wizard image list in the New Skin from Template wizards.
The margintop property specifies the name of the SA used to set the top margin of the image
The marginbottom property specifies the name of the SA used to set the bottom margin of the image
The marginleft property specifies the name of the SA used to set the left margin of the image
The marginright property specifies the name of the SA used to set the right margin of the image
The trans property specifies the name of the SA used to set the transparency of the image
The tilemode property specifies the name of the SA used to set the tiling/stretching mode of the image
The normalframe, pressedframe and mouseoverframe properties are not used yet – support is planned
The InvertTileMode property specifies whether the SA selected by tilemode actually has the tile/stretching mode inverted. Like SA “Stretch” for which value of 1 means stretch not tile.
The alpha property specifies the name of the SA used to set the alpha blending value of the image.

Example:

[Buttons,Bitmap]

type=File

subtype=Bitmap

constraints=*.bmp

filter=Bitmap Files|*.bmp|All Files|*.*

name=System Buttons

wizard=1

default=bms.bmp

margintop=topheight

marginbottom=bottomheight

marginleft=leftwidth

marginright=rightwidth

trans=trans

tilemode=tile

imagecountdef=framecount

normalframe=1

pressedframe=2

mouseoverframe=5

imagecount=5

alpha=alpha

image1=Normal

image2=Pressed

image3=Disabled

image4=Focus

image5=Default

3.12.10.2 Subtype ‘animation’

The animation subtype assumes that the image is a set of frames of fixed size (this was added for WebBlinds). As such we need to specify the extents of these frames. This is done using two properties:

frameheight - the height of the single frame in the file
framewidth - the width of the single frame in the file

Example:

[WebBlinds,AnimSmall]

type=file

subtype=animation

filter=Bitmap Files|*.bmp|All Files|*.*

name=Small Animation

constraints=*.bmp

description=WebBlinds Animation

optional=1

frameheight=22

framewidth=38

3.12.10.3 Subtype ‘sound’

A reference to a wave file.

Example:

[Button,InSound]

name=Button Sound - Press

type=file

subtype=sound

constraints=*.wav

filter=Wave Files|*.wav|All files|*.*

description=SOUND to play when the button is PRESSED

3.12.10.4 Subtype ‘command’

A reference to an executable file.

Example:

[Button,Command]

name=Program/Command

type=file

subtype=command

constraints=*.exe

filter=Program File|*.exe|All files|*.*

description=COMMAND to execute when the is PRESSED

3.12.10.5 Subtype ‘zip’

A reference to a zip file.

Example:

[Personality,IconTheme]

name= IconPackager Theme

type=file

subtype=zip

constraints=*.zip

filter=Zip File|*.zip|All files|*.*

description=Icon Packager ICON THEME to be installed.

3.12.10.6 Subtype ‘script’

A reference to a script file.

Example:

[ScriptFile]

name=Script File

type=file

subtype=script

constraints=*.wbs

filter=Script File|*.wbs|All files|*.*

description=Select WB Script File

3.12.11 Type ‘enumerator’

An Enumerator is a reference to another section of the enumerator subtype. The enumerator can be of the following subtypes: button, layout, script, font, colour. The actual value of the attribute in the skin is the number trailing the enumerated section name. When the enumerator is of type eg. colour it refers to the colour section. etc… constraints are not applicable (hardcoded to 0-255). The default value is 255 and could be specified in the def file, though it’s not recommended.

Example:

[normalfont]

name= Font - Normal

type=enumerator

subtype=font

description=Normal Font Face

3.12.12 Type ‘set’

The Set type is a good choice when the attribute can have values of some specific set that cannot be defined by a choice type, because (for example) it’s not numeric, or the granularity is not 1. Constraints should specify the number of elements in the set. The elements in the set are described by a pair of two attributes value# and realvalue#. The first one defines the name of the set element, while the second one is the actual value that should be placed in the skin file. Both should be specified for all the elements in the set. The default attribute specifies the default element of the set and should have the value of the value# attribute of one of the elements of the set.

Example:

[FontWeight]

name=Font - Weight

type=set

constraints=9

default=400

value0=Thin

realvalue0=100

value1=Ultra Light

realvalue1=200

value2=Light

realvalue2=300

value3=Normal

realvalue3=400

value4=Medium

realvalue4=500

value5=Semi bold

realvalue5=600

value6=Bold

realvalue6=700

value7=Ultra Bold

realvalue7=800

value8=Heavy

realvalue8=900

description=Font Weight (eg. 200=light, 400=Normal, 700=bold)

3.12.13 Type ‘ignored’

This type of attributes is used to handle the code that of some reasons is obsolete or erroneous. SkinStudio can check for the presence of obsolete and erroneous code when the skin is being opened. It will also highlight the SA marked as ignored when the skin will be analyzed.

3.12.13.1 Subtype ‘moved’

This kind of SA can be created when the skin specification have been changed and some SA names have changed or have been moved to different sections. You may specify where actually SkinStudio should move those attributes with use of moveto# property. Skinstudio will create as many copies of the attribute as the number of moveto# properties is found in the SQ definition then it will delete the original SA. The syntax of the moveto# property is:

moveto#=SkinSection SkinAttribute

where SS name is optional and, if not specified, will simply rename the SA and leave it in its current SS.

Example:

[General,ResizeBorderSize]

type=ignored

subtype=moved

name=Obsolete resize margin

moveto0=ResizeBorderSize_Top

moveto1=ResizeBorderSize_Left

moveto2=General ResizeBorderSize_Bottom

moveto3=General ResizeBorderSize_Right

3.12.13.2 Subtype ‘deleted’

The deleted SA can be specified for the code that the skinning software ceased to support or for the SA that are often placed there by novice skinners but were never supported by the skinning software. SkinStudio will delete such SA on erroneous code checking. If you know of such SA’s in the format it’s better to let SkinStudio mark them as unsupported than not defining them. It’s always better to say “This SA is not supported by the skinning software” than “This SA is not recognized by SkinStudio” as it states things clear.

Example:

[General,SkinHeight]

type=ignored

subtype=deleted

description=This attribute is obsolete and will not be supported by the future versions of ObjectBar. You should let SkinStudio delete this attribute.

4 Defining explorer tree structure

The first thing we need to know is how to declare a skin section. The way it’s done in def files is:

[Root,TitlebarSkin]

Type=Section

Name=Skin Root

This definition allows SkinStudio to recognize the ‘TitlebarSkin’ section when it finds one in the edited skin. The above code also tells SkinStudio how to present the section to the user. It specifies that the section in the ini file called TitlebarSkin in SkinStudio will be referenced as “Skin Root”. Both entries are required for performance issues.

Now... we need to define section structure.

[Root,Controls]

Type=Section

Name=GUI Controls

Parent=TitlebarSkin

Virtual=1

[Root,Scrollbars]

Type=Section

Name=Scrollbars

Parent=Controls

Optional=0

IconClosed=28

IconOpened=143

Now what we have defined above is the actual structure of this tree:

Skin Root

+----------GUI Controls

+----------Scrollbars

The virtual attribute for the [Controls] section means that the [Controls] section is not an actual section but is just a virtual container that can have other sections as its children, but which cannot have any attributes of it’s own. Optional=0 means that if the section [scrollbars] exist it cannot be removed. This is good for the must-have sections so that the user does not accidentally remove it. The iconopened and iconclosed attributes are the index of the internal Skinstudio icon list. The current icon set is defined in chapter 5.

5 Shadow attributes and phantom sections

SkinStudio 3 introduces the idea of Shadow SAs. The problem with most skin formats which is especially visible in UIS files is that they are messy. With SkinStudio 3 Def files designer can move attributes to other sections for editing to make the format better oriented for the user. It even enables to the author to show multiple copies of an attribute in many sections and and hide the original ones.

For example WindowBlinds 3.4 introduced a new way of defining Checkboxes and Radio buttons. They are not in thei separate sections. But for compatibility reasons WB still accepts them in their original [Buttons] SS. But we want users to switch and start implementing them in the newer way. So we want hide the deprecated definitions in their original section and show them in the new section to put everything regarding checkboxes in one place. Let’s see how it’s done in the code (for the means of clearness only the relevant properties have been shown). We mark the original attributes as shawdowed (so they can be hidden if the attributes shadowing is enabled in SkinStudio):

[Buttons,CheckButton]

Inherits=Image

Shadowed=1

[Buttons,CheckButtonMask]

Inherits=ImageMask

Shadowed=1

[Buttons,CheckPerPixel]

Inherits=PerPixel

Shadowed=1

[Buttons,EnhancedMode]

Type=Bool

Shadowed=1

Now we have to define their shadows in the target section:

[Button.Checkbox,GroupForDeprecations]

Inherits=TGroupForDeprecations

[Button.Checkbox,OldImage]

Inherits=Buttons,CheckButton

Shadow=1

InGroup=GroupForDeprecations

[Button.Checkbox,OldImageMask]

Inherits=Buttons,CheckButtonMask

Shadow=1

InGroup=GroupForDeprecations

[Button.Checkbox,OldCheckPerPixel]

Inherits=Buttons,CheckPerPixel

Shadow=1

InGroup=GroupForDeprecations

[Button.Checkbox,OldCheckEnhancedMode]

Inherits=Buttons,EnhancedMode

Shadow=1

InGroup=GroupForDeprecations

As you can see the shadow defining is not hard to understand. Right now the attributes shadows defined in the [Button.Checkbox] section will mimic the original ones. They will appear in the [Button.Checkbox] section but all reads and writes will still influence the [Buttons] section. Easy isn’t it?

But what if the section does not exist? What of it’s not shown in the tree? Skinstudio still hides the original attributes but does not show the shadowed attributes because it does not know that such section should be faked too. Here is where phantom SS’s come in handy. You need to define such SS as phantom so SkinStudio know that is should show it no matter if the target SS exists in the skin or not. Even more you may create a shadow SS that are not allowed in the skin format and fill it with shadow attributes only. That way the def author may extract e.g. the “Titlebar Text background” attributes from the [Personality] SS and put them in a fake [TitlebarText] SS. The phantom SS is defined exactly like the regular SS. The only difference is that it’s listed in the main definition file in the [PhantomSections]. In our example it will be like:

[PhantomSections]

Section0=Button.Checkbox

Section1=Button.Radio

6 Main definition file for a skin format

Each skin format has a main def file. This file specifies all the format-specific options using its own sections and the sections defined by other def files it includes. One section that should exist in only one file (the main file for the format) is the [fileformat] section. In this section we include the other def files by using include# attributes. The attributes have to be numbered consecutively because SkinStudio stops including files at the first gap in numeration. The numeration starts from 0.

Other attributes found in the fileformat sections are:

rootsection - the name of the section to be treated as the root in the section tree
rooticonopened - the icon index for when the root node is selected
rooticonclosed - the icon index for when the root node is not selected
convertobsoletecode - whether the format supports obsolete code replacing
skinnedsoftware - names the software using this skin format
imagesrelativetofolder - allows SkinStudio to determine whether or not the parent folder name should be included in the file references
implementinterfaces - tells SkinStudio if it should process the interface implementing for sections. This setting is not recommended as it slows down skin opening considerably. Please do not use interfaces for more complex formats, like WindowBlinds.
implementtemplates - tells SkinStudio if the def author have implemented template sections in the format definition. This is the new approach to section generalizations and should be used instead of Interfaces.
GeneratedHTMLFileName - the filename to be used to generate documentation
ssHTMLFormatSpecPageTitle , ssHTMLFormatSpecDefaultTitle, ssHTMLFormatSpecDefaultText, ssHTMLFormatSpecColourKeyExplain, ssHTMLFormatSpecColourKeySection, ssHTMLFormatSpecColourKeySectionD, ssHTMLFormatSpecColourKeyAttribM, ssHTMLFormatSpecColourKeyAttribMD, ssHTMLFormatSpecColourKeyAttribO, ssHTMLFormatSpecColourKeyAttribOD, ssHTMLFormatSpecColourKeyMoreInfo, ssHTMLFormatSpecColourKeyMoreInfoD – all localized strings used in generating documentation

7 Section Templates (ST) as an efficient technique to a great number of similar sections

The ST is a generalization of SS. It is an efficient way of implementing sections that are identical or very similar. The equivalent for this in the programming languages could be inheritance of objects. This is the second approach to SS generalizations that appeared to perform excellent.

Section template defines what SAs appear in a section and what groups it is divided into. The attribute are then populated in the definition file with usage of inheritance of their source attribute.

The definition of the section template can look as follows:

[TWBDSectionInterface]

Group0=GroupForMargins

SourceAttribute0=ImageObject

TargetAttribute0=Image

SourceAttribute1=ImageMask

SourceAttribute2=TGroupForMargins

TargetAttribute2=GroupForMargins

Now the example section implementing that template would look like this

[Root,ShellStyle.Arrow]

type=Section

name=Shell Style Arrow

template0=TWBDSectionInterface

Now the section implementing this template will have three SAs:

Image – Inheriting from ImageObject, Image mask with the name that will be the same as the source (because the target name is not specified) and a GroupForMargins SA that will inherit after TGroupForMargins.

The equivalent code for this (and how the definition is populated in memory) would be as follows:

[Root,ShellStyle.Arrow]

type=Section

name=Shell Style Arrow

Group0=GroupForMargins

[ShellStyle.Arrow,Image]

Inherits=ImageObject

[ShellStyle.Arrow,ImageMask]

Inherits=ImageMask

[ShellStyle.Arrow, GroupForMargins]

Inherits= TGroupForMargins

The bold parts have been generated by internal SkinStudio template population code. So as you could see Templates are the short ways of defining multiple similar SS’.

8 Images and icons defined in SkinStudio

Figure 1 - The list of available icons with the corresponding icon numbers

Object Bar, Pocket Blinds, UIS, WebBlinds and WindowBlinds are either registered trademarks or trademarks of Stardock Inc.

Microsoft Windows 95 / 98 / Me / NT / 2000 / XP are either registered trademarks or trademarks of Microsoft Corporation.

All other names appearing in this document may or may not be either trademarks or registered trademarks of their respective companies.

NOTE: Specifications are subject to change without notice.