This document discusses the format of Theme (.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.
A new file format, .themepack, was introduced with Windows 7 to help users share themes. Themes can be selected in the Personalization Control Panel only in Windows 7 Home Premium or higher, or only on Windows Server 2008 R2 when the Desktop component is installed.
Fed up with the standard and dull desktop of yours? See this listing of the Rainmeter themes for Windows, and create your desktop personal.
The following topics are discussed in this article.
- Description of a Theme File
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 other users, 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=name or 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:Fabrikambrand.png | Windows 7 and laterBrandImage 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 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 Computer icon.
The following are values for the default desktop icons in Windows 7.
[Control PanelColors] 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 the Aero visual style, you should avoid overriding the default values in this section.
The color of elements, such as scroll bars, 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 PanelCursors] 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 Sports.
[Control PanelDesktop] 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 a custom desktop background and specify a path to the image file. The following example shows how to modify the desktop appearance.
[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 the desktop background image specified in the [Control PanelDesktop] section. If you include this section, you must specify slide show settings here.
Your theme's background can be a slide show 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 slide show. 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] |
| 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 slide show. Images in subfolders are not included in the slide show. ImagesRootPath supports Environment Variable substitutions in the path. [!Note] |
| ItemNPath=path(s) to specific image(s) | For use with ImagesRootPath. ItemNPath specifies paths to specific images, so that you can limit the slide show 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 slide show, including images added after creating and installing the theme. ItemNPath supports Environment Variable substitutions in the path. N is 0, 1, 2, and so on. |
The following examples show how a .theme file specifies the slide show to include a set of images stored locally.
The following example is a template for a .theme file that creates a desktop background slide show 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.
[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 scroll bar 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.
[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 .msstyles files. The color and size sections of .theme files can be replaced by .msstyles 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.
Adding a Path element to a .msstyles 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 .msstyles file and match the .msstyles 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.msstyles, you can specify the desired Glass Color, as shown in the following example.
Windows 7: When the path points to Aero.msstyles, you can also specify the desired Transparency value, as shown in the following example.
If the ColorizationColor and Transparency values exactly match a system color, the Personalization Control Panel displays the system name for the color. Otherwise, the color is labeled 'Custom.'
The following shows a VisualStyles section for the Windows 7 Basic theme.
The following shows a VisualStyles section for the Windows Classic theme.
The following shows a VisualStyles section for a High Contrast Black theme.
[Sounds] and [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 Sound 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.
Windows 7 and later: A sound scheme name can be specified instead of listing each sound separately.
The SchemeName value specifies the sound scheme name or the localized sound scheme name, as shown in the example above.
[Boot] Section
Note
Screen Savers are deprecated in the Windows 10 Anniversary Update and beyond.
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.
[MasterThemeSelector] Section
Note
Ifilex mac ifilex for mac. 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.
Example of a Theme File
The following example shows a complete .theme file.
Installing Theme Files
When Windows is initialized, the operating system enumerates the first-level subdirectories of %WinDir%Resources to identify available themes. The system default theme files are located in %WinDir%ResourcesThemes. The user theme files are stored in %WinDir%Users
A .theme file has file associations; therefore, theme installer applications can call ShellExecute on a .theme file to open the Personalization window in Control Panel to the specified theme.
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 |