Creating and Installing Theme Files

This document discusses the format of .theme files used in Microsoft Windows XP. Microsoft Plus! for Windows 95 introduced .theme files. A .theme file is a .ini text file that is divided into sections, which specify visual elements that appear on a Windows desktop. Section names are wrapped in brackets ([]) in the .ini file.

The following topics are discussed in this article.

    * Creating a Theme File
    * Example of a Theme File
    * Installing Theme Files

Creating a Theme File

A .theme file enables you to change the appearance of certain desktop elements. The following steps describe the easiest way to create a .theme file.

  1. In Control Panel, click the Display icon. Make changes to the settings you want, such as background, screen saver, and icons.
  2. Click Apply.
  3. Select the Themes tab and click Save As....
  4. To make your theme available to users of your application, you must supply your .theme file, as well as the background picture, screen saver, and icons files.

You can also modify your .theme file manually for a greater level of control over the details of your theme. The following topics describe the sections of .theme files and provide examples of how to specify changes for the different elements.
Desktop Features Icons

The desktop, which is the screen you see when you log on to Windows, is the home of icons for such features as My Computer, My Documents, and Recycle Bin. The first section of a .theme file specifies the icons to use for these desktop features. Following are two examples of how a .theme file sets the My Computer icon.

[CLSID\{20D04FE0-3AEA-1069-A2D8-08002B30309D}\DefaultIcon]
DefaultValue=%ThemeDir%Inside your Computer My Computer.ico

; My Computer
[CLSID\{20D04FE0-3AEA-1069-A2D8-08002B30309D}\DefaultIcon]
DefaultValue=%WinDir%explorer.exe,0
screen saver

Colors

If .theme files are installed on a computer, the user can open Control Panel, click the Appearance and Themes icon and select a theme. When the user selects a theme, the theme can change certain aspects of the desktop appearance. One aspect that can be changed is the color of elements such as scrollbars, text, and buttons. The .theme file specifies the RGB values for the elements to change. Following is an example of how colors are set.

[Control Panel\Colors]
ActiveTitle=10 36 106
Background=166 202 240
Hilight=10 36 106
HilightText=255 255 255
TitleText=255 255 255
Window=255 255 255
WindowText=0 0 0
Scrollbar=212 208 200
InactiveTitle=128 128 128
Menu=212 208 200
WindowFrame=0 0 0
MenuText=0 0 0
ActiveBorder=212 208 200
InactiveBorder=212 208 200
AppWorkspace=128 128 128
ButtonFace=212 208 200
ButtonShadow=128 128 128
GrayText=128 128 128
ButtonText=0 0 0
InactiveTitleText=212 208 200
ButtonHilight=255 255 255
ButtonDkShadow=64 64 64
ButtonLight=212 208 200
InfoText=0 0 0
InfoWindow=255 255 225
GradientActiveTitle=166 202 240
GradientInactiveTitle=192 192 192

Cursors

A theme can also change the appearance of cursors. To do so, you create .cur files to replace the default Windows cursors. The following example is from a .theme file that defines the cursors for a theme called Inside Your Computer.

[Control Panel\Cursors]
Arrow=%ThemeDir%Inside Your Computer arrow.cur
Help=%ThemeDir%Inside Your Computer help.cur
AppStarting=%ThemeDir%Inside Your Computer wait.ani
Wait=%ThemeDir%Inside Your Computer busy.ani
NWPen=%ThemeDir%Inside Your Computer pen.cur
No=%ThemeDir%Inside Your Computer no.cur
SizeNS=%ThemeDir%Inside Your Computer size NS.cur
SizeWE=%ThemeDir%Inside Your Computer size WE.cur
Crosshair=%ThemeDir%Inside Your Computer cross.cur
IBeam=%ThemeDir%Inside Your Computer beam.cur
SizeNWSE=%ThemeDir%Inside Your Computer size NWSE.cur
SizeNESW=%ThemeDir%Inside Your Computer size NESW.cur
SizeAll=%ThemeDir%Inside Your Computer move.cur
UpArrow=%ThemeDir%Inside Your Computer up.cur
DefaultValue=Windows default

Desktop Appearance

You can create custom wallpaper for the desktop and specify a path to the graphics file in a .theme file. Additionally, this section of the .theme file can specify whether the screen saver is active. The following example shows how to do modify the desktop appearance.

