[voltaic]

STYLEBUILDER: THE BASICS
by voltaic
May 24 2003



I. Requirements:


Wanna create your own themes huh?
Well, not so fast.
Before you do anything you will need three applications.
First visit TGTSoft's website at http://www.tgtsoft.com/
Download their theme editing software, StyleBuilder.
The second thing you may want to get is a resource editor.
I recommend Resource Hacker at http://www.users.on.net/johnson/resourcehacker/
The resource editor can be used to edit themes manually (not covered in the tutorial).
And the third application you need is something that you already have: Notepad.exe


II. Purpose:


Nothing much to say here, you already know why you're here.
This simple tutorial will walk you through the basics of StyleBuilder and theme editing.
The explanations are intended for beginners who should at least know what skinning is.
General knowledge of image editing, file types, folders etc. is required.
If you came this far to find this tutorial you should have some background information.
This tutorial will not teach you how to make an entire theme.
This tutorial will cover the basics to get you started.
With such practical information you should be able to figure out how to do the rest.
This is not as hard as you think it is.


III. Understanding XP Styles:


The latest version of the Windows operating system, Windows XP, includes a skinning engine.
With this ability the user can change the way the graphical user interface looks and reacts.
Control elements, windows, menus, text and other miscellaneous components can therefore be skinned.

The user can change these features by using theme files with ".msstyles" extensions.
.Msstyles themes are basically a collection of setting files and images.
The majority of file types used in .msstyles are .ini .xml .bmp and .png

.ini and .xml files contain all the settings relevant to the particular theme.
.bmp and .png files on the other hand are image files that contain the interface graphics.
.ini and .xml files tell the operating system how to use and manipulate the image files.

In a nutshell this is what an .msstyle is composed of.

When working with StyleBUilder you will notice other miscellaneous files.
We mostly do not deal with them because they usually contain settings that should not be changed.
StyleBuilder in addition creates its own file format with an ".sb" extension.
This file contains documentation and substitution values that I'll be talking about later on.


IV. Using StyleBuilder:


Although it may seem complicated at first, StyleBuilder is fairly easy to use.
There are six main sections that we can work with:

1) Shortcut Bar
2) Part Tree
3) Preview Window
4) Part window
5) Properties Tab
6) Properties Window

[See the image below]

The Shortcut Bar is where we select which main section of a theme we are going to work with.
StyleBuilder provides the user with nine different main parts to select from.
Each main part in the Shortcut Bar will display the selected part in the Preview Window.
In addition the Shortcut Bar includes links to solid color and font settings of the theme.

The Part Tree is where we can select specific parts of a theme.
While the Shortcut Bar only included the main components of a theme, the Part Tree includes specific parts under these main components.
For example a Window is a large component composed of specific parts such as a captionbar.
The Part Tree lists all the parts of a theme in hierarchical order.

The Preview Window displays the general component that we select using the Shortcut Bar.
This window is not only a preview window, but it also acts as a shortcut window.
By clicking on the specific element displayed in the Preview Window we can easily edit it in the Properties Tab.
For example if we wanted to change how the Start Button looks we would first click on the Task Bar button in the Shortcut Bar,
and then we would click on the actual Start Button displayed in the Preview Window.

And this would take us to our next destination: the Properties Tab.
The Properties Tab shows the user what properties the selected part has.
In the previous example our selected part would be the Start Button because we just clicked on it.
In order to display a part's properties we can select that part in two different ways.
The first method is by clicking on the actual part in the Preview Window.
The other method is finding the name of that part in the Part Tree, which lists all the available parts in the theme.
Once we pick our part the Properties Tab shows us what kind of properties are available.
We can also add properties that are not enabled by clicking on the "Add Property" button.
Similarly we can remove a part by selecting the part we want to remove and clicking on the "Remove" button.

After we decide on a property we want to edit we can move on to the Properties Window.
We first need to click on the property we are going to edit.
Once we click on the property in the Properties Tab, the Properties Window will display what can be changed about that particular property.
Examples include margins, color, image files, sizes, and numerical values.

For instance if we wanted to change the color of the Start Button text, we would click on the "TextColor" property in the Properties Tab.
To change the text color we then would change the RGB color value of the text in the Properties Window.

And finally the Part Window displays the images used in a particular part.
The Part Window has fairly limited functionality.
The main purpose it serves is to allow the user to see how a resized graphic would look.

If you can do everything so far then technically you can make your own theme.

[voltaic]

V. Creating a New Theme:


