Enabling Visual Styles

This topic explains how to ensure that common controls are displayed in the user's preferred visual style when running under Microsoft Windows XP or later versions of the operating system.

• Using Manifests or Directives to Ensure That Visual Styles Can Be Applied to Applications
• Using ComCtl32.dll Version 6 in an Application That Uses Only Standard Extensions
• Using ComCtl32 Version 6 in an Application That Uses Extensions, Plug-ins, or a DLL That Is Brought into a Process
• Using ComCtl32 Version 6 in Control Panel or a DLL That Is Run by RunDll32.exe
• Adding Visual Style Support to MMC Snap-ins
• Turning Off Visual Styles
• Using Visual Styles with HTML Content
• Causing the UxTheme Manager to Ignore Top Level Windows
• Making Your Application Compatible with Earlier Versions of Windows

Using Manifests or Directives to Ensure That Visual Styles Can Be Applied to Applications

Applications have a nonclient area, which includes the window frame and nonclient scroll bars. The appearance of the nonclient area is controlled by the style that is currently selected by the user. In Windows XP, for example, the user can specify the appearance of windows as either "Windows XP style" or "Windows Classic style". If Windows XP style is specified, the nonclient area is given the new look without any further action on the part of the software developer. For controls in the client area, however, you have the choice of either supporting only the classic look or supporting visual styles.

To enable visual styles for common controls in the client area, you must use ComCtl32.dll version 6 or later. Unlike earlier versions of ComCtl32.dll, version 6 is not redistributable. The only way you can use version 6 of the DLL is to use an operating system that contains it. Windows XP 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 complete list of DLL versions and their distribution platforms, see Shell and Common Controls 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. Version 6 includes some new controls and new options for other controls as well as support for changing the appearance of controls in a window.

To apply visual styles to your application, you must use an application manifest or a compiler directive to ensure that ComCtl32.dll version 6 is used when 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 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.

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.

Following is an example of a manifest file.

Important  If you write an application for the 64 bit Windows platform, you must change the processorArchitecture entry to processorArchitecture="amd64". You can also specify "*", which ensures that all platforms are targeted.

<?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="X86"
    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="X86"
            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 two 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.

Using ComCtl32.dll Version 6 in an Application That Uses Only Standard Extensions

The following are examples of applications that do not use third-party extensions.

• Calculator
• FreeCell
• Minesweeper
• Notepad
• Solitaire

To create a manifest and enable your application to use visual styles.

1. Link to ComCtl32.lib and call InitCommonControls.

2. 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="X86"
       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="X86"
               publicKeyToken="6595b64144ccf1df"
               language="*"
           />
       </dependentAssembly>
   </dependency>
   </assembly>
   

3. 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.

Using ComCtl32 Version 6 in an Application That Uses Extensions, Plug-ins, or a DLL That Is Brought into a Process

The following are examples of applications that use extensions.

• Microsoft Management Console (MMC)
• Windows Shell
• Microsoft Visual Studio

ComCtl32.dll version 6 is not completely backward compatible because some of the controls are modified and new controls are added. Using version 6 of the common controls might require code changes in your application. If an application uses extensions developed by a third party, you cannot change the extension if you have compatibility issues. The following steps describe how you can apply a visual style to your application without impacting an extension.

To create a manifest and enable your application to use visual styles.

1. Include the common controls header file as follows:

   #include "commctrl.h"
   

2. Compile your application with the -DISOLATION_AWARE_ENABLED flag or insert the following statement before the #include "windows.h" statement.

   #define ISOLATION_AWARE_ENABLED 1
   

3. 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="X86"
       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="X86"
               publicKeyToken="6595b64144ccf1df"
               language="*"
           />
       </dependentAssembly>
   </dependency>
   </assembly>
   

4. Add the manifest to your application's resource file as follows:

   
   ISOLATIONAWARE_MANIFEST_RESOURCE_ID RT_MANIFEST "YourApp.manifest"
   

   Winuser.rh includes the following defines:

   #define RT_MANIFEST 24

   #define ISOLATIONAWARE_MANIFEST_RESOURCE_ID 2

Using ComCtl32 Version 6 in Control Panel or a DLL That Is Run by RunDll32.exe

To create a manifest and enable your application to use visual styles.

1. Link to ComCtl32.lib and call InitCommonControls.

2. 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="X86"
       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="X86"
               publicKeyToken="6595b64144ccf1df"
               language="*"
           />
       </dependentAssembly>
   </dependency>
   </assembly>
   

3. 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.

Adding Visual Style Support to MMC Snap-ins

Support for visual styles may be added to more types of applications than the three previously described. For example, if you are writing a MMC snap-in you can add visual style support.

1. Compile your application with the -DISOLATION_AWARE_ENABLED flag or insert the following statement before the #include "windows.h" statement.

   
   #define ISOLATION_AWARE_ENABLED 1
   

2. Include the common control header file in your snap-in source.

   
   #include "commctrl.h"
   

3. 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="X86"
       name="YourCompanyName.YourDivision.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="X86"
               publicKeyToken="6595b64144ccf1df"
               language="*"
           />
       </dependentAssembly>
   </dependency>
   </assembly>
   

4. Add the manifest to your application'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.

Turning Off Visual Styles

To turn off visual styles for a control or for all controls in a window, call SetWindowTheme as shown in the following example, where hwnd is the handle of the window in which to disable visual styles.

SetWindowTheme(hwnd, L" ", L" ");

The control will render as it did in earlier versions of Windows.

Using Visual Styles with HTML Content

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">

To turn off visual styles, use the following:

<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.

Causing the UxTheme Manager to Ignore Top Level Windows

To avoid applying the new visual style to a top level window, consider the following:

• As long as a window has a non-NULL region applied to it (SetWindowRgn), the UxTheme Manager assumes that this is a specialized window and the window will 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 top level 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.

Making Your Application Compatible with Earlier Versions of Windows

Much of the Windows XP 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:

• If you use the features in ComCtl32.dll version 6, such as the tile view or link control, you must handle the case where those controls are not available on your user's computer. ComCtl32.dll version 6 is not redistributable.
• Test your application to make sure you are not relying on features of ComCtl32.dll version 6 without first checking for the current version.
• Do not link to UxTheme.lib.
• Write error-handling code for instances when visual styles do not work as expected.
• Installing your application's manifest in earlier versions will not affect the rendering of controls.