[Control Panel\Desktop]
Wallpaper=%WinDir%web\wallpaper\Professional.jpg
;The path to the wallpaper picture can point to a
;.bmp, .gif, .jpg, .png, or .htm file.

TileWallpaper=0
;A value of 0 means that the wallpaper picture should 
;not be tiled and 1 means that it should. 

WallpaperStyle=2
;A value of 2 means that the wallpaper picture should be
;stretched and 0 means that it should be centered.

Pattern=(None)
ScreenSaveActive=1

Note  The elements, tilewallpaper and center, are not available with wallpaper that uses a .htm file. Windows XP supports .htm wallpapers but Microsoft .NET and later, will no longer support them.
System Metrics

You can specify system metrics in a .theme file. System metrics are the dimensions of various display elements, such as the window border width, icon height, or scrollbar width. The NonclientMetrics and IconMetrics values are binary structures defined by NONCLIENTMETRICS and ICONMETRICS in winuser.h. Following is an example of how to change system metrics.

[Control Panel\Desktop\WindowMetrics]

[Metrics]
IconMetrics=76 0 0 0 139 0 0 0 139 0 0 0 1 0 0 0 245
255 255 255 0 0 0 0 0 0 0 0 0 0 0 0 144 1 0 0 0 0 0 0
0 0 0 0 84 97 104 111 109 97 0 119 0 0 7 0 0 0 0 0 216
31 7 0 28 52 1 1 216 31 7 0 176 36 1 1
NonclientMetrics=84 1 0 0 1 0 0 0 16 0 0 0 16 0 0 0 18
0 0 0 18 0 0 0 245 255 255 255 0 0 0 0 0 0 0 0 0 0 0 0
188 2 0 0 0 0 0 0 0 0 0 0 84 97 104 111 109 97 0 0 0 0
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 12 0 0 0
15 0 0 0 245 255 255 255 0 0 0 0 0 0 0 0 0 0 0 0 188 2
0 0 0 0 0 0 0 0 0 0 84 97 104 111 109 97 0 0 80 37 11
0 0 0 0 0 140 221 6 0 227 115 247 119 2 40 11 0 7 0 0
0 18 0 0 0 18 0 0 0 245 255 255 255 0 0 0 0 0 0 0 0 0
0 0 0 144 1 0 0 0 0 0 0 0 0 0 0 84 97 104 111 109 97 0
0 0 0 0 0 60 222 6 0 50 71 252 119 120 1 7 0 76 73 252
119 8 6 7 0 245 255 255 255 0 0 0 0 0 0 0 0 0 0 0 0
144 1 0 0 0 0 0 0 0 0 0 0 84 97 104 111 109 97 0 119 0
0 7 0 120 1 7 0 120 1 7 0 40 37 11 0 120 1 7 0 120 1 7
0 245 255 255 255 0 0 0 0 0 0 0 0 0 0 0 0 144 1 0 0 0
0 0 0 0 0 0 0 84 97 104 111 109 97 0 0 92 1 0 0 136 4
0 0 40 37 1 1 0 0 7 0 184 221 6 0 46 75 232 119

Visual Styles

You can supply specific information concerning the size and color of desktop elements in .mstheme files. The color and size sections of .theme files can be replaced by .mstheme files which enable you to modify desktop elements in more detail. These files are specified in the visual styles section of a .theme file. Following is an example of a visual styles section.

[VisualStyles]
Path=%ResourceDir%\Themes\Professional\Professional.mstheme
ColorStyle=Default
Size=Normal

Adding a Path element to a .mstheme file is optional. If you supply a path, you should remove the metrics and color sections from the .theme file. When these sections are removed, the colors, fonts, and sizes for a theme come from the .mstheme file and match the .mstheme author's intent. Failing to remove the metric and color sections can cause Windows or applications to have drawing problems.
Application Events

The user can select the Sounds, Speech, and Audio Devices icon in Control Panel to associate sounds with events that occur in applications. For example, a .wav file can play when an application is opened. A .theme file can specify .wav files to replace the default ones. The following example shows how to do this.

[AppEvents\Schemes\Apps\.Default\SystemExclamation\.Current]
DefaultValue=%WinDir%media\chord.wav

[AppEvents\Schemes\Apps\.Default\SystemExit\.Current]
DefaultValue=%WinDir%media\tada.wav