Making a new theme involves starting with a template theme and changing most of its properties.
Once you set the properties to your liking you should have a new theme.
The part that takes most of your time is going to be making the theme the way you want.
Most of the time the properties you change will not produce the results you expect.
Therefore themeing require a lot of trial and error.

Before you start working on your theme you will need a template.
To do this you need to click the "New" button in the upper left corner of StyleBuilder.
The program will ask you to specify a folder in which the theme files will be created.
Create yourself a separate folder for just the theme you will be working on.
DO NOT create the theme in a folder that already contains other data.

When you click ok, StyleBuilder will create the necessary .xml .ini files as well as the theme graphics (.bmp and .png).
Once you navigate to the folder in which your theme was created you will notice three folders.
These will be called "Blue" "Homestead" and "Metallic"
As you might notice these folders contain images that your SubStyles use.

A SubStyle can be thought as a theme in a theme.
For example the default theme called "Luna" contains three SubStyles.
In this case the SUbStyles are simply different colored versions of the main theme.
SubStyles can be useful if you intend to make slightly different versions of a theme.
For example you may want to include different color schemes, or different button graphics in your theme.
To do this you would use multiple SubStyles so that you don't have to create 50 different .msstyles files.

To see which SubStyle you are working on look at the Shortcut Bar.
Above and below the Shortcut Bar you should see the names of the SubStyles.
The SubStyle you are editing is the one that has all the buttons listed right below it (Windows & Toolbars, Task Bar etc.)

You can also create new SubStyles by clicking on "Edit" in your toolbar menu and selecting "Add New Color Scheme".
In the Add Color Scheme window you can select what the SubStyle will look like.
If you pick "Current" it will be a copy of the SubStyle you are editing.
If you select "Template" then the SubStyle will be the one that you specify below in the drop-down menu.
If you choose the last option "Other" you will be able to import a SubStyle from a completely different theme.

To rename a SubStyle you need to right-click on the name of the SubStyle in the Part Tree.
By clicking on "Rename" you will be able to change the SubStyle's name.
Similarly by clicking on "Delete" you will be able to delete the SubStyle.

BE VERY CAREL when deleting a SubStyle because the process cannot be reverted.
StyleBuilder will delete the SubStyle and all of its graphics permanently.


VI. Editing the Properties of the Theme:


In your theme folder you will notice the .xml files that carry the same names as your SubStyles.
These .xml files contain practically all the settings each of your SubStyles require.
You don't need an .xml editor to open these files; simply use Notepad.exe to edit them.

[see the .xml file image below]

Now open one of these .xml files and take a look at its contents.
To do this you need to right-click the file and select "Open With".
In the window double click on "Notepad".

Tthe file you opened will be structure hierarchically (just like the Part Tree in StyleBuilder).
The structure resembles the following:

<Root>
<Group name=Groupname>
<Class name=ClassName>
<Part name=PartName>
<Property name=PropertyName>
</Property>
</Part>
</Class>
</Group>
</Root>

"Groups" correspond to the large components mentioned in Section IV.
Groups include:

Substitution, General, ExplorerBar, Placesbar, Start, Startmenu,
TaskBand, TastBandGroupMenu, TaskBandVert, TaskBar, TaskBarVert,
TrayNotify, TrayNotifyHoriz, TrayNotifyHorizOpen, TrayNotifyVert,
and TrayNotifyVertOpen.

As you might have noticed these main components can be found in the Part Tree under "Values".

Under these groups you will find Classes that are smaller, more specific groups.
And under Classes you will find individual Parts that in turn have their own Properties.

When working with .xml files the only values that need changing will be individual "Properties".
Editing is very simple in .xml files.
You first need to navigate through the file and find the Class in which the Property resides.
When you find the Property (the find command should save you a lot of time) you simply change its value.

For example the Start Button font that we changed earlier in StyleBuilder can also be changed in the .xml file.
You just need to scroll down until you find <GROUP Name="Start"> and under that, <CLASS Name="Button">.
Under the Button class you will see <Property Name="TextColor" Value="255 255 255"/>.
This tells you that the TextColor property has a value of 255 255 255 .
This is an RGB color value; to change it simply delete the old value and replace it with some other valid RGB color.

Since we talked about changing Properties now we can move on to changing graphical elements.

[voltaic]

VII. Editing the Graphics of the Theme:


Editing the graphical parts of the theme is done easier in StyleBuilder.
To do this you will need an image editing application.
By default you would have Paint.exe installed but Paint will only be enough for very simple adjustments.
Strong editing applications such as Photoshop are almost necessary if you want to create original themes.

