Common Control Versions

This topic lists the available versions of the Common Control library (ComCtl32.dll), describes how to identify the version that your application is using, and explains how to target your application for a specific version.

This topic contains the following sections.

Common Control DLL Versions Numbers

Support for common controls is provided by ComCtl32.dll. All 32-bit and 64-bit versions of Windows include ComCtl32.dll. This DLL has been updated several times since it was first introduced. Each successive version supports the features and API of earlier versions. However, each new version also contains a number of new features and a correspondingly larger API. Applications must be aware of which version of Windows they are running on, and only use the features and API supported by that version.

Because various versions of ComCtl32.dll were distributed with Windows Internet Explorer, the version of ComCtl32.dll that is active is sometimes different from the version that was shipped with the operating system. Therefore, it is not enough for your application to know which operating system version it is running on. It must directly determine which version of ComCtl32.dll is present.

In the common controls reference documentation, many programming elements specify a minimum supported DLL version number. This version number indicates that the programming element is implemented in that version and subsequent versions of the DLL unless otherwise specified. If no version number is specified, the programming element is implemented in all existing versions of the DLL.

Before Windows XP, new ComCtl32.dll versions were sometimes provided with new versions of Internet Explorer. As of Windows XP, those DLLs were no longer provided as redistributable files outside of new versions of Windows itself. The following table outlines the different DLL versions and how they were distributed dating back to Microsoft Internet Explorer 3.0, Windows 95, and Microsoft Windows NT 4.0.

ComCtl32.dll
VersionDistribution Platform
4.0Windows 95 and Microsoft Windows NT 4.0
4.70Internet Explorer 3.0
4.71Microsoft Internet Explorer 4.0
4.72Microsoft Internet Explorer 4.01 and Windows 98
5.80Windows 98 Second Edition and Microsoft Internet Explorer 5
5.81Windows Millennium Edition (Windows Me), Windows 2000, Microsoft Internet Explorer 5.01, Microsoft Internet Explorer 5.5, and Microsoft Internet Explorer 6
5.82Windows XP, Windows Server 2003, Windows Vista, Windows Server 2008, and Windows 7
6.0Windows XP, Windows Server 2003
6.10Windows Vista, Windows Server 2008, and Windows 7

 

Structure Sizes for Different Common Control Versions

Ongoing enhancements to common controls have resulted in the need to extend many of the structures. For this reason, the size of the structures has changed between different versions of Commctrl.h. Because most of the common control structures take a structure size as one of the parameters, a message or function can fail if the size is not recognized. To remedy this, structure size constants have been defined to aid in targeting different version of ComCtl32.dll. The following list defines the structure size constants.

HDITEM_V1_SIZE The size of the HDITEM structure in version 4.0.
IMAGELISTDRAWPARAMS_V3_SIZE The size of the IMAGELISTDRAWPARAMS structure in version 5.9.
LVCOLUMN_V1_SIZE The size of the LVCOLUMN structure in version 4.0.
LVGROUP_V5_SIZE The size of the LVGROUP structure in version 6.0.
LVHITTESTINFO_V1_SIZE The size of the LVHITTESTINFO structure in version 4.0.
LVITEM_V1_SIZE The size of the LVITEM structure in version 4.0.
LVITEM_V5_SIZE The size of the LVITEM structure in version 6.0.
LVTILEINFO_V5_SIZE The size of the LVTILEINFO structure in version 6.0.
NMLVCUSTOMDRAW_V3_SIZE The size of the NMLVCUSTOMDRAW structure in version 4.7.
NMTTDISPINFO_V1_SIZE The size of the NMTTDISPINFO structure in version 4.0.
NMTVCUSTOMDRAW_V3_SIZE The size of the NMTVCUSTOMDRAW structure in version 4.7.
PROPSHEETHEADER_V1_SIZE The size of the PROPSHEETHEADER structure in version 4.0.
PROPSHEETPAGE_V1_SIZE The size of the PROPSHEETPAGE structure in version 4.0.
REBARBANDINFO_V3_SIZE The size of the REBARBANDINFO structure in version 4.7.
REBARBANDINFO_V6_SIZE The size of the REBARBANDINFO structure in version 6.0.
TTTOOLINFO_V1_SIZE The size of the TOOLINFO structure in version 4.0.
TTTOOLINFO_V2_SIZE The size of the TOOLINFO structure in version 4.7.
TTTOOLINFO_V3_SIZE The size of the TOOLINFO structure in version 6.0.
TVINSERTSTRUCT_V1_SIZE The size of the TVINSERTSTRUCT structure in version 4.0.

 

Using DllGetVersion to Determine the Version Number

Starting with version 4.71, the ComCtl32.dll, among others, began exporting the DllGetVersion function. This function can be called by an application to determine which DLL version is present on the system.

Note  DLLs do not necessarily export DllGetVersion. Always test for it before attempting to use it.

