Common Controls


		Contents Index Topic Contents
	Previous Topic: Common Controls Next Topic: Common Control Reference

Common Controls

The common controls are a set of windows that are implemented by the common control library, which is a dynamic-link library (DLL) included with the Microsoft® Windows® operating system. Like other control windows, a common control is a child window that an application uses in conjunction with another window to perform I/O tasks.
Using Common Controls

Common Control Updates in Internet Explorer

Common Control Reference

Using Common Controls

Most common controls belong to a window class defined in the common control DLL. The window class and the corresponding window procedure define the properties, appearance, and behavior of the control. To ensure that the common control DLL is loaded, include the InitCommonControls function in your application. You create a common control by specifying the name of the window class when calling the CreateWindowEx function or by specifying the appropriate class name in a dialog box template.
Common Control DLL Versions

Because of ongoing enhancements, different versions of Comctl32.dll implement different features. Throughout this document, programming elements are marked with a version number. This version number indicates that the programming element is implemented in that version and later versions of Comctl32.dll. If no version number is specified, the programming element is implemented in all versions. The following table outlines the different versions of Comctl32.dll and the distribution platform.

Version Distribution platform

4.00 Microsoft® Windows® 95/Windows NT® 4.0

4.70 Microsoft® Internet Explorer 3.x

4.71 Microsoft® Internet Explorer 4.0

4.72 Microsoft® Internet Explorer 4.01

The following function retrieves the major and minor version numbers of the Comctl32.dll that is installed on the local system.
#include <windows.h>
#include <shlwapi.h>

HRESULT GetComCtlVersion(LPDWORD pdwMajor, LPDWORD pdwMinor)
{
HINSTANCE   hComCtl;

if(   IsBadWritePtr(pdwMajor, sizeof(DWORD)) || 
      IsBadWritePtr(pdwMinor, sizeof(DWORD)))
   return E_INVALIDARG;

//load the DLL
hComCtl = LoadLibrary(TEXT("comctl32.dll"));

if(hComCtl)
   {
   HRESULT           hr = S_OK;
   DLLGETVERSIONPROC pDllGetVersion;
   
   /*
   You must get this function explicitly because earlier versions of the DLL 
   don't implement this function. That makes the lack of implementation of the 
   function a version marker in itself.
   */
   pDllGetVersion = (DLLGETVERSIONPROC)GetProcAddress(hComCtl, TEXT("DllGetVersion"));
   
   if(pDllGetVersion)
      {
      DLLVERSIONINFO    dvi;
      
      ZeroMemory(&dvi, sizeof(dvi));
      dvi.cbSize = sizeof(dvi);
   
      hr = (*pDllGetVersion)(&dvi);
      
      if(SUCCEEDED(hr))
         {
         *pdwMajor = dvi.dwMajorVersion;
         *pdwMinor = dvi.dwMinorVersion;
         }
      else
         {
         hr = E_FAIL;
         }   
      }
   else
      {
      /*
      If GetProcAddress failed, then the DLL is a version previous to the one 
      shipped with IE 3.x.
      */
      *pdwMajor = 4;
      *pdwMinor = 0;
      }
   
   FreeLibrary(hComCtl);

   return hr;
   }

return E_FAIL;
}
Structure sizes for different common control versions

Ongoing enhancements to common controls has resulted in the need to extend many of the structures. This results in the size of the structures changing between different versions of Commctrl.h. Because most of the common control structures take a structure size as one of the parameters, this can result in a message or function failing 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 new structure size constants.

HDITEM_V1_SIZE The size of the HDITEM structure in version 4.00.

LVCOLUMN_V1_SIZE The size of the LVCOLUMN structure in version 4.00.

LVHITTESTINFO_V1_SIZE The size of the LVHITTESTINFO structure in version 4.00.

LVITEM_V1_SIZE The size of the LVITEM structure in version 4.00.

NMLVCUSTOMDRAW_V3_SIZE The size of the NMLVCUSTOMDRAW structure in version 4.70.

NMTTDISPINFO_V1_SIZE The size of the NMTTDISPINFO structure in version 4.00.

NMTVCUSTOMDRAW_V3_SIZE The size of the NMTVCUSTOMDRAW structure in version 4.70.

PROPSHEETHEADER_V1_SIZE The size of the PROPSHEETHEADER structure in version 4.00.

PROPSHEETPAGE_V1_SIZE The size of the PROPSHEETPAGE structure in version 4.00.

REBARBANDINFO_V3_SIZE The size of the REBARBANDINFO structure in version 4.70.

TTTOOLINFO_V1_SIZE The size of the TOOLINFO structure in version 4.00.

TVINSERTSTRUCT_V1_SIZE The size of the TVINSERTSTRUCT structure in version 4.00.

Project Versions

To ensure that your application is compatible with different targeted versions of the common control DLL (Comctl32.dll), a version macro was added to Commctrl.h. This version macro is used to define, exclude, or redefine certain common control definitions for different versions of the DLL. The macro name is _WIN32_IE and you, the developer, 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 are the currently available version numbers and the effect each has on your application.

Version Description

0x0200 The application will be compatible with Comctl32.dll version 4.00 and later. The application will not, however, be able to implement the common control features that were added after version 4.00 of Comctl32.dll.

0x0300 The application will be compatible with Comctl32.dll version 4.70 and later. The application will not, however, be able to implement the common control features that were added after version 4.70 of Comctl32.dll.

0x0400 The application will be compatible with Comctl32.dll version 4.71 and later. The application will not, however, be able to implement the common control features that were added after version 4.71 of Comctl32.dll.