To make StyleBuilder integrate with your editing application you first need to setup StyleBuilder.
To do this click on "Tools" and then choose "Options" in your toolbar menu.
In the Options window click on "New" and then give the application any name you want.
Below that, in the Program field, enter the path of the application's executable file.
You can also click on the "..." browse button to select the location.
After you're done click ok.
Now whenever you try to edit some image in StyleBuilder, the image will open in the application you just specified.


In order to edit an image you first have to find the Property it is linked to.
To do this take a look at the Preview Window in StyleBuilder and click on something you'd like to edit.
In this example we will edit the Start Button.
First click on "Windows & Toolbars" in the Shortcut Bar, then click on the Start Button in the Preview Window.

Take a look at the Properties Tab below.
Click on the ImageFile property and click on "Edit" in the Properties Window.
Your image editor will load the Start Button image.
Make some changes to the button and then save the image.

When you switch back to StyleBuilder you will see that the Preview Window will display the new Start Button.
With this method will eventually edit every component of the theme to your liking.

Another way to do this is by right-clicking on the image directly in the Preview Window.
In the small menu that opens you can click on "Edit" to achieve the same result as above.

In other cases you may want to use a completely different graphic you created some other time.
To use this graphic instead of the default one you will need to click on the part in the Preview Window or in the Part Tree.
Then in the Properties Tab you need to click on the "ImageFile" property.
In the Property Window click "Choose" and then find the image you'd like to use.

MAKE SURE that the new image you are using is in the correct folder.
By this I mean the image you are using should be in the folder that has the same name as the SubStyle you are working on.

One thing that you should know when editing images is the transparent color.
This color is referred as magic pink, and has a value of RGB: 255 0 255 .
If found in a .bmp image this color will be interpreted as transparent.
For example if you use a Start Button graphic that is filled with magic pink, the Start Button of your theme will be invisible.

To make sure that transparencies work in your theme, you need to have "Transparent" property enabled.
In parts that contain images you can manually add "Transparent" by clicking on "Add Property" in the Properties Tab.
Once added make sure the property is enabled.
To enable "Transparent" you need to first click on it, and then place a check mark next "Transparent" in the Properties Window.
When changing this property in an .xml file its value will be either "True" or "False".
In most image-containing parts the "Transparent" property will already be enabled.

The second file type that you will be using is .png
.png files are interpreted differently than .bmp files.
Only certain parts of your theme will require .png files.
If you see that a part has a .png file please try not to replace it with a .bmp file.
This is also valid for part that use .bmp files.
Although it may certainly work, using the image type that is there by default is recommended.

Transparencies in .png files work differently than .bmp files.
In .pngs magic pink WILL NOT be interpreted as transparent.
Instead you will need to use Alpha Channels that contain transparency data in .png files.
.pngs however are not used for transparent parts by default.
Since this can be considered a little more advanced than the scope of this tutorial I will not discuss transparencies in .png files.

And finally you should know about image resizing and image margins.
Almost every part that uses graphics will have "ContentMargins" and "SizignMargins".
These properties tell the operating system how to treat images when item placement and resizing is necessary.
"ContentMargins" indicate the portion of the given image that will actually contain functional parts.
For example the start text on the start button will be drawn inside StartButton.bmp's "ContentMargins".
The operating system WILL NOT draw anything that happens to be outside these margins.

"SizingMargins" on the other hand determine the area inside the image that will be resized.
For example if a captionbar includes complicated graphics we would not want the operating system to stretch these graphics.
Because doing so would distort the graphics.
For this reason images that will be resized need to have some uniform, repeating areas that can be either tiled or stretched.
To determine these areas that will be tiled or stretched we use the "SizingMargins" property.
All parts of the image that are OUTSIDE the "SizingMargins" will remain unchanged.
All parts of the image that are OUTSIDE the "SizingMargins" will not be resized or stretched.

And finally we can use the "SizingType" property to tell the operating system how to resize the image.
This property can be set to TrueSize, Stretch, Tile, TileHorz, TileVert, TileCenter.
TrueSize, as it implies, will only use the true size of the image.
This will effectively disable resizing.
When setting "SizingType" to TrueSize make sure the part is not a resized part (StartButton for example).
Stretch on the other hand will simply extend the image to fit the given space.
This value can be used if the image resembles a horizontal pipe.
Stretch can be particularly useful in the Caption area.
All the Tile values on the other hand are used to tile the given area.
Use these if you want to want to have a repeating pattern.