For Windows versions earlier than Windows 2000, DllGetVersion returns a DLLVERSIONINFO structure that contains the major and minor version numbers, the build number, and a platform ID. For Windows 2000 and later systems, DllGetVersion might instead return a DLLVERSIONINFO2 structure. In addition to the information provided through DLLVERSIONINFO, DLLVERSIONINFO2also provides the hotfix number that identifies the latest installed service pack, which provides a more robust way to compare version numbers. Because the first member of DLLVERSIONINFO2 is a DLLVERSIONINFO structure, the later structure is backward-compatible.

The following sample function GetVersion loads a specified DLL and attempts to call its DllGetVersion function. If successful, it uses a macro to pack the major and minor version numbers from the DLLVERSIONINFO structure into a DWORD that is returned to the calling application. If the DLL does not export DllGetVersion, the function returns zero. With Windows 2000 and later systems, you can modify the function to handle the possibility that DllGetVersion returns a DLLVERSIONINFO2 structure. If so, use the information in that DLLVERSIONINFO2 structure's ullVersion member to compare versions, build numbers, and service pack releases. The MAKEDLLVERULL macro simplifies the task of comparing these values to those in ullVersion.

Note  Using LoadLibrary incorrectly can pose security risks. Refer to the LoadLibrary documentation for information on how to correctly load DLLs with different versions of Windows.



#include "stdafx.h"
#include "windows.h"
#include "windef.h"
#include "winbase.h"
#include "shlwapi.h"

#define PACKVERSION(major,minor) MAKELONG(minor,major)

DWORD GetVersion(LPCTSTR lpszDllName)
{
    HINSTANCE hinstDll;
    DWORD dwVersion = 0;

    // For security purposes, LoadLibrary should be provided with a fully qualified 
    // path to the DLL. The lpszDllName variable should be tested to ensure that it 
    // is a fully qualified path before it is used. 
    hinstDll = LoadLibrary(lpszDllName);
	
    if(hinstDll)
    {
        DLLGETVERSIONPROC pDllGetVersion;
        pDllGetVersion = (DLLGETVERSIONPROC)GetProcAddress(hinstDll, "DllGetVersion");

        // Because some DLLs might not implement this function, you must test for 
        // it explicitly. Depending on the particular DLL, the lack of a DllGetVersion 
        // function can be a useful indicator of the version. 

        if(pDllGetVersion)
        {
            DLLVERSIONINFO dvi;
            HRESULT hr;

            ZeroMemory(&dvi, sizeof(dvi));
            dvi.info1.cbSize = sizeof(dvi);

            hr = (*pDllGetVersion)(&dvi);

            if(SUCCEEDED(hr))
            {
               dwVersion = PACKVERSION(dvi.info1.dwMajorVersion, dvi.info1.dwMinorVersion);
            }
        }
        FreeLibrary(hinstDll);
    }
    return dwVersion;
}

The following code example shows how you can use GetVersion to test whether ComCtl32.dll is version 6.0 or later.



LPCTSTR lpszDllName = L"C:\\Windows\\System32\\ComCtl32.dll";
DWORD dwVer = GetVersion(lpszDllName);
DWORD dwTarget = PACKVERSION(6,0);

if(dwVer >= dwTarget)
{
    // This version of ComCtl32.dll is version 6.0 or later.
}
else
{
    // Proceed knowing that version 6.0 or later additions are not available.
    // Use an alternate approach for older the DLL version.
}

Project Versions

To ensure that your application is compatible with different targeted versions of a .dll file, version macros are present in the header files. These macros are used to define, exclude, or redefine certain definitions for different versions of the DLL. See Using the Windows Headers for an in-depth description of these macros.

For example, the macro name _WIN32_IE is commonly found in older headers. You are responsible for defining the macro as a hexadecimal number. This version number defines the target version of the application that is using the DLL. The following table shows the available version numbers and the effect each has on your application.

VersionDescription
0x0300The application is compatible with ComCtl32.dll version 4.70 and later. The application cannot implement features that were added after version 4.70.
0x0400The application is compatible with ComCtl32.dll version 4.71 and later. The application cannot implement features that were added after version 4.71.
0x0401The application is compatible with ComCtl32.dll version 4.72 and later. The application cannot implement features that were added after version 4.72.
0x0500The application is compatible with ComCtl32.dll version 5.80 and later. The application cannot implement features that were added after version 5.80.
0x0501The application is compatible with ComCtl32.dll version 5.81 and later. The application cannot implement features that were added after version 5.81.
0x0600The application is compatible with ComCtl32.dll version 6.0 and later. The application cannot implement features that were added after version 6.0.

 

If you do not define the _WIN32_IE macro in your project, it is automatically defined as 0x0500. To define a different value, you can add the following to the compiler directives in your make file; substitute the desired version number for 0x0400.



/D _WIN32_IE=0x0400

Another method is to add a line similar to the following in your source code before you include the Shell header files. Substitute the desired version number for 0x0400.



#define _WIN32_IE 0x0400
#include <commctrl.h>

Related topics

About Common Controls

 

 

Community Additions

ADD
Show:
© 2014 Microsoft