Getting started with SkinBuilder

1. Overview
2. Quick Start
3. Color Schemes
4. Working with properties
5. Defining macros
6. Global properties
7. System metrics
8. Window elements customization
9. Import/Export

Overview

The SkinBuilder utility allows creating new and customizing existing skins in CJSTYLES format. A skin file is a compiled resource only PE Win32 module that uses a legacy MSSTYLES Microsoft's format for storing Windows XP skins. However those two formats are not interchangeable. Therefore, a CJSTYLES file cannot be used as a theme file for Windows, and MSSTYLES in its turn cannot be used as a skin file for a Toolkit Pro or Suite Pro driven application.

Similarly to MSSTYLES file, a CJSTYLES file contains a number of embedded image and text resource files, in particular embedded .INI files define color schemes provided by the skin, and embedded .BMP and .PNG files are the images referenced by the embedded color schemes and used for drawing certain window and control elements. This means that at least one color scheme (.INI file) is required to exist in a CJSTYLES file.

Because a CJSTYLES file is a resource only (i.e. code free PE library), it can be used in both x86 and x64 project configurations.

Quick start

The SkinBuilder utility is shipped along with Toolkit Pro and Suite Pro and can be found in the Utils directory in the installed location. To get started, you can choose New Project to begin with a blank skin project, or select an existing skin to customize:

The specified location will contain a saved skin project file that can later be reused for skin editing, but it should not be confused with a compiled CJSTYLES file.

Color Schemes

By default a new blank skin will have a virtual Common color scheme that can contain properties common for all other color schemes, but it cannot be used as an individual color scheme. So, as it was said above, at least one color scheme is required to be added. Clicking a '+' button in the Schema pane will allow creating a new color scheme:

The schema name and INI file name fields must be specified. The other fields contain only metadata that describe a schema and have no functional meaning.

This way a tree of color schemes can be built:

Each scheme down the tree has its properties either redefined or inherited from the parent schemes. And only those schemes that have an .INI file name associated can be used from an application. If no .INI file name is provided then a scheme is considered virtual, like the default Common scheme.

Working With Properties

The Schema tree shows a number of items, some have black titles, and some are gray.

A black title indicates that an item has customized properties in the selected color schema, those can be seen in the Properties pane in black color too.

A gray schema item title means the opposite, it either has no properties specified at all, or all of its properties are inherited. Inherited properties can be seen in the Properties pane in gray color.

Defining Macros

Macros can be used to substitute string data with some predefined value. For example a skin contains two color schemes - Light and Dark. Each color scheme has a number of associated images with identical names but kept in folders named Light and Dark. If a common or a parent color scheme is used then knowing scheme name is impossible for referencing a needed image file. In this case scheme Light can have ImageFolder macro defined to "Light", and scheme Dark can have it defined to "Dark" respectively. Now a common or a parent scheme can reference needed images using a relative path name that contain ImageFolder macro:

ImageFile = %ImageFolder%\FrameCaption.png

For this the Macros schema item has to be selected, and in the Properties pane there is a '+' button to add a new macro and specify its name and value manually:

Global Properties

Similarly to Macros, the Globals schema item can have a number of globally defined properties. But once defined, those properties don't get substituted in string values like macros do. Instead they define default values for named known properties. The list of the known property names is available in the dropdown list of the Add Property dialog:

System Metrics

In Windows a number of common user interface parameters are known as System Metrics. Those include common color values, element sizes, font data or flags (see GetSystemMetrics Windows API documentation for more details). An application that uses SkinFramework receives those values not from the Windows itself, but from the skin data if they are defined there. The System Metrics item also provides access to global system colors that are not considered to be metrics but combined in SkinBuilder with metrics for ease of use. The details on possible system color values can be found on the GetSysColor Windows API function documentation page.

Window Elements Customization

Some window or control elements can have state specific property settings. For example a window caption can be customized for active, inactive and disabled states. When element states are available, they can be seen at the bottom of the Schema pane, selecting a needed state will show its customized properties in the Properties pane:

The properties can be customized by pressing a '+' button at the top of the Properties pane and selecting the needed property to add:

The tricky part here is a matching property selection as there is no way to know for sure which properties are used by which control. This behavior comes partially from UxTheme calls from Windows for drawing control parts and from the window message hooking specifics of SkinFramework. It is recommended to review the Common color schema of the sample skins that are shipped along with Toolkit Pro and Suite Pro and property names as defined in those skins. Re-using image formats will also be helpful as various window and control parts require images of certain sizes, direction, or use one image as an image list.

Import/Export

Once a designed skin is ready to be used, it can be exported either to .CJSTYLES compiled skin file or a resource script for Visual Studio Resource Compiler. A .CJSTYLES file can be shipped separately and reused by any number of applications regardless of target CPU type (x86 or x64). A resource script assumes that a skin will be built-in into an application. All this can be achieved using File -> Export menu.

The File -> Import menu currently allows only importing from legacy .MSSTYLES files that are compatible with Windows XP only. No newer MSSTYLES formats are supported.