
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.
Common Control Updates in Internet Explorer
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.
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 |
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;
}
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. |
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. |
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.
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.
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 while the color of other buttons in the system changes.
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 WM_HSCROLL messages, 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 controls in Microsoft® Internet Explorer support the following new features.
This section contains information about the programming elements used with common controls.
| Functions |
| GetEffectiveClientRect |
| InitCommonControls |
| InitCommonControlsEx |
| ShowHideMenuCtl |
| Messages |
| WM_NOTIFY |
| WM_NOTIFYFORMAT |
| Utility Macros |
| FORWARD_WM_NOTIFY |
| HANDLE_WM_NOTIFY |
| INDEXTOSTATEIMAGEMASK |
| Notifications |
| NM_CHAR |
| NM_CLICK |
| NM_CUSTOMDRAW |
| NM_DBLCLK |
| NM_HOVER |
| NM_KEYDOWN |
| NM_KILLFOCUS |
| NM_NCHITTEST |
| NM_OUTOFMEMORY |
| NM_RCLICK |
| NM_RDBLCLK |
| NM_RELEASEDCAPTURE |
| NM_RETURN |
| NM_SETCURSOR |
| NM_SETFOCUS |
| Structures |
| COLORSCHEME |
| INITCOMMONCONTROLSEX |
| NMCHAR |
| NMHDR |
| NMKEY |
| NMMOUSE |
| NMOBJECTNOTIFY |
The following window class names are provided by the common control library:
| ANIMATE_CLASS | Creates animation controls. These controls silently display an audio video interleaved (AVI) clip. |
| DATETIMEPICK_CLASS | Creates date and time picker controls. These controls provide a simple and intuitive interface to exchange date and time information with a user. |
| HOTKEY_CLASS | Creates hot key controls. These controls make it easy for the user to define hot keys. |
| MONTHCAL_CLASS | Creates month calendar controls. These controls provide a simple and intuitive way for a user to select a date from a familiar interface. |
| PROGRESS_CLASS | Creates progress bars. These controls indicate the progress of a lengthy operation. |
| REBARCLASSNAME | Creates rebar controls. These controls act as a container for child windows. |
| STATUSCLASSNAME | Creates status windows. These controls display status information in a horizontal window. |
| TOOLBARCLASSNAME | Creates toolbars. These controls contain buttons that carry out menu commands. |
| TOOLTIPS_CLASS | Creates tooltip controls. These controls display a small pop-up window containing a line of text that describes the purpose of a tool in an application. |
| TRACKBAR_CLASS | Creates trackbars. These controls let the user select from a range of values by moving a slider. |
| UPDOWN_CLASS | Creates up-down controls. These controls combine a pair of arrows with an edit control. Clicking the arrows increments or decrements the value in the edit control. |
| WC_COMBOBOXEX | Creates ComboBoxEx controls. These controls provide an extension of the combo box control that provides native support for item images. |
| WC_HEADER | Creates header controls. These controls display headings at the top of columns of information and let the user sort the information by clicking the headings. |
| WC_IPADDRESS | Creates IP address controls. These controls are similar to an edit control, but they allow you to enter a numeric address in Internet protocol (IP) format. |
| WC_LISTVIEW | Creates list view controls. These controls display a collection of items, each consisting of an icon and a label, and provide several ways to arrange the items. |
| WC_PAGESCROLLER | Creates pager controls. These controls are used to contain and scroll another window. |
| WC_TABCONTROL | Creates tab controls. These controls define multiple pages for the same area of a window or dialog box. Each page consists of a set of information or a group of controls that an application displays when the user selects the corresponding tab. |
| WC_TREEVIEW | Creates tree view controls. These controls display a hierarchical list of items. Each item consists of a label and an optional bitmap. |
Following are the common control styles. Except where noted, these styles apply to header controls, toolbar controls, and status windows.
| CCS_ADJUSTABLE | Enables a toolbar's built-in customization features, which allow the user to drag a button to a new position or to remove a button by dragging it off the toolbar. In addition, the user can double-click the toolbar to display the Customize Toolbar dialog box, which allows the user to add, delete, and rearrange toolbar buttons. |
| CCS_BOTTOM | Causes the control to position itself at the bottom of the parent window's client area and sets the width to be the same as the parent window's width. Status windows have this style by default. |
| CCS_LEFT | Version 4.70. Causes the control to be displayed vertically on the left side of the parent window. |
| CCS_NODIVIDER | Prevents a two-pixel highlight from being drawn at the top of the control. |
| CCS_NOMOVEX | Version 4.70. Causes the control to resize and move itself vertically, but not horizontally, in response to a WM_SIZE message. If CCS_NORESIZE is used, this style does not apply. |
| CCS_NOMOVEY | Causes the control to resize and move itself horizontally, but not vertically, in response to a WM_SIZE message. If CCS_NORESIZE is used, this style does not apply. Header windows have this style by default. |
| CCS_NOPARENTALIGN | Prevents the control from automatically moving to the top or bottom of the parent window. Instead, the control keeps its position within the parent window despite changes to the size of the parent. If CCS_TOP or CCS_BOTTOM is also used, the height is adjusted to the default, but the position and width remain unchanged. |
| CCS_NORESIZE | Prevents the control from using the default width and height when setting its initial size or a new size. Instead, the control uses the width and height specified in the request for creation or sizing. |
| CCS_RIGHT | Version 4.70. Causes the control to be displayed vertically on the right side of the parent window. |
| CCS_TOP | Causes the control to position itself at the top of the parent window's client area and sets the width to be the same as the parent window's width. Toolbars have this style by default. |
| CCS_VERT | Version 4.70. Causes the control to be displayed vertically. |
The following functions are used with the common controls.
void GetEffectiveClientRect(
HWND hWnd,
LPRECT lprc,
LPINT lpInfo
);
Calculates the dimensions of a rectangle in the client area.
void InitCommonControls(VOID);
Registers and initializes the common control window classes. This function is obsolete. New applications should use the InitCommonControlsEx function.
BOOL InitCommonControlsEx(
LPINITCOMMONCONTROLSEX lpInitCtrls
);
Registers specific common control classes from the common control dynamic-link library (DLL).
Version 4.70
BOOL ShowHideMenuCtl(
HWND hWnd,
UINT uFlags,
LPINT lpInfo
);
Sets or removes the specified menu item's check mark attribute and shows or hides the corresponding control. The function adds a check mark to the specified menu item if it does not have one and then displays the corresponding control. If the menu item already has a check mark, the function removes the check mark and hides the corresponding control.
The following messages are used with the common controls.
WM_NOTIFY
idCtrl = (int) wParam;
pnmh = (LPNMHDR) lParam;
Sent by a common control to its parent window when an event has occurred in the control or the control requires some kind of information.
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 will, which notification codes it will send.
WM_NOTIFYFORMAT
hwndFrom = (HWND) wParam;
Command = lParam;
Used to determine if a window accepts ANSI or Unicode structures in the WM_NOTIFY notification message. WM_NOTIFYFORMAT messages are sent from a common control to its parent window and from the parent window to the common control.
| NFR_ANSI | ANSI structures should be used in WM_NOTIFY messages sent by the control. |
| NFR_UNICODE | Unicode structures should be used in WM_NOTIFY messages sent by the control. |
| 0 | An error occurred. |
If Command is NF_REQUERY, the return value is the result of the requery operation.
| NF_QUERY | The message is a query to determine whether ANSI or Unicode structures should be used in WM_NOTIFY messages. This command is sent from a control to its parent window during the creation of a control and in response to an NF_REQUERY command. |
| NF_REQUERY | The message is a request for a control to send an NF_QUERY form of this message to its parent window. This command is sent from the parent window. The parent window is asking the control to requery it about the type of structures to use in WM_NOTIFY messages. |
When a common control is created, the control sends a WM_NOTIFYFORMAT message to its parent window to determine the type of structures to use in WM_NOTIFY messages. If the parent window does not handle this message, the DefWindowProc function responds according to the type of the parent window. That is, if the parent window is a Unicode window, DefWindowProc returns NFR_UNICODE, and if the parent window is an ANSI window, DefWindowProc returns NFR_ANSI. If the parent window is a dialog box and does not handle this message, the DefDlgProc function similarly responds according to the type of the dialog box (Unicode or ANSI).
A parent window can change the type of structures a common control uses in WM_NOTIFY messages by setting lParam to NF_REQUERY and sending a WM_NOTIFYFORMAT message to the control. This causes the control to send an NF_QUERY form of the WM_NOTIFYFORMAT message to the parent window.
Not all controls will send WM_NOTIFYFORMAT messages. In particular, the standard Windows controls (edit controls, combo boxes, list boxes, buttons, scroll bars, and static controls) do not send WM_NOTIFYFORMAT messages. Consult the documentation for the control to determine if it will send the WM_NOTIFYFORMAT message.
The following macros are used with common controls.
VOID FORWARD_WM_NOTIFY(
hwnd,
idFrom,
pnmhdr,
fn
);
Sends or posts the WM_NOTIFY message.
The FORWARD_WM_NOTIFY macro is defined as follows:
#define FORWARD_WM_NOTIFY(hwnd, idFrom, pnmhdr, fn) \
(void)(fn)((hwnd), WM_NOTIFY, (WPARAM)(int)(id), \
(LPARAM)(NMHDR FAR*)(pnmhdr))
HANDLE_WM_NOTIFY(
hwnd,
wParam,
lParam,
fn
);
Calls a function that processes the WM_NOTIFY message.
The HANDLE_WM_NOTIFY macro is defined as follows:
#define HANDLE_WM_NOTIFY(hwnd, wParam, lParam, fn) \
(fn)((hwnd), (int)(wParam), (NMHDR FAR*)(lParam))
UINT INDEXTOSTATEIMAGEMASK(
UINT i
);
Prepares the index of a state image so that a tree view control or list view control can use the index to retrieve the state image for an item.
The INDEXTOSTATEIMAGEMASK macro is defined as follows:
#define INDEXTOSTATEIMAGEMASK(i) ((i) << 12)
The following notifications are used with common controls.
NM_CHAR
lpnmc = (LPNMCHAR) lParam;
Sent by a control when a character key is processed. This notification message is sent in the form of a WM_NOTIFY message.
Version 4.71
NM_CLICK
lpnmh = (LPNMHDR) lParam;
Notifies a control's parent window that the user has clicked the left mouse button within the control. NM_CLICK is sent in the form of a WM_NOTIFY message.
NM_DBLCLK
lpnmh = (LPNMHDR) lParam;
Notifies a control's parent window that the user has double-clicked the left mouse button within the control. NM_DBLCLK is sent in the form of a WM_NOTIFY message.
NM_HOVER
lpnmh = (LPNMHDR) lParam;
Sent by a control when the mouse hovers over an item. This notification message is sent in the form of a WM_NOTIFY message.
Version 4.70
NM_KEYDOWN
lpnmk = (LPNMKEY) lParam;
Sent by a control when the control has the keyboard focus and the user presses a key. This notification message is sent in the form of a WM_NOTIFY message.
Version 4.71
NM_KILLFOCUS
lpnmh = (LPNMHDR) lParam;
Notifies a control's parent window that the control has lost the input focus. NM_KILLFOCUS is sent in the form of a WM_NOTIFY message.
NM_NCHITTEST
lpnmmouse = (LPNMMOUSE) lParam;
Sent by a control when the control receives a WM_NCHITTEST message. This notification message is sent in the form of a WM_NOTIFY message.
Version 4.71
NM_OUTOFMEMORY
lpnmh = (LPNMHDR) lParam;
Notifies a control's parent window that the control could not complete an operation because there was not enough memory available. NM_OUTOFMEMORY is sent in the form of a WM_NOTIFY message.
NM_RCLICK
lpnmh = (LPNMHDR) lParam;
Notifies a control's parent window that the user has clicked the right mouse button within the control. NM_RCLICK is sent in the form of a WM_NOTIFY message.
NM_RDBLCLK
lpnmh = (LPNMHDR) lParam;
Notifies a control's parent window that the user has double-clicked the right mouse button within the control. NM_RDBLCLK is sent in the form of a WM_NOTIFY message.
NM_RELEASEDCAPTURE
lpnmh = (LPNMHDR) lParam;
Notifies a control's parent window that the control is releasing mouse capture. This notification is sent in the form of a WM_NOTIFY message.
Version 4.71
NM_RETURN
lpnmh = (LPNMHDR) lParam;
Notifies a control's parent window that the control has the input focus and that the user has pressed the ENTER key. NM_RETURN is sent in the form of a WM_NOTIFY message.
NM_SETCURSOR
lpnmm = (LPNMMOUSE) lParam;
Notifies a control's parent window that the control is setting the cursor in response to a WM_SETCURSOR message. This notification is sent in the form of a WM_NOTIFY message.
Version 4.71
NM_SETFOCUS
lpnmh = (LPNMHDR) lParam;
Notifies a control's parent window that the control has received the input focus. NM_SETFOCUS is sent in the form of a WM_NOTIFY message.
The following structures are used with common controls.
typedef struct tagCOLORSCHEME{
DWORD dwSize;
COLORREF clrBtnHighlight;
COLORREF clrBtnShadow;
} COLORSCHEME, *LPCOLORSCHEME;
Contains information for the drawing of buttons in a toolbar or rebar.
Version 4.71
typedef struct tagINITCOMMONCONTROLSEX {
DWORD dwSize;
DWORD dwICC;
} INITCOMMONCONTROLSEX, *LPINITCOMMONCONTROLSEX;
Carries information used to load common control classes from the dynamic-link library (DLL). This structure is used with the InitCommonControlsEx function.
| ICC_ANIMATE_CLASS | Load animate control class. |
| ICC_BAR_CLASSES | Load toolbar, status bar, trackbar, and tooltip control classes. |
| ICC_COOL_CLASSES | Load rebar control class. |
| ICC_DATE_CLASSES | Load date and time picker control class. |
| ICC_HOTKEY_CLASS | Load hot key control class. |
| ICC_INTERNET_CLASSES | Load IP address class. |
| ICC_LISTVIEW_CLASSES | Load list view and header control classes. |
| ICC_PAGESCROLLER_CLASS | Load pager control class. |
| ICC_PROGRESS_CLASS | Load progress bar control class. |
| ICC_TAB_CLASSES | Load tab and tooltip control classes. |
| ICC_TREEVIEW_CLASSES | Load tree view and tooltip control classes. |
| ICC_UPDOWN_CLASS | Load up-down control class. |
| ICC_USEREX_CLASSES | Load ComboBoxEx class. |
| ICC_WIN95_CLASSES | Load animate control, header, hot key, list view, progress bar, status bar, tab, tooltip, toolbar, trackbar, tree view, and up-down control classes. |
Version 4.70
typedef struct tagNMCHAR{
NMHDR hdr;
UINT ch;
DWORD dwItemPrev;
DWORD dwItemNext;
} NMCHAR, FAR *LPNMCHAR;
Contains information used with character notification messages.
Version 4.71
typedef struct tagNMHDR {
HWND hwndFrom;
UINT idFrom;
UINT code;
} NMHDR;
Contains information about a notification message.
typedef struct tagNMKEY {
NMHDR hdr;
UINT nVKey;
UINT uFlags;
} NMKEY, FAR *LPNMKEY;
Contains information used with key notification messages.
Version 4.71
typedef struct tagNMMOUSE {
NMHDR hdr;
DWORD dwItemSpec;
DWORD dwItemData;
POINT pt;
} NMMOUSE, FAR* LPNMMOUSE;
Contains information used with mouse notification messages.
Version 4.71
typedef struct tagNMOBJECTNOTIFY {
NMHDR hdr;
int iItem;
IID* piid;
IUnknown* pObject;
HRESULT hResult;
} NMOBJECTNOTIFY, FAR* LPNMOBJECTNOTIFY;
Contains information used with the TBN_GETOBJECT, TCN_GETOBJECT, and PSN_GETOBJECT notification messages.
Version 4.71
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.