0x0401 The application will be compatible with Comctl32.dll version 4.72 and later. The application will not, however, be able to implement the common control features that were added after version 4.72 of Comctl32.dll.

The most effective way to define this macro in your project is to add the following to the compiler directives in your make file (substitute the desired version number for 0x0400):
/D _WIN32_IE=0x0400 
Another method that can be used to define this macro in your project is to add a line similar to the following in your source code before including Commctrl.h (substitute the desired version number for 0x0400):
#define _WIN32_IE 0x0400
#include <commctrl.h>
If you do not define this macro in your project, Commctrl.h will automatically define it as 0x0400.
Common Control Styles

Each type of common control has a set of control styles that you can use to vary the appearance and behavior of the control. The common control library also includes a set of control styles that apply to two or more types of common controls. The common control styles are described in the Common Control Styles section.
Common Control Messages

Because common controls are windows, an application can manipulate them by using messages, such as WM_GETFONT or WM_SETTEXT. In addition, the window class of each common control supports a set of control-specific messages that an application can use to manipulate the control. An application can use any of the message sending or posting functions to pass messages to the control. In addition, some common controls have a set of macros that an application can use instead of the sending or posting functions. The macros are typically easier to use than the functions.
When a change is made to the system color settings, Windows sends a WM_SYSCOLORCHANGE message to all top-level windows. Your top-level window must forward the WM_SYSCOLORCHANGE message to its common controls; otherwise, the controls will not be notified of the color change. This ensures that the colors used by your common controls are consistent with those used by other user interface objects. For example, a toolbar control uses the "3D Objects" color to draw its buttons. If the user changes the 3D Objects color but the WM_SYSCOLORCHANGE message is not forwarded to the toolbar, the toolbar buttons will remain in their original color (or even change to a combination of old and new colors) while the color of other buttons in the system changes.
Common Control Notification Messages

Common controls are child windows that send notification messages to the parent window when events, such as input from the user, occur in the control. The application relies on these notification messages to determine what action the user wants it to take. Except for trackbars, which use the WM_HSCROLL and WM_VSCROLL messages to notify its parent of changes, common controls send notification messages as WM_NOTIFY messages. The lParam parameter of WM_NOTIFY is either the address of an NMHDR structure or the address of a larger structure that includes NMHDR as its first member. The structure contains the notification code and identifies the common control that sent the notification message. The meaning of the remaining structure members, if any, varies depending on the notification code.
Note Not all controls will send WM_NOTIFY messages. In particular, the standard Windows controls (edit controls, combo boxes, list boxes, buttons, scroll bars, and static controls) do not send WM_NOTIFY messages. Consult the documentation for the control to determine if it will send any WM_NOTIFY messages and, if it does, which notification codes it will send.
Each type of common control has a corresponding set of notification codes. The common control library also provides notification codes that can be sent by more than one type of common control. See the documentation for the control of interest to determine which notification codes it will send and what format they take.
Common Control Updates in Internet Explorer

Common controls in Microsoft® Internet Explorer support the following new features.

Common Control Initialization
The common controls are now initialized with the InitCommonControlsEx function. This function allows you to specify which controls should be initialized for your application instead of initializing all of the controls. The InitCommonControls function is still supported, but new applications should use InitCommonControlsEx.
New Common Control Styles
There are four new common control styles defined. These are CCS_LEFT, CCS_RIGHT, CCS_VERT, and CCS_NOMOVEX. For more information, see Common Control Styles.

Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.

Version	Distribution platform
4.00	Microsoft® Windows® 95/Windows NT® 4.0
4.70	Microsoft® Internet Explorer 3.x
4.71	Microsoft® Internet Explorer 4.0
4.72	Microsoft® Internet Explorer 4.01

HDITEM_V1_SIZE	The size of the HDITEM structure in version 4.00.
LVCOLUMN_V1_SIZE	The size of the LVCOLUMN structure in version 4.00.
LVHITTESTINFO_V1_SIZE	The size of the LVHITTESTINFO structure in version 4.00.
LVITEM_V1_SIZE	The size of the LVITEM structure in version 4.00.
NMLVCUSTOMDRAW_V3_SIZE	The size of the NMLVCUSTOMDRAW structure in version 4.70.
NMTTDISPINFO_V1_SIZE	The size of the NMTTDISPINFO structure in version 4.00.
NMTVCUSTOMDRAW_V3_SIZE	The size of the NMTVCUSTOMDRAW structure in version 4.70.
PROPSHEETHEADER_V1_SIZE	The size of the PROPSHEETHEADER structure in version 4.00.
PROPSHEETPAGE_V1_SIZE	The size of the PROPSHEETPAGE structure in version 4.00.
REBARBANDINFO_V3_SIZE	The size of the REBARBANDINFO structure in version 4.70.
TTTOOLINFO_V1_SIZE	The size of the TOOLINFO structure in version 4.00.
TVINSERTSTRUCT_V1_SIZE	The size of the TVINSERTSTRUCT structure in version 4.00.

Version	Description
0x0200	The application will be compatible with Comctl32.dll version 4.00 and later. The application will not, however, be able to implement the common control features that were added after version 4.00 of Comctl32.dll.
0x0300	The application will be compatible with Comctl32.dll version 4.70 and later. The application will not, however, be able to implement the common control features that were added after version 4.70 of Comctl32.dll.
0x0400	The application will be compatible with Comctl32.dll version 4.71 and later. The application will not, however, be able to implement the common control features that were added after version 4.71 of Comctl32.dll.
0x0401	The application will be compatible with Comctl32.dll version 4.72 and later. The application will not, however, be able to implement the common control features that were added after version 4.72 of Comctl32.dll.