[AppEvents\Schemes\Apps\.Default\SystemHand\.Current]
DefaultValue=%WinDir%media\chord.wav

[AppEvents\Schemes\Apps\.Default\SystemQuestion\.Current]
DefaultValue=%WinDir%media\chord.wav

[AppEvents\Schemes\Apps\.Default\SystemStart\.Current]
DefaultValue=%WinDir%media\The Microsoft Sound.wav

[AppEvents\Schemes\Apps\Explorer\EmptyRecycleBin\.Current]
DefaultValue=%WinDir%media\ding.wav

Other

In the [other] section, you can set a skin file (.wmz) to use with the Microsoft Windows Media Player. The following example shows this.

[other]
WindowsMediaPlayerSkin=Holiday.wmz

Boot

In the .theme file, you can specify the screen saver for Windows to use. The following example shows this.

[boot]
SCRNSAVE.EXE=%WinDir%\System32\ssflwbox.scr

Master Theme Selector

The master theme selector section of the .theme file should always be included as a tag that indicates the file is valid. You do not have a choice of values for this parameter. The following shows this.

[MasterThemeSelector]
MTSM=DABJDKT
ThemeColorBPP=4

Example of a Theme File

The following example shows a complete .theme file.

[Theme]
DisplayName=@themeui.dll,-2016

; My Computer
[CLSID\{20D04FE0-3AEA-1069-A2D8-08002B30309D}\DefaultIcon]
DefaultValue=%WinDir%explorer.exe,0

; My Documents
[CLSID\{450D8FBA-AD25-11D0-98A8-0800361B1103}\DefaultIcon]
DefaultValue=%WinDir%SYSTEM32\mydocs.dll,0

; My Network Places
[CLSID\{208D2C60-3AEA-1069-A2D7-08002B30309D}\DefaultIcon]
DefaultValue=%WinDir%SYSTEM32\shell32.dll,17

; Recycle Bin
[CLSID\{645FF040-5081-101B-9F08-00AA002F954E}\DefaultIcon]
full=%WinDir%SYSTEM32\shell32.dll,32
empty=%WinDir%SYSTEM32\shell32.dll,31

[Control Panel\Colors]
ActiveTitle=10 36 106
Background=58 110 165
Hilight=10 36 106
HilightText=255 255 255
TitleText=255 255 255
Window=255 255 255
WindowText=0 0 0
Scrollbar=212 208 200
InactiveTitle=128 128 128
Menu=212 208 200
WindowFrame=0 0 0
MenuText=0 0 0
ActiveBorder=212 208 200
InactiveBorder=212 208 200
AppWorkspace=128 128 128
ButtonFace=212 208 200
ButtonShadow=128 128 128
GrayText=128 128 128
ButtonText=0 0 0
InactiveTitleText=212 208 200
ButtonHilight=255 255 255
ButtonDkShadow=64 64 64
ButtonLight=212 208 200
InfoText=0 0 0
InfoWindow=255 255 225
GradientActiveTitle=166 202 240
GradientInactiveTitle=192 192 192

[Control Panel\Cursors]
Arrow=
Help=
AppStarting=
Wait=
NWPen=
No=
SizeNS=
SizeWE=
Crosshair=
IBeam=
SizeNWSE=
SizeNESW=
SizeAll=
UpArrow=
DefaultValue=Windows default

[Control Panel\Desktop]
Wallpaper=(None)
TileWallpaper=0
WallpaperStyle=2
Pattern=(None)
ScreenSaveActive=0

[AppEvents\Schemes\Apps\.Default\.Default\.Current]
DefaultValue=%WinDir%media\ding.wav

[AppEvents\Schemes\Apps\.Default\AppGPFault\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\.Default\Maximize\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\.Default\MenuCommand\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\.Default\MenuPopup\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\.Default\Minimize\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\.Default\Open\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\.Default\RestoreDown\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\.Default\RestoreUp\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\.Default\RingIn\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\.Default\Ringout\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\.Default\SystemAsterisk\.Current]
DefaultValue=%WinDir%media\chord.wav

[AppEvents\Schemes\Apps\.Default\SystemDefault\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\.Default\SystemExclamation\.Current]
DefaultValue=%WinDir%media\chord.wav

[AppEvents\Schemes\Apps\.Default\SystemExit\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\.Default\SystemHand\.Current]
DefaultValue=%WinDir%media\chord.wav

