This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
This topic explains how to configure your application to ensure that common controls are displayed in the user's preferred visual style.
This topic includes the following sections.
To enable your application to use visual styles, you must use ComCtl32.dll version 6 or later. Because version 6 is not redistributable, it is available only when your application is running on a version of Windows that contains it. Windows ships with both version 5 and version 6. ComCtl32.dll version 6 contains both the user controls and the common controls. By default, applications use the user controls defined in User32.dll and the common controls defined in ComCtl32.dll version 5. For a list of DLL versions and their distribution platforms, see Common Control Versions.
If you want your application to use visual styles, you must add an application manifest or compiler directive that indicates that ComCtl32.dll version 6 should be used if it is available.
An application manifest enables an application to specify which versions of an assembly it requires. In Microsoft Win32, an assembly is a set of DLLs and a list of versionable objects that are contained within those DLLs.
Manifests are written in XML. The name of the application manifest file is the name of your executable followed by the file name extension .manifest; for example, MyApp.exe.manifest. The following sample manifest shows that the first section describes the manifest itself. The following table shows the attributes set by the assemblyIdentity element in the manifest description section.
| Attribute | Description |
|---|---|
| version | Version of the manifest. The version must be in the form major.minor.revision.build (that is, n.n.n.n, where n <=65535). |
| processorArchitecture | Processor for which your application is developed. |
| name | Includes company name, product name and application name. |
| type | Type of your application, such as Win32. |
The sample manifest also provides a description of your application and specifies application dependencies. The following table shows the attributes set by the assemblyIdentity element in the dependency section.
| Attribute | Description |
|---|---|
| type | Type of the dependency component, such as Win32. |
| name | Name of the component. |
| version | Version of the component. |
| processorArchitecture | Processor that the component is designed for. |
| publicKeyToken | Key token used with this component. |
| language | Language of the component. |
Following is an example of a manifest file.
Important
Set the processorArchitecture entry to "X86" if your application targets the 32 bit Windows platform, or to "amd64" if your application targets the 64 bit Windows platform. You can also specify "*", which ensures that all platforms are targeted, as shown in the following examples.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
<assemblyIdentity
version="1.0.0.0"
processorArchitecture="*"
name="CompanyName.ProductName.YourApplication"
type="win32"
/>
<description>Your application description here.</description>
<dependency>
<dependentAssembly>
<assemblyIdentity
type="win32"
name="Microsoft.Windows.Common-Controls"
version="6.0.0.0"
processorArchitecture="*"
publicKeyToken="6595b64144ccf1df"
language="*"
/>
</dependentAssembly>
</dependency>
</assembly>
If you are using Microsoft Visual C++ 2005 or later, you can add the following compiler directive to your source code instead of manually creating a manifest. For readability, the directive is broken into several lines here.
#pragma comment(linker,"\"/manifestdependency:type='win32' \
name='Microsoft.Windows.Common-Controls' version='6.0.0.0' \
processorArchitecture='*' publicKeyToken='6595b64144ccf1df' language='*'\"")
The following topics describe the steps for applying visual styles to different types of applications. Notice that the manifest format is the same in each case.
The following are examples of applications that do not use third-party extensions.
To create a manifest and enable your application to use visual styles.
Link to ComCtl32.lib and call InitCommonControls.
Add a file called YourApp.exe.manifest to your source tree that has the XML manifest format.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
<assemblyIdentity
version="1.0.0.0"
processorArchitecture="*"
name="CompanyName.ProductName.YourApplication"
type="win32"
/>
<description>Your application description here.</description>
<dependency>
<dependentAssembly>
<assemblyIdentity
type="win32"
name="Microsoft.Windows.Common-Controls"
version="6.0.0.0"
processorArchitecture="*"
publicKeyToken="6595b64144ccf1df"
language="*"
/>
</dependentAssembly>
</dependency>
</assembly>
Add the manifest to your application's resource file as follows:
CREATEPROCESS_MANIFEST_RESOURCE_ID RT_MANIFEST "YourApp.exe.manifest"
Note
When you add the previous entry to the resource you must format it on one line. Alternatively, you can place the XML manifest file in the same directory as your application's executable file. The operating system will load the manifest from the file system first, then check the resource section of the executable. The file system version takes precedence.
When you build your application, the manifest will be added as a binary resource.
To create a manifest and enable your application to use visual styles.
Link to ComCtl32.lib and call InitCommonControls.
Add a file called YourApp.cpl.manifest to your source tree that has the XML manifest format.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
<assemblyIdentity
version="1.0.0.0"
processorArchitecture="*"
name="CompanyName.ProductName.YourApplication"
type="win32"
/>
<description>Your application description here.</description>
<dependency>
<dependentAssembly>
<assemblyIdentity
type="win32"
name="Microsoft.Windows.Common-Controls"
version="6.0.0.0"
processorArchitecture="*"
publicKeyToken="6595b64144ccf1df"
language="*"
/>
</dependentAssembly>
</dependency>
</assembly>
Add the manifest to your application's resource file as resource ID 123.
Note
When you author a Control Panel application, place it in the appropriate category. Control Panel now supports categorization of Control Panel applications. This means that Control Panel applications can be assigned identifiers and separated into task areas such as Add or Remove Programs, Appearance and Themes, or Date, Time, Language, and Regional Options.
Support for visual styles can be added to an extension, plug-in, MMC snap-in, or a DLL that is brought into a process. For example, use the following steps to add visual styles support for an Microsoft Management Console (MMC) snap-in.
Compile your snap-in with the -DISOLATION_AWARE_ENABLED flag or insert the following statement before the #include "windows.h" statement.
#define ISOLATION_AWARE_ENABLED 1
For more information about ISOLATION_AWARE_ENABLED, see Isolating Components.
Include the common control header file in your snap-in source.
#include <commctrl.h>
Add a file called YourApp.manifest to your source tree that uses the XML manifest format.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
<assemblyIdentity
version="1.0.0.0"
processorArchitecture="*"
name="CompanyName.ProductName.YourApplication"
type="win32"
/>
<description>Your application description here.</description>
<dependency>
<dependentAssembly>
<assemblyIdentity
type="win32"
name="Microsoft.Windows.Common-Controls"
version="6.0.0.0"
processorArchitecture="*"
publicKeyToken="6595b64144ccf1df"
language="*"
/>
</dependentAssembly>
</dependency>
</assembly>
Add the manifest to your snap-in's resource file. See Using ComCtl32 Version 6 in an Application That Uses Extensions, Plug-ins, or a DLL That Is Brought into a Process for details on adding a manifest to a resource file.
You can turn off visual styles for a control or for all controls in a window by calling the SetWindowTheme function as follows:
SetWindowTheme(hwnd, L" ", L" ");
In the previous example, hwnd is the handle of the window in which to disable visual styles. After the call, the control renders without visual styles.
HTML pages that modify the Cascading Style Sheets (CSS) properties such as background or border do not have visual styles applied to them. They display the specified CSS attribute. When specified as part of the content, most CSS properties do apply to elements that have visual styles applied.
By default, visual styles are applied to intrinsic HTML controls on pages displayed in Microsoft Internet Explorer 6 and later versions. To turn off visual styles for an HTML page, add a META tag to the <head> section. This technique also applies to content packaged as HTML Applications (HTAs). To turn off visual styles, the META tag must be as follows:
<META HTTP-EQUIV="MSThemeCompatible" CONTENT="no">
Note
If the browser setting and the tag setting do not agree, the page will not apply visual styles. For example, if the META tag is set to "no" and the browser is set to enable visual styles, visual styles will not be applied to the page. However, if either the browser or META tag is set to "yes" and the other item is not specified, visual styles will be applied.
Visual styles might change the layout of your content. Also, if you set certain attributes on intrinsic HTML controls, such as the width of a button, you might find that the label on the button is unreadable under certain visual styles.
You must thoroughly test your content using visual styles to determine whether applying visual styles has an adverse effect on your content and layout.
To avoid applying visual styles to a top level window, give the window a non-null region (SetWindowRgn). The system assumes that a window with a non-NULL region is a specialized window that does not use visual styles. A child window associated with a non-visual-styles top level window may still apply visual styles even though the parent window does not.
If you want to disable the use of visual styles for all windows in your application, call SetThemeAppProperties and do not pass the STAP_ALLOW_NONCLIENT flag. If an application does not call SetThemeAppProperties, the assumed flag values are STAP_ALLOW_NONCLIENT | STAP_ALLOW_CONTROLS | STAP_ALLOW_WEBCONTENT. The assumed values cause the nonclient area, the controls, and web content to have a visual style applied.
Much of the visual style architecture is designed to make it simple to continue to ship your product on earlier versions of Windows that do not support changing the appearance of controls. When shipping an application for more than one operating system, be aware of the following:
Training
Module
Choose the best UI framework for a native Windows development project - Training
Windows developers have various options for creating applications that run on Windows. This module introduces the native Windows UI frameworks that are available for Windows development. It also provides guidance on how to choose the best framework for your application.
Documentation
SetWindowTheme function (uxtheme.h) - Win32 apps
Causes a window to use a different set of visual style information than its class normally uses.
This section provides an overview of visual styles and explains how to configure your application to use them.
Visual Styles Overview - Win32 apps
This topic describes visual styles and identifies the Windows components that support them. It also explains the steps you must take to use visual styles in your applications.