[This documentation is preliminary and is subject to change.]
This document discusses the format of Theme (.theme) files used in Windows 7, Windows Vista, and Microsoft Windows XP. 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.
Windows 7 supports new features including the Desktop Background Slideshow. Unrecognized sections of .theme files are ignored by previous versions of the operating system. A new file format, .themepack, has also been introduced with Windows 7 to help users share themes.
The following topics are discussed in this article.
Creating a Theme File
A .theme file enables you to change the appearance of certain desktop elements. You can create or modify a .theme file in two ways:
- Modify personalization or display settings in Control Panel and save the settings as a .theme file. See your Windows Help for instructions.
- Create a .theme file manually for a greater level of control over the details of your theme.
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 do this with a theme pack.
Description of a Theme File
Theme files have a number of required and optional sections. The following describe the sections of .theme files and provide examples of how to specify changes for the different elements.
[Theme] Section
Note This section is optional. If you do not include this section in your .theme file, the system uses default settings.
The [Theme] section identifies the name of your custom theme and specifies your theme's brand logo and desktop icons.
The first part of the [Theme] section contains the following two elements:
| Element | Description |
|---|
DisplayName=@module,-stringId
example: DisplayName=@themeui.dll,-2013 | DisplayName is the theme name that will show up in the Personalization Control Panel. It can be a string or a reference to a localized name.
This field is optional. If it is missing, the theme filename is used as the theme name. |
BrandImage=path to image
example: BrandImage=c:\Fabrikam\brand.png | Windows 7
BrandImage specifies the path to a branded graphic file that is incorporated in the theme preview in the Personalization Control Panel.
The icon graphic must be a PNG file. The graphic is scaled to 80x240 pixels, so it is recommended that you provide an image of that size. The Theme gallery respects the transparent regions of your brand icon.
This field is optional. If it is missing, no logo is displayed as the theme icon. |
The rest of the [Theme] section specifies custom icons for desktop features like My Computer, My Documents, Network, and Recycle Bin. If you do not specify custom desktop icons, the desktop displays the system default desktop icons.
The 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
The following are values for the default desktop icons.
; Computer - SHIDI_SERVER
[CLSID\{20D04FE0-3AEA-1069-A2D8-08002B30309D}\DefaultIcon]
DefaultValue=%SystemRoot%\System32\imageres.dll,-109
; Documents - IDI_MYDOCS
[CLSID\{59031A47-3F72-44A7-89C5-5595FE6B30EE}\DefaultIcon]
DefaultValue=%SystemRoot%\System32\shell32.dll,-235
; Network - SHIDI_MYNETWORK
[CLSID\{F02C1A0D-BE21-4350-88B0-7367FC96EF3C}\DefaultIcon]
DefaultValue=%SystemRoot%\System32\imageres.dll,-25
; Recycle Bin - SHIDI_RECYCLERFULL SHIDI_RECYCLER
[CLSID\{645FF040-5081-101B-9F08-00AA002F954E}\DefaultIcon]
Full=%SystemRoot%\System32\imageres.dll,-54
Empty=%SystemRoot%\System32\imageres.dll,-55
[Control Panel\Colors] Section
Note This section is optional. If you do not include this section in your .theme file, the system uses default settings. If your theme uses Aero Glass, you should avoid overriding the default values in this section.
The color of elements, such as scrollbars, text, and buttons, are customizable. The .theme file specifies the RGB values to change for these elements. The values override the default values of the visual style and are used when your theme is based on Windows Classic, Windows 7 Basic, or High Contrast themes.
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
[Control Panel\Cursors] Section
Note This section is optional. If you do not include this section in your .theme file, the system uses default 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
[Control Panel\Desktop] Section
Note This section is required. If you do not include this section in your .theme file, the system ignores your Theme and does not display the Theme in Control Panel.
You can create custom wallpaper for the desktop and specify a path to the graphics file. 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 .tif file.
TileWallpaper=0
; 0: The wallpaper picture should not be tiled
; 1: The wallpaper picture should be tiled
WallpaperStyle=2
; 0: The image is centered if TileWallpaper=0 or tiled if TileWallpaper=1
; 2: The image is stretched to fill the screen
; 6: The image is resized to fit the screen while maintaining the aspect
ratio.
; 10: The image is resized and cropped to fill the screen while maintaining
the aspect ratio.
[Slideshow] Section
Windows 7 and later.
Note This section is optional. If you do not include this section in your .theme file, the system uses default Desktop Appearance settings. If you include this section, you must specify slideshow settings here.
Your theme's background can be a slideshow either of images stored locally or of images served by an RSS feed. The [Slideshow] section of the file contains the following attributes:
| Attribute | Description |
|---|
| Interval=number of milliseconds | Required. Interval is a number that determines how often the background changes. It is measured in milliseconds. |
| Shuffle=0 or 1 | Required. Shuffle identifies whether the background shuffles.
0 = Disabled
1 = Enabled |
| RSSFeed=URL to RSS feed | Required if ImagesRootPath is not specified. RSSFeed specifies an RSS feed to use as the background slideshow. For the feed to work, you need to reference high-resolution images adhering to the "enclosures" standard used by the Windows RSS Platform. Because of this limitation, .theme files that include an RSS feed must be created manually.
Note You cannot specify both an RssFeed and ImagesRootPath. |
| ImagesRootPath=path to image folder | Required if RSSFeed is not specified. ImagesRootPath specifies a path to a set of images you want to use as the background slideshow. Images in subfolders are not included in the slideshow.
ImagesRootPath supports Environment Variable substitutions in the path.
Note You cannot specify both an RssFeed and ImagesRootPath. |
| ItemNPath=path(s) to specific image(s) | For use with ImagesRootPath. ItemNPath specifies paths to specific images, so that you can limit the slideshow to particular images instead of all images in a folder. If no paths are specified, all images in the ImagesRootPath path are used in the slideshow, including images added after creating and installing the theme.
ItemNPath supports Environment Variable substitutions in the path.
|
The following examples show how a .theme file specifies the slideshow to include a set of images stored locally.
[Slideshow]
Interval=1800000
Shuffle=1
ImagesRootPath=%SystemRoot%\Web\Wallpaper\
[Slideshow]
Interval=1800000
Shuffle=1
ImagesRootPath=c:\fabrikam\wallpaper
Item0Path=c:\fabrikam\wallpaper\ocean.jpg
Item1Path=c:\fabrikam\wallpaper\mountain.jpg
Item2Path=c:\fabrikam\wallpaper\river.jpg
The following example is a template for a .theme file that creates a desktop background slideshow using images from an RSS feed. Follow these steps to customize the template:
- Copy the following example and paste it into a text editor.
- Replace {themename} with the name you want to appear in the Personalization Control Panel themes gallery.
- Replace {rssfeedurl} with the full path to a compatible RSS feed.
- Save the changes as a file with the ".theme" extension.
[[Theme]
DisplayName={themename}
[Slideshow]
Interval=1800000
Shuffle=1
RssFeed={rssfeedurl}
[Control Panel\Desktop]
TileWallpaper=0
WallpaperStyle=10
Pattern=
[Control Panel\Cursors]
AppStarting=%SystemRoot%\cursors\aero_working.ani
Arrow=%SystemRoot%\cursors\aero_arrow.cur
Crosshair=
Hand=%SystemRoot%\cursors\aero_link.cur
Help=%SystemRoot%\cursors\aero_helpsel.cur
IBeam=
No=%SystemRoot%\cursors\aero_unavail.cur
NWPen=%SystemRoot%\cursors\aero_pen.cur
SizeAll=%SystemRoot%\cursors\aero_move.cur
SizeNESW=%SystemRoot%\cursors\aero_nesw.cur
SizeNS=%SystemRoot%\cursors\aero_ns.cur
SizeNWSE=%SystemRoot%\cursors\aero_nwse.cur
SizeWE=%SystemRoot%\cursors\aero_ew.cur
UpArrow=%SystemRoot%\cursors\aero_up.cur
Wait=%SystemRoot%\cursors\aero_busy.ani
DefaultValue=Windows Aero
Link=
[VisualStyles]
Path=%SystemRoot%\resources\themes\Aero\Aero.msstyles
ColorStyle=NormalColor
Size=NormalSize
ColorizationColor=0X6B74B8FC
Transparency=1
[MasterThemeSelector]
MTSM=DABJDKT
[Metrics] Section
Note This section is optional. If you do not include this section in your .theme file, the system uses default visual style settings.
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] Section
Note This section is required. If you do not include this section in your .theme file, the system ignores your Theme and does not display the Theme in Control Panel.
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.
Windows Vista / Windows 7: When the path points to Aero.msstyle, you can specify the desired Glass Color and Transparency values, as shown in the following example.
[VisualStyles]
Path=%SystemRoot%\resources\Themes\Aero\Aero.msstyles
ColorStyle=NormalColor
Size=NormalSize
ColorizationColor=0X7298844C
Transparency=1
If the ColorizationColor and Transparency values exactly match a system color, the Control Panel displays the system name for the color. Otherwise, the color is labeled "Custom."
The following shows a VisualStyles section for the Windows Basic theme.
[VisualStyles]
Path=%ResourceDir%\Themes\Aero\Aero.msstyles
Composition=0
ColorStyle=NormalColor
Size=NormalSize
ColorizationColor=0x45409efe
Transparency=1
The following shows a VisualStyles section for the Windows Classic theme.
[VisualStyles]
Path=
ColorStyle=@themeui.dll,-854
Size=@themeui.dll,-2019
Transparency=0
The following shows a VisualStyles section for a High Contrast Black theme.
[VisualStyles]
Path=
ColorStyle=@themeui.dll,-852
Size=@themeui.dll,-2019
Transparency=0
[AppEvents] Sections (Sounds)
Note This section is optional. If you do not include this section in your .theme file, the system uses default sound settings.
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]
DefaultValue=%WinDir%media\chord.wav
[AppEvents\Schemes\Apps\.Default\SystemExit]
DefaultValue=%WinDir%media\tada.wav
[AppEvents\Schemes\Apps\.Default\SystemHand]
DefaultValue=%WinDir%media\chord.wav
[AppEvents\Schemes\Apps\.Default\SystemQuestion]
DefaultValue=%WinDir%media\chord.wav
[AppEvents\Schemes\Apps\.Default\SystemStart]
DefaultValue=%WinDir%media\The Microsoft Sound.wav
[AppEvents\Schemes\Apps\Explorer\EmptyRecycleBin]
DefaultValue=%WinDir%media\ding.wav
[Boot] Section
Note This section is optional. If you do not include this section in your .theme file, no screen saver is used.
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
[MasterThemeSelector] Section
Note This section is required. If you do not include this section in your .theme file, the system ignores your Theme and does not display the Theme in Control Panel.
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=My Current Theme
BrandImage=c:\Fabrikam\brand.png
; 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\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]
DefaultValue=%WinDir%media\ding.wav
[AppEvents\Schemes\Apps\.Default\AppGPFault]
DefaultValue=
[AppEvents\Schemes\Apps\.Default\Maximize]
DefaultValue=
[AppEvents\Schemes\Apps\.Default\MenuCommand]
DefaultValue=
[AppEvents\Schemes\Apps\.Default\MenuPopup]
DefaultValue=
[AppEvents\Schemes\Apps\.Default\Minimize]
DefaultValue=
[AppEvents\Schemes\Apps\.Default\Open]
DefaultValue=
[AppEvents\Schemes\Apps\.Default\RestoreDown]
DefaultValue=
[AppEvents\Schemes\Apps\.Default\RestoreUp]
DefaultValue=
[AppEvents\Schemes\Apps\.Default\RingIn]
DefaultValue=
[AppEvents\Schemes\Apps\.Default\Ringout]
DefaultValue=
[AppEvents\Schemes\Apps\.Default\SystemAsterisk]
DefaultValue=%WinDir%media\chord.wav
[AppEvents\Schemes\Apps\.Default\SystemDefault]
DefaultValue=
[AppEvents\Schemes\Apps\.Default\SystemExclamation]
DefaultValue=%WinDir%media\chord.wav
[AppEvents\Schemes\Apps\.Default\SystemExit]
DefaultValue=
[AppEvents\Schemes\Apps\.Default\SystemHand]
DefaultValue=%WinDir%media\chord.wav
[AppEvents\Schemes\Apps\.Default\SystemQuestion]
DefaultValue=%WinDir%media\chord.wav
[AppEvents\Schemes\Apps\.Default\SystemStart]
DefaultValue=
[AppEvents\Schemes\Apps\Explorer\EmptyRecycleBin]
DefaultValue=%WinDir%media\ding.wav
[AppEvents\Schemes\Apps\.Default\Close]
DefaultValue=
[Slideshow]
Interval=1800000
Shuffle=1
ImagesRootPath=c:\fabrikam\wallpaper
Item0Path=c:\fabrikam\wallpaper\ocean.jpg
Item1Path=c:\fabrikam\wallpaper\mountain.jpg
Item2Path=c:\fabrikam\wallpaper\river.jpg
[boot]
SCRNSAVE.EXE=%WinDir%\System32\logon.scr
[MasterThemeSelector]
MTSM=DABJDKT
ThemeColorBPP=4
[VisualStyles]
Path=%SystemRoot%\resources\Themes\Aero\Aero.msstyles
ColorStyle=NormalColor
Size=NormalSize
ColorizationColor=0X7298844C
Transparency=1
Installing Theme Files
When Windows is initialized, the operating system enumerates the following directories and subdirectories to identify available themes.
The registry key values are ignored and the REG_SZ data contains the path. Windows 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.
- Create a theme directory, such as %UserProfile%\AppData\Local\Microsoft\Windows\Themes\.
- Register the path to the theme directory in the InstalledThemes registry key.
- 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.
Theme Packs
Windows 7 and later. A theme pack is a .cab file that contains not only the .theme file but also the files needed to implement the theme on another computer, such as sound files and images. Users can create theme packs through the Personalization Control Panel.
Supported file types include the following:
| File type | Extension |
|---|
| Theme | .theme |
| Image | .jpg, .jpeg, .bmp, .dib, .tif, .png |
| Sound | .wav |
| Mouse cursor | .cur, .ani |
| Desktop icon | .ico |
| Brand logo | .png |
Related Topics