[AppEvents\Schemes\Apps\.Default\SystemQuestion\.Current]
DefaultValue=%WinDir%media\chord.wav

[AppEvents\Schemes\Apps\.Default\SystemStart\.Current]
DefaultValue=

[AppEvents\Schemes\Apps\Explorer\EmptyRecycleBin\.Current]
DefaultValue=%WinDir%media\ding.wav

[AppEvents\Schemes\Apps\.Default\Close\.Current]
DefaultValue=

[Control Panel\Desktop\WindowMetrics]

[Metrics]
IconMetrics=76 0 0 0 139 0 0 0 139 0 0 0 1 0 0 0 245
255 255 255 0 0 0 0 0 0 0 0 0 0 0 0 144 1 0 0 0 0 0 0
0 0 0 0 84 97 104 111 109 97 0 119 0 0 7 0 0 0 0 0 216
31 7 0 28 52 1 1 216 31 7 0 176 36 1 1
NonclientMetrics=84 1 0 0 1 0 0 0 16 0 0 0 16 0 0 0 18
0 0 0 18 0 0 0 245 255 255 255 0 0 0 0 0 0 0 0 0 0 0 0
188 2 0 0 0 0 0 0 0 0 0 0 84 97 104 111 109 97 0 0 0 0
0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 12 0 0 0
15 0 0 0 245 255 255 255 0 0 0 0 0 0 0 0 0 0 0 0 188 2
0 0 0 0 0 0 0 0 0 0 84 97 104 111 109 97 0 0 80 37 11
0 0 0 0 0 140 221 6 0 227 115 247 119 2 40 11 0 7 0 0
0 18 0 0 0 18 0 0 0 245 255 255 255 0 0 0 0 0 0 0 0 0
0 0 0 144 1 0 0 0 0 0 0 0 0 0 0 84 97 104 111 109 97 0
0 0 0 0 0 60 222 6 0 50 71 252 119 120 1 7 0 76 73 252
119 8 6 7 0 245 255 255 255 0 0 0 0 0 0 0 0 0 0 0 0
144 1 0 0 0 0 0 0 0 0 0 0 84 97 104 111 109 97 0 119 0
0 7 0 120 1 7 0 120 1 7 0 40 37 11 0 120 1 7 0 120 1 7
0 245 255 255 255 0 0 0 0 0 0 0 0 0 0 0 0 144 1 0 0 0
0 0 0 0 0 0 0 84 97 104 111 109 97 0 0 92 1 0 0 136 4
0 0 40 37 1 1 0 0 7 0 184 221 6 0 46 75 232 119

[other]
WindowsMediaPlayerSkin=Holiday.wmz

[boot]
SCRNSAVE.EXE=%WinDir%\System32\logon.scr

[MasterThemeSelector]
MTSM=DABJDKT
ThemeColorBPP=4


Installing Theme Files

When Windows XP is initialized, it enumerates the following directories and subdirectories.

    * The ProgramFiles directory
    * First level subdirectories of %windir%\Resources\<LangID>\ using SHGetFolderPath (NULL, CSIDL_RESOURCES_LOCALIZED, NULL, O, szPath);
    * %AppData%\Microsoft\Windows\Themes
    * Any directories specified under the registry key

      Software

      Microsoft

      Windows

      CurrentVersion!

      Themes

      InstalledThemes

The registry key values are ignored and the REG_SZ data contains the path. Windows XP looks for .theme files in the InstalledThemes directory or its first level subdirectories.

A .theme file can specify a DisplayName value under the Themes section. If a DisplayName exists, it is used instead of the file name.

The %ThemeDir% token has been updated to make it easier for you to make a subdirectory for each theme; %ThemeDir% points to the legacy directory. If a theme file is not found in %ThemeDir%, the operating system attempts to load the file from the location of the .theme file.

Use the following steps to create an installer.

  1. Create a theme directory, such as %ProgramFiles%\Themes\.
  2. Register the path to the theme directory in the InstalledThemes registry key.
  3. Install each theme in its own subdirectory, for example: %ProgramFiles%\Themes\Holiday.theme, Holiday.jpg.

A .theme file has file associations; therefore theme installer applications can call ShellExecute on a .theme file to open the Display window in Control Panel to the specified theme. If the Display window in Control Panel is already open, the Themes tab will not be selected or its selection changed.