If you are still unsure how "ContentMargins" "SizingMargins" and "SizingType" work, try to change some values and see what happens.
The Part Window can especially be useful because the parts drawn in the part window can be resized by hand.
Just drag the lower right corners of the images to resize them inside the Part Window.
This way you can see for yourself how each of these properties affect part graphics.

[voltaic]

VIII. Editing an Existing Theme:


You may sometimes want to edit some minor parts of a theme you have downloaded.
To do this you will first need to import the .msstyles file so that you can edit its individual parts.
In StyleBuilder you need to click on "File" and then "Import" in your menu bar (top).

In the "Import .msstyles" window you need to specify the location of the theme in the first field.
Then you need to specify the destination folder in which the contents of the theme will be extracted.

Again, treat this like a new theme and use an empty folder.
When you click ok the components of the theme will be imported into the folder you specified.

To edit the parts of the theme you have imported you will need to follow the basic steps I talked about in sections V. VI. and VII.

One difficulty that you might encounter in the process may be certain properties that have values that include $$.
Values such as $StartButtonFont$ are "Substitution Values".
This means that these values are specified under "Normal -> Substitution", and "Values -> Substitution" found in the Part Tree.
To change these substitution values you will first need to go to the "Substitution" groups I specified above.
Then in the Properties Tab and Properties Window you can change their values.

Most of the Substitution values can be manually edited in the .sb file in your theme directory.
The .sb file will be named the same as your theme (for example Luna.sb).
The .xml files only contain a handful of Substitution values.


IX. Saving the Finished Theme:


Before saving your theme you may also want to change the theme's documentation.
If this is a unique theme you have created you may want to click on "Documentation" in the Part Tree.
In the Properties Tab you may fill out the necessary information such as Author, DisplayName, URL, Copyright etc.
This is done so that some other person editing your theme will know who initially created the theme.

Once you are satisfied with the theme you have created or modified you can save it for later use.
By clicking on "File" and then "Save As" you can save your theme in a new directory.
By doing this you can also change the name of your theme.
When you do a "Save As" all of the components of your theme will be created in the new directory (including images).

StyleBuilder by default saves changes as you work on a theme.
This can be a good or bad thing depending on your view.
If you do not want to save the theme in a new location you can simply click on "File" and then "Save".
However it is very likely that StyleBuilder already saved all the changes you have made in the meantime.
It is therefore IMPORTANT that you backup you theme time to time if you are afraid of messing it up.


X. Compiling and Testing the Finished Theme:


After saving your theme you would certainly want to test it and see how it looks.
To do this you will need to click on "Actions" and then "Compile" in the toolbar menu.
Doing this will place all the files and images of your theme into a single .msstyles files.
Depending on the number of SubStyles you have the process may take seconds or couple of minutes at most.
The compiled .msstyles file will be created in your theme directory.
You can then switch back to the directory, double click on the .msstyles file and apply it.
This is one way of testing your theme for any bugs and errors.

Another way you can use to test your theme is the "Test System Style" option under "Tools" in your toolbar.
I personally do not prefer this method, as it does not work correctly with my themes.
You may need to try it out for yourself to see if you like it.

If you notice errors or bugs in your theme you may need to go back to StyleBuilder and figure out what properties are causing them.
This will always happen and can be considered the most time consuming part of skinning.
As you add and change things to your theme I suggest you frequently compile it and test for defects.

[voltaic]

XI. Credits:


StyleBuilder Help file was used to check the names of different components.
Other than that, my own knowledge.


XII. Additional Notes:


Additional feedback/ideas/bugs would be greatly appreciated.
If you have any suggestions/additions/corrections please post them.
If there is something I have missed please say so.
I will be updating the tutorial as necessary.



~volt

[Michael]

great tutorial.

[Predator]

Yeah great

[190087262457]

I went through the tutorial, and I did everything and got my theme exactly how I wanted it. So I compiled it, but when I double click the .msstyles, all it does is takes me to my Display Properties in the Appearance Tab and doesn't load anything new into the fields. Help, please?

[Michael]

Is this the first tiem you ever tried to put a theme onto your system? if so make sure you patch the UXTHEME.DLL file.

[brutalchris]

How do you add a wallpaper to a theme so when you apply a msstyle the wallpaper you include is automatically set as the desktop wallpaper? Is this done in stylebuilder or resource hacker or what? and could someone explain how to do this? I see ZERO tutorials on this yet everyone seems to know where or how to do it... mind boggling. Thanks.