Header Controls

Header Controls


A header control is a window that is usually positioned above columns of text or numbers. It contains a title for each column, and it can be divided into parts. The user can drag the dividers that separate the parts to set the width of each column. The following illustration shows a header control that has labeled columns that give detailed information about files in a directory.

Header control with labeled columns.

arrowy.gifUsing Header Controls

arrowy.gifHeader Control Updates in Internet Explorer

arrowy.gifHeader Control Reference

Using Header Controls

You can create a header control by using the CreateWindowEx function, specifying the WC_HEADER window class and the appropriate header styles. This window class is registered when the common control dynamic-link library (DLL) is loaded. To ensure that this DLL is loaded, use the InitCommonControls function. After you create a header control, you can divide it into parts, set the text in each part, and control the appearance of the window by using header window messages.

Header Control Size and Position

Typically, you must set the size and position of a header control to fit within the boundaries of a particular rectangle, such as the client area of a window. By using the HDM_LAYOUT message, you can retrieve the appropriate size and position values from the header control.

When sending HDM_LAYOUT, you specify the address of an HDLAYOUT structure that contains the coordinates of the rectangle that the header control is to occupy and provides a pointer to a WINDOWPOS structure. The control fills the WINDOWPOS structure with size and position values appropriate for positioning the control along the top of the specified rectangle. The height value is the sum of the heights of the control's horizontal borders and the average height of characters in the font currently selected into the control's device context.

If you want to use HDM_LAYOUT to set the initial size and position of a header control, set the initial visibility state of the control so that it is hidden. After sending HDM_LAYOUT to retrieve the size and position values, you can use the SetWindowPos function to set the new size, position, and visibility state.

Items

A header control typically has several header items that define the columns of the control. You add an item to a header control by sending the HDM_INSERTITEM message to the control. The message includes the address of an HDITEM structure. This structure defines the properties of the header item, which can include a string, a bitmapped image, an initial size, and an application-defined 32-bit value.

The fmt member of an item's HDITEM structure can include either the HDF_STRING or HDF_BITMAP flag to indicate whether the control displays the item's string or bitmap. If you want to display both a string and a bitmap, create an owner-drawn item by setting the fmt member to include the HDF_OWNERDRAW flag. The HDITEM structure also specifies formatting flags that tell the control whether to center, left-align, or right-align the string or bitmap in the item's rectangle.

HDM_INSERTITEM returns the index of the newly added item. You can use the index in other messages to set properties or retrieve information about the item. You can delete an item by using the HDM_DELETEITEM message, specifying the index of the item to delete.

You can use the HDM_SETITEM message to set the properties of an existing header item and the HDM_GETITEM message to retrieve the current properties of an item. To retrieve a count of the items in a header control, use the HDM_GETITEMCOUNT message.

Owner-Drawn Header Controls

You can define individual items of a header control to be owner-drawn items. Using this technique gives you more control than you would otherwise have over the appearance of a header item.

You can use the HDM_INSERTITEM message to insert a new owner-drawn item into a header control or the HDM_SETITEM message to change an existing item to an owner-drawn item. Both messages include the address of an HDITEM structure, which should have the fmt member set to the HDF_OWNERDRAW value.

When a header control must draw an owner-drawn item, it sends the WM_DRAWITEM message to the parent window. The wParam parameter of the message is the child window identifier of the header control, and the lParam parameter is an address of a DRAWITEMSTRUCT structure. The parent window uses the information in the structure to draw the item. For an owner-drawn item in a header control, the DRAWITEMSTRUCT structure contains the following information.
Member Description
CtlType ODT_HEADER owner-drawn control type.
CtlID Child-window identifier of the header control.
itemID Index of the item to be drawn.
itemAction ODA_DRAWENTIRE drawing-action flag.
itemState ODS_SELECTED drawing-action flag if the cursor is on the item and the mouse button is down. Otherwise, this member is zero.
hwndItem Handle to the header control.
hDC Handle to the device context of the header control.
rcItem Coordinates of the header item to be drawn. The coordinates are relative to the upper-left corner of the header control.
itemData Application-defined 32-bit value associated with the item.

Header Control Notification Messages

A header control sends notification messages to its parent window when the user clicks or double-clicks an item, when the user drags an item divider, and when the attributes of an item change. The parent window receives the notifications in the form of WM_NOTIFY messages. The following notifications are used with header controls.
Notification Description
HDN_BEGINTRACK Signals the start of divider dragging.
HDN_DIVIDERDBLCLICK Indicates that the user double-clicked a divider.
HDN_ENDTRACK Signals the end of divider dragging.
HDN_ITEMCHANGED Indicates a change in the attributes of an item.
HDN_ITEMCHANGING Indicates that the attributes of an item are about to change.
HDN_ITEMCLICK Indicates that the user clicked an item.
HDN_ITEMDBLCLICK Indicates that the user double-clicked an item.
HDN_TRACK Indicates that the user dragged a divider.

Default Header Control Message Processing

This section describes the window messages handled by the window procedure for the WC_HEADER window class.
Message Processing performed
WM_CREATE Initializes the header control.
WM_DESTROY Uninitializes the header control.
WM_ERASEBKGND Fills the background of the header control using the control's current background color.
WM_GETDLGCODE Returns a combination of the DLGC_WANTTAB and DLGC_WANTARROWS values.
WM_GETFONT Returns the handle to the current font, which is used by the header control to draw its text.
WM_LBUTTONDBLCLK Captures mouse input. If the mouse cursor is on a divider, the control sends the HDN_BEGINTRACK notification message and begins dragging the divider. If the cursor is on an item, the item is displayed in the pressed state.
WM_LBUTTONDOWN Same as the WM_LBUTTONDBLCLK message.
WM_LBUTTONUP Releases the mouse capture. If the control was tracking mouse movement, it sends the HDN_ENDTRACK notification message and redraws the header control. Otherwise, the control sends the HDN_ITEMCLICK notification message and redraws the header item that was clicked.
WM_MOUSEMOVE If a divider is being dragged, the control sends the HDN_TRACK notification message and displays the item at the new position. If the left mouse button is down and the cursor is on an item, the item is displayed in the pressed state.
WM_NCCREATE Allocates and initializes an internal data structure.
WM_NCDESTROY Frees the resources allocated by the header control after the header control is uninitialized.
WM_PAINT Paints the invalid region of the header control. If the wParam parameter is non-NULL, the control assumes that the value is an HDC and paints using that device context.
WM_SETCURSOR Sets the cursor shape, depending on whether the cursor is on a divider or in a header item.
WM_SETFONT Selects a new font handle into the device context for the header control.

Creating a Header Control

The following example demonstrates how to create a header control and position it along the top of the parent window's client area. The control is initially hidden. The HDM_LAYOUT message is used to calculate the size and position of the control within the parent window. The control is then repositioned and made visible.


	// DoCreateHeader - creates a header control that is positioned along 
	//     the top of the parent window's client area. 
	// Returns the handle to the header control. 
	// hwndParent - handle to the parent window. 
	// 
	// Global variable 
	//    g_hinst - handle to the application instance 
	extern HINSTANCE g_hinst; 
 
	HWND DoCreateHeader(HWND hwndParent) 
	{ 
        HWND hwndHeader; 
        RECT rcParent; 
        HDLAYOUT hdl; 
        WINDOWPOS wp; 
 
        // Ensure that the common control DLL is loaded, and then create 
        // the header control. 
        InitCommonControls(); 
 
        if ((hwndHeader = CreateWindowEx(0, WC_HEADER, (LPCTSTR) NULL, 
                WS_CHILD | WS_BORDER | HDS_BUTTONS | HDS_HORZ, 
                0, 0, 0, 0, hwndParent, (HMENU) ID_HEADER, g_hinst, 
                (LPVOID) NULL)) == NULL) 
            return (HWND) NULL; 
 
        // Retrieve the bounding rectangle of the parent window's 
        // client area, and then request size and position values 
        // from the header control. 
        GetClientRect(hwndParent, &rcParent); 
 
        hdl.prc = &rcParent; 
        hdl.pwpos = ℘ 
        if (!SendMessage(hwndHeader, HDM_LAYOUT, 0, (LPARAM) &hdl)) 
            return (HWND) NULL; 
 
        // Set the size, position, and visibility of the header control. 
        SetWindowPos(hwndHeader, wp.hwndInsertAfter, wp.x, wp.y, 
            wp.cx, wp.cy, wp.flags | SWP_SHOWWINDOW); 
 
        return hwndHeader; 
	} 
 

Adding an Item to a Header Control

The following example demonstrates how to use the HDM_INSERTITEM message and the HDITEM structure to add an item to a header control. The new item consists of a string that is left-justified within the item rectangle.


	// DoInsertItem - inserts an item into a header control. 
	// Returns the index of the new item. 
	// hwndHeader - handle to the header control. 
	// iInsertAfter - index of the previous item. 
	// nWidth - width of the new item. 
	// lpsz - address of the item string. 
	int DoInsertItem(HWND hwndHeader, int iInsertAfter, 
	    int nWidth, LPSTR lpsz) 
	{ 
	    HDITEM hdi; 
	    int index; 
	 
	    hdi.mask = HDI_TEXT | HDI_FORMAT | HDI_WIDTH; 
	    hdi.pszText = lpsz; 
	    hdi.cxy = nWidth; 
	    hdi.cchTextMax = lstrlen(hdi.pszText); 
	    hdi.fmt = HDF_LEFT | HDF_STRING; 
 
    index = SendMessage(hwndHeader, HDM_INSERTITEM, 
        (WPARAM) iInsertAfter, (LPARAM) &hdi); 
 
    return index; 
 
	} 
 

Header Control Updates in Internet Explorer

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

Image Lists
New messages for this feature include HDM_GETIMAGELIST and HDM_SETIMAGELIST. The header control structure HDITEM has been updated to support image lists. Image lists can be used with current bitmap support.
Callback Items
Currently, callback support includes header item text and images. Setting a header item's text to the LPSTR_TEXTCALLBACK value or its image to the I_IMAGECALLBACK value will cause the control to send an HDN_GETDISPINFO message to request callback information as needed. HDN_GETDISPINFO is supported by the new NMHDDISPINFO structure.
Custom Item Ordering
The new messages that support this feature are: HDM_GETORDERARRAY, HDM_SETORDERARRAY, and HDM_ORDERTOINDEX.
Drag-and-Drop Manipulation
Drag-and-drop reordering of header items is now available. Implement drag-and-drop support by including the HDS_DRAGDROP style when creating the control. By default, the header control automatically handles drag-and-drop overhead and graphic effects. However, the owner of the control can manually support drag-and-drop manipulation by handling the HDN_BEGINDRAG and HDN_ENDDRAG notification messages. While handling these notifications, the owner might need to send HDM_CREATEDRAGIMAGE and HDM_SETHOTDIVIDER messages.
Hot Tracking
When this feature is enabled, the item that is under the pointer will be highlighted. To enable hot tracking in a header control, create it with the HDS_HOTTRACK style.
Text, Bitmaps, and Images
Items can simultaneously display item text, a bitmap, and an image.

Header Control Reference

This section contains information about the programming elements used with header controls.

Header Control Styles

Messages
HDM_CREATEDRAGIMAGE
HDM_DELETEITEM
HDM_GETIMAGELIST
HDM_GETITEM
HDM_GETITEMCOUNT
HDM_GETITEMRECT
HDM_GETORDERARRAY
HDM_GETUNICODEFORMAT
HDM_HITTEST
HDM_INSERTITEM
HDM_LAYOUT
HDM_ORDERTOINDEX
HDM_SETHOTDIVIDER
HDM_SETIMAGELIST
HDM_SETITEM
HDM_SETORDERARRAY
HDM_SETUNICODEFORMAT

Utility Macros
Header_CreateDragImage
Header_DeleteItem
Header_GetImageList
Header_GetItem
Header_GetItemCount
Header_GetItemRect
Header_GetOrderArray
Header_GetUnicodeFormat
Header_InsertItem
Header_Layout
Header_OrderToIndex
Header_SetHotDivider
Header_SetImageList
Header_SetItem
Header_SetOrderArray
Header_SetUnicodeFormat

Notifications
HDN_BEGINDRAG
HDN_BEGINTRACK
HDN_DIVIDERDBLCLICK
HDN_ENDDRAG
HDN_ENDTRACK
HDN_GETDISPINFO
HDN_ITEMCHANGED
HDN_ITEMCHANGING
HDN_ITEMCLICK
HDN_ITEMDBLCLICK
HDN_TRACK
NM_CUSTOMDRAW (header)
NM_RCLICK (header)
NM_RELEASEDCAPTURE (header)

Structures
HD_HITTESTINFO
HD_ITEM
HD_LAYOUT
HD_NOTIFY
HDHITTESTINFO
HDITEM
HDLAYOUT
NMHDDISPINFO
NMHEADER

Header Control Styles

Header controls have a number of styles, described below, that determine the control's appearance and behavior. You set the initial styles when you create the header control. To retrieve and change the styles after creating the control, use the GetWindowLong and SetWindowLong functions.

HDS_BUTTONS
Each item in the control looks and behaves like a push button. This style is useful if an application carries out a task when the user clicks an item in the header control. For example, an application could sort information in the columns differently depending on which item the user clicks.
HDS_DRAGDROP
Version 4.70. Allows drag-and-drop reordering of header items.
HDS_FULLDRAG
Version 4.70. Causes the header control to display column contents even while the user resizes a column.
HDS_HIDDEN
Indicates a header control that is intended to be hidden. This style does not hide the control. Instead, when you send the HDM_LAYOUT message to a header control with the HDS_HIDDEN style, the control returns zero in the cy member of the WINDOWPOS structure. You would then hide the control by setting its height to zero. This can be useful when you want to use the control as an information container instead of a visual control.
HDS_HORZ
Creates a header control with a horizontal orientation.
HDS_HOTTRACK
Version 4.70. Enables hot tracking.

Header Control Messages

This section includes information about the messages for header controls.

HDM_CREATEDRAGIMAGE
HDM_CREATEDRAGIMAGE
    wParam = (WPARAM) (int) iIndex;
    lParam = 0;

Creates a semi-transparent version of an item's image for use as a dragging image. You can send this message explicitly or use the Header_CreateDragImage macro.

iIndex
Zero-based index of the item within the header control. The image assigned to this item is the basis for the transparent image.

Version 4.70

HDM_DELETEITEM
HDM_DELETEITEM 
    wParam = (WPARAM) (int) index; 
    lParam = 0;

Deletes an item from a header control. You can send this message explicitly or use the Header_DeleteItem macro.

index
Index of the item to delete.
HDM_GETIMAGELIST
HDM_GETIMAGELIST
    wParam = 0;
    lParam = 0;

Retrieves the handle to the image list that has been set for an existing header control. You can send this message explicitly or use the Header_GetImageList macro.

Version 4.70

HDM_GETITEM
HDM_GETITEM 
    wParam = (WPARAM) (int) index; 
    lParam = (LPARAM) (LPHDITEM) phdi; 

Retrieves information about an item in a header control. You can send this message explicitly or use the Header_GetItem macro.

index
Index of the item for which information is to be retrieved.
phdi
Address of an HDITEM structure. When the message is sent, the mask member indicates the type of information being requested. When the message returns, the other members receive the requested information. If the mask member specifies zero, the message returns TRUE but copies no information to the structure.
HDM_GETITEMCOUNT
HDM_GETITEMCOUNT 
    wParam = 0; 
    lParam = 0;

Retrieves a count of the items in a header control. You can send this message explicitly or use the Header_GetItemCount macro.

HDM_GETITEMRECT
HDM_GETITEMRECT
    wParam = (WPARAM) (int) iIndex;
    lParam = (LPARAM) lpItemRect;

Retrieves the bounding rectangle for a given item in a header control. You can send this message explicitly or use the Header_GetItemRect macro.

iIndex
Zero-based index of the header control item for which to retrieve the bounding rectangle.
lpItemRect
Address of a RECT structure that receives the bounding rectangle information.

Version 4.70

HDM_GETORDERARRAY
HDM_GETORDERARRAY
    wParam = (WPARAM) (int) iSize;
    lParam = (LPARAM) (LPINT) lpiArray;

Retrieves the current left-to-right order of items in a header control. You can send this message explicitly or use the Header_GetOrderArray macro.

iSize
Number of integer elements that lpiArray can hold. This value must be equal to or greater than the number of items in the control (see HDM_GETITEMCOUNT).
lpiArray
Address of an array of integers that receive the index values for items in the header. The number of elements in this array is specified in iSize and must be equal to or greater than the number of items in the control. For example, the following code fragment will reserve enough memory to hold the index values.
int iItems,
    *lpiArray;

// Get memory for buffer.
(iItems = SendMessage(hwndHD, HDM_GETITEMCOUNT, 0,0))!=-1)
    if(!(lpiArray = calloc(iItems,sizeof(int))))
MessageBox(hwnd, "Out of memory.","Error", MB_OK);

Version 4.70

HDM_GETUNICODEFORMAT
HDM_GETUNICODEFORMAT
    wParam = 0;
    lParam = 0;

Retrieves the UNICODE character format flag for the control. You can send this message explicitly or use the Header_GetUnicodeFormat macro.

See also HDM_SETUNICODEFORMAT

HDM_HITTEST
HDM_HITTEST 
    wParam = 0; 
    lParam = (LPARAM) (LPHDHITTESTINFO) phdhti; 

Tests a point to determine which header item, if any, is at the specified point.

phdhti
Address of an HDHITTESTINFO structure that contains the position to test and receives information about the results of the test.
HDM_INSERTITEM
HDM_INSERTITEM 
    wParam = (WPARAM) (int) index; 
    lParam = (LPARAM) (const LPHDITEM) phdi; 

Inserts a new item into a header control. You can send this message explicitly or use the Header_InsertItem macro.

index
Index of the item after which the new item is to be inserted. The new item is inserted at the end of the header control if index is greater than or equal to the number of items in the control. If index is zero, the new item is inserted at the beginning of the header control.
phdi
Address of an HDITEM structure that contains information about the new item.
HDM_LAYOUT
HDM_LAYOUT 
    wParam = 0; 
    lParam = (LPARAM) (LPHDLAYOUT) playout; 

Retrieves the correct size and position of a header control within the parent window. You can send this message explicitly or use the Header_Layout macro.

playout
Address of an HDLAYOUT structure. The prc member specifies the coordinates of a rectangle, and the pwpos member receives the size and position for the header control within the rectangle.
HDM_ORDERTOINDEX
HDM_ORDERTOINDEX
    wParam = (WPARAM) iOrder;
    lParam = 0;

Retrieves an index value for an item based on its order in the header control. You can send this message explicitly or use the Header_OrderToIndex macro.

iOrder
Order in which the item appears within the header control, from left to right. For example, the index value of the item in the far left column would be 0. The value for the next item to the right would be 1, and so on.

Version 4.70

HDM_SETHOTDIVIDER
HDM_SETHOTDIVIDER
    wParam = (WPARAM) flag;
    lParam = (LPARAM) dwInputValue;

Changes the color of a divider between header items to indicate the destination of an external drag-and-drop operation. You can send this message explicitly or use the Header_SetHotDivider macro.

flag
Value specifying the type of value represented by dwInputValue. This value can be one of the following:
TRUE Indicates that dwInputValue holds the client coordinates of the pointer.
FALSE Indicates that dwInputValue holds a divider index value.
dwInputValue
Value held in dwInputValue is interpreted depending on the value of flag.

If flag is TRUE, dwInputValue represents the x- and y-coordinates of the pointer. The x-coordinate is in the low word, and the y-coordinate is in the high word. When the header control receives the message, it highlights the appropriate divider based on the dwInputValue coordinates.

If flag is FALSE, dwInputValue represents the integer index of the divider to be highlighted.

This message creates an effect that a header control automatically produces when it has the HDS_DRAGDROP style. The HDM_SETHOTDIVIDER message is intended to be used when the owner of the control handles drag-and-drop operations manually.

Version 4.70

HDM_SETIMAGELIST
HDM_SETIMAGELIST
    wParam = 0;
    lParam = (LPARAM) himl;

Assigns an image list to an existing header control. You can send this message explicitly or use the Header_SetImageList macro.

himl
Handle to an image list.

Version 4.70

HDM_SETITEM
HDM_SETITEM
    wParam = (WPARAM)(int) iIndex;
    lParam = (LPARAM)(const LPHDITEM) phdItem;

Sets the attributes of the specified item in a header control. You can send this message explicitly or use the Header_SetItem macro.

iIndex
Current index of the item whose attributes are to be changed.
phdItem
Address of an HDITEM structure that contains item information. When this message is sent, the mask member of the structure must be set to indicate which attributes are being set.

The HDITEM structure that supports this message supports item order and image list information. By using these members, you can control the order in which items are displayed and specify images to appear with items.

HDM_SETORDERARRAY
HDM_SETORDERARRAY
    wParam = (WPARAM) (int) iSize;
    lParam = (LPARAM) lpiArray;

Sets the left-to-right order of header items. You can send this message explicitly or use the Header_SetOrderArray macro.

iSize
Size of the buffer at lpiArray, in elements. This value must equal the value returned by HDM_GETITEMCOUNT.
lpiArray
Address of an array that specifies the order in which items should be displayed, from left to right. For example, if the contents of the array are {2,0,1}, the control displays item 2, item 0, and item 1, from left to right.

Version 4.70

HDM_SETUNICODEFORMAT
HDM_SETUNICODEFORMAT
    wParam = (WPARAM)(BOOL)fUnicode;
    lParam = 0;

Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control. You can send this message explicitly or use the Header_SetUnicodeFormat macro.

fUnicode
Determines the character set that is used by the control. If this value is nonzero, the control will use UNICODE characters. If this value is zero, the control will use ANSI characters.

See also HDM_GETUNICODEFORMAT

Header Control Macros

This section contains information about header control macros.

Header_CreateDragImage
HIMAGELIST Header_CreateDragImage(
    HWND hwndHD,
    int iIndex
);

Creates a transparent version of an item image within an existing header control. You can use this macro or send the HDM_CREATEDRAGIMAGE message explicitly.

hwndHD
Handle to a header control.
iIndex
Zero-based index of the item within the header control. The image assigned to this item is used as the basis for the transparent image.

Version 4.70

Header_DeleteItem
BOOL Header_DeleteItem(
    hwndHD, 	
    index	
   );	

Deletes an item from a header control. You can use this macro or send the HDM_DELETEITEM message explicitly.

hwndHD
Handle to the header control.
index
Index of the item to delete.

The Header_DeleteItem macro is defined as follows:

#define Header_DeleteItem(hwndHD, index)     \
      (BOOL)SendMessage((hwndHD), HDM_DELETEITEM, (WPARAM)(int)(index), 0L) 
 
Header_GetImageList
HIMAGELIST Header_GetImageList(HWND hwndHD);

Retrieves the handle to the image list that has been set for an existing header control. You can use this macro or send the HDM_GETIMAGELIST message explicitly.

hwndHD
Handle to a header control.

Version 4.70

Header_GetItem
BOOL Header_GetItem(
    hwndHD, 	
    index, 	
    phdi	
   );	

Retrieves information about an item in a header control. You can use this macro or send the HDM_GETITEM message explicitly.

hwndHD
Handle to the header control.
index
Index of the item for which information is to be retrieved.
phdi
Address of an HDITEM structure. When the message is sent, the mask member indicates the type of information being requested. When the message returns, the other members receive the requested information. If the mask member specifies zero, the message returns TRUE but copies no information to the structure.

The Header_GetItem macro is defined as follows:

#define Header_GetItem(hwndHD, index, phdi)      \
    (BOOL)SendMessage((hwndHD), HDM_GETITEM,   \
    (WPARAM)(int)(index), (LPARAM)(LPHDITEM)(phdi))
 
Header_GetItemCount
int Header_GetItemCount(
    hwndHD	
   );	

Retrieves a count of the items in a header control. You can use this macro or send the HDM_GETITEMCOUNT message explicitly.

hwndHD
Handle to the header control.

The Header_GetItemCount macro is defined as follows:

#define Header_GetItemCount(hwndHD)   \
       (int)SendMessage((hwndHD), HDM_GETITEMCOUNT, 0, 0L)
 
Header_GetItemRect
BOOL Header_GetItemRect(
    HWND hwndHD,
    int iIndex,
    LPRECT lpItemRect
);

Retrieves the bounding rectangle for a given item in a header control. You can use this macro or send the HDM_GETITEMRECT message explicitly.

hwndHD
Handle to a header control.
iIndex
Zero-based index of the header control item for which to retrieve the bounding rectangle.
lpItemRect
Address of a RECT structure that receives the bounding rectangle information.

Version 4.70

Header_GetOrderArray
BOOL Header_GetOrderArray(
    HWND hwndHD,
    int iSize,
    int *lpiArray
);

Retrieves the current left-to-right order of items in a header control. You can use this macro or send the HDM_GETORDERARRAY message explicitly.

hwndHD
Handle to a header control.
iSize
Number of integer elements that lpiArray can hold. This value must be equal to or greater than the number of items in the control (see HDM_GETITEMCOUNT).
lpiArray
Address of an array of integers that receive the index values for items in the header. The number of elements in this array is specified in iSize and must be equal to or greater than the number of items in the control. For example, the following code fragment will reserve enough memory to hold the index values.
int iItems,
    *lpiArray;
	
// Get memory for buffer
if((iItems = SendMessage(hwndHD, HDM_GETITEMCOUNT, 0,0))!=-1)
    if(!(lpiArray = calloc(iItems,sizeof(int))))
MessageBox(hwnd, "Out of memory.","Error", MB_OK);

Version 4.70

Header_GetUnicodeFormat
BOOL Header_GetUnicodeFormat(
    HWND hwnd
);

Retrieves the UNICODE character format flag for the control. You can use this macro or send the HDM_GETUNICODEFORMAT message explicitly.

hwnd
Handle to the control.

See also Header_SetUnicodeFormat

Header_InsertItem
int Header_InsertItem(
    hwndHD, 	
    index, 	
    phdi	
   );	

Inserts a new item into a header control. You can use this macro or send the HDM_INSERTITEM message explicitly.

hwndHD
Handle to the header control.
index
Index of the item after which the new item is to be inserted. The new item is inserted at the end of the header control if index is greater than or equal to the number of items in the control. If index is zero, the new item is inserted at the beginning of the header control.
phdi
Address of an HDITEM structure that contains information about the new item.

The Header_InsertItem macro is defined as follows:

#define Header_InsertItem(hwndHD, index, phdi) \
    (int)SendMessage((hwndHD), HDM_INSERTITEM, (WPARAM)(int)(index), \
    (LPARAM)(const LPHDITEM)(phdi))
 
Header_Layout
BOOL Header_Layout(
    hwndHD, 	
    playout	
   );	

Retrieves the correct size and position of a header control within the parent window. You can use this macro or send the HDM_LAYOUT message explicitly.

hwndHD
Handle to the header control.
playout
Address of an HDLAYOUT structure. The prc member specifies the coordinates of a rectangle, and the pwpos member receives the size and position for the header control within the rectangle.

The Header_Layout macro is defined as follows:

#define Header_Layout(hwndHD, playout) \
    (BOOL)SendMessage((hwndHD), HDM_LAYOUT, 0, \
    (LPARAM)(PLHDLAYOUT)(playout))
 
Header_OrderToIndex
int Header_OrderToIndex(
    HWND hwndHD,
    int iOrder
);

Retrieves an index value for an item based on its order in the header control. You can use this macro or send the HDM_ORDERTOINDEX message explicitly.

hwndHD
Handle to a header control.
iOrder
Order that the item appears within the header control, from left to right. The index value of the item in the far left column would be 0, the next item to the right would be 1, and so on.

Version 4.70

Header_SetHotDivider
int Header_SetHotDivider(
    HWND hwndHD,
    BOOL flag,
    DWORD dwInputValue
);

Changes the color of a divider between header items to indicate the destination of an external drag-and-drop operation. You can use this macro or send the HDM_SETHOTDIVIDER message explicitly.

hwndHD
Handle to a header control.
flag
Value specifying how dwInputValue is to be interpreted. The value in this field can be one of the following:
TRUE Indicates that dwInputValue holds client coordinates of the pointer.
FALSE Indicates that dwInputValue holds a divider index value.
dwInputValue
Value held here is interpreted depending on the value of flag.

If flag is TRUE, dwInputValue represents the x- and y- client coordinates of the pointer. The x-coordinate is in the low word, and the y-coordinate is in the high word. Upon receiving the message, the header control highlights the appropriate divider based on the dwInputValue coordinates.

If flag is FALSE, dwInputValue represents the integer index of the divider that will be highlighted.

A header control set to the HDS_DRAGDROP style produces this effect automatically. This message is intended to be used when the owner of the control handles drag-and-drop operations manually.

Version 4.70

Header_SetImageList
HIMAGELIST Header_SetImageList(
    HWND hwndHD,
    HIMAGELIST himl
);

Assigns an image list to an existing header control. You can use this macro or send the HDM_SETIMAGELIST message explicitly.

hwndHD
Handle to a header control.
himl
Handle to an image list.

Version 4.70

Header_SetItem
BOOL Header_SetItem(
    hwndHD,
    iIndex;
    phdItem
);

Sets the attributes of the specified item in a header control. You can use this macro or send the HDM_SETITEM message explicitly.

hwndHD
Handle to a header control.
iIndex
Current index of the item whose attributes are to be changed.
phdItem
Address of an HDITEM structure that contains item information. When this message is sent, the mask member of the structure must be set to indicate which attributes are being set.

The HDITEM structure that supports this macro supports item order and image list information. By using these members, you can control the order in which items are displayed and specify images to appear with items.

Header_SetOrderArray
BOOL Header_SetOrderArray(
    HWND hwndHD,
    int iSize,
    int *lpiArray
);

Sets the left-to-right order of header items. You can use this macro or send the HDM_SETORDERARRAY message explicitly.

hwndHD
Handle to a header control.
iSize
Size of the buffer at lpiArray, in elements. This value must equal the value returned by HDM_GETITEMCOUNT.
lpiArray
Address of an array that specifies the order in which items should be displayed, from left to right. For example, if the contents of the array are {2,0,1}, the control displays item 2, item 0, and item 1, from left to right.

Version 4.70

Header_SetUnicodeFormat
BOOL Header_SetUnicodeFormat(
    HWND hwnd,
    BOOL fUnicode
);

Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control. You can use this macro or send the HDM_SETUNICODEFORMAT message explicitly.

hwnd
Handle to the control.
fUnicode
Determines the character set that is used by the control. If this value is nonzero, the control will use UNICODE characters. If this value is zero, the control will use ANSI characters.

See also Header_GetUnicodeFormat

Header Control Notification Messages

This section contains information about the notification messages sent by header controls.

HDN_BEGINDRAG
HDN_BEGINDRAG
   pNMHeader = (LPNMHEADER) lParam;

Sent by a header control when a drag operation has begun on one of its items. This notification message is sent only by header controls that are set to the HDS_DRAGDROP style. This notification is sent in the form of a WM_NOTIFY message.

pNMHeader
Address of an NMHEADER structure containing information about the header item that is being dragged.

A header control defaults to automatically managing drag-and-drop reordering. Returning TRUE to indicate external (manual) drag-and-drop management allows the owner of the control to provide custom services as part of the drag-and-drop process.

Version 4.70

HDN_BEGINTRACK
HDN_BEGINTRACK 
    phdn = (LPNMHEADER) lParam; 

Notifies a header control's parent window that the user has begun dragging a divider in the control (that is, the user has pressed the left mouse button while the mouse cursor is on a divider in the header control). This notification message is sent in the form of a WM_NOTIFY message.

phdn
Address of an NMHEADER structure that contains information about the header control and the item whose divider is to be dragged.
HDN_DIVIDERDBLCLICK
HDN_DIVIDERDBLCLICK 
    phdn = (LPNMHEADER) lParam; 

Notifies a header control's parent window that the user double-clicked the divider area of the control. This notification message is sent in the form of a WM_NOTIFY message.

phdn
Address of an NMHEADER structure that contains information about the header control and the item whose divider was double-clicked.
HDN_ENDDRAG
HDN_ENDDRAG
   pNMHeader = (LPNMHEADER) lParam;

Sent by a header control when a drag operation has ended on one of its items. This notification is sent as a WM_NOTIFY message. Only header controls that are set to the HDS_DRAGDROP style send this notification.

pNMHeader
Address of an NMHEADER structure containing information about the header item that was being dragged.

If the owner is performing external (manual) drag-and-drop management, it must return FALSE. The owner then must reorder header items manually by sending HDM_SETITEM or HDM_SETORDERARRAY.

Version 4.70

HDN_ENDTRACK
HDN_ENDTRACK 
    phdn = (LPNMHEADER) lParam; 

Notifies a header control's parent window that the user has finished dragging a divider. This notification message sent in the form of a WM_NOTIFY message.

phdn
Address of an NMHEADER structure that contains information about the header control and the item whose divider was dragged.
HDN_GETDISPINFO
HDN_GETDISPINFO
   pDispInfo = (LPNMHDDISPINFO) lParam;

Sent to the owner of a header control when the control needs information about a callback header item. This notification is sent as a WM_NOTIFY message.

pDispInfo
Address of an NMHDDISPINFO structure. On input, the fields of the structure specify what information is required and the item of interest.

Fill the appropriate members of the structure to return the requested information to the header control. If your message handler sets the mask member of the NMHDDISPINFO structure to HDI_DI_SETITEM, the header control stores the information and will not request it again.

Version 4.70

HDN_ITEMCHANGED
HDN_ITEMCHANGED 
    phdr = (LPNMHEADER) lParam; 

Notifies a header control's parent window that the attributes of a header item have changed. This notification message is sent in the form of a WM_NOTIFY message.

phdr
Address of an NMHEADER structure that contains information about the header control, including the attributes that have changed.
HDN_ITEMCHANGING
HDN_ITEMCHANGING 
    phdr = (LPNMHEADER) lParam; 

Notifies a header control's parent window that the attributes of a header item are about to change. This notification message is sent in the form of a WM_NOTIFY message.

phdr
Address of an NMHEADER structure that contains information about the header control and the header item, including the attributes that are about to change.
HDN_ITEMCLICK
HDN_ITEMCLICK 
    phdr = (LPNMHEADER) lParam; 

Notifies a header control's parent window that the user clicked the control. This notification message is sent in the form of a WM_NOTIFY message.

phdr
Address of an NMHEADER structure that identifies the header control and specifies the index of the header item that was clicked and the mouse button used to click the item. The pItem member is set to NULL.

A header control sends this notification message after the user releases the left mouse button.

HDN_ITEMDBLCLICK
HDN_ITEMDBLCLICK 
    pnmhdr = (LPNMHEADER) lParam; 

Notifies a header control's parent window that the user double-clicked the control. This notification message is sent in the form of a WM_NOTIFY message. Only header controls that are set to the HDS_BUTTONS style send this notification.

pnmhdr
Address of an NMHEADER structure that contains information about this notification.
HDN_TRACK
HDN_TRACK 
    phdr = (LPNMHEADER) lParam; 

Notifies a header control's parent window that the user is dragging a divider in the header control. This notification message is sent in the form of a WM_NOTIFY message.

phdr
Address of an NMHEADER structure that contains information about the header control and the item whose divider is being dragged.
NM_CUSTOMDRAW (header)
NM_CUSTOMDRAW
    lpNMCustomDraw = (LPNMCUSTOMDRAW) lParam;

Sent by a header control to notify its parent window about drawing operations. This notification is sent in the form of a WM_NOTIFY message.

lpNMCustomDraw
Address of an NMCUSTOMDRAW structure that contains information about the drawing operation. The dwItemSpec member of this structure contains the index of the item being drawn and the lItemlParam member of this structure contains the item's lParam.

Version 4.70

See also Using Custom Draw

NM_RCLICK (header)
NM_RCLICK 
    lpnmh = (LPNMHDR) lParam; 

Notifies a tree view control's parent window that the user has clicked the right mouse button within the control. This notification is sent in the form of a WM_NOTIFY message.

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.
NM_RELEASEDCAPTURE (header)
NM_RELEASEDCAPTURE
    lpnmh = (LPNMHDR) lParam; 

Notifies a header control's parent window that the control is releasing mouse capture. This notification is sent in the form of a WM_NOTIFY message.

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Version 4.71

Header Control Structures

This section contains information on the structures used to support header controls.

HDHITTESTINFO
typedef struct _HD_HITTESTINFO {  
    POINT pt;  
    UINT flags; 
    int iItem; 
} HDHITTESTINFO, FAR *LPHDHITTESTINFO;

Contains information about a hit test. This structure is used with the HDM_HITTEST message. This structure supersedes the HD_HITTESTINFO structure.

pt
POINT structure that contains the point to be hit test, in client coordinates.
flags
Variable that receives information about the results of a hit test. This member can be one or more of the following values:
HHT_NOWHERE The point is inside the header control's bounding rectangle but is not over a header item.
HHT_ONDIVIDER The point is on the divider between two header items.
HHT_ONDIVOPEN The point is on the divider of an item that has a width of zero. Dragging the divider reveals the item instead of resizing the item to the left of the divider.
HHT_ONHEADER The point is inside the header control's bounding rectangle.
HHT_TOLEFT The point is to the left of the header control's bounding rectangle.
HHT_TORIGHT The point is to the right of the header control's bounding rectangle.

Two of these values can be combined, such as when the position is above and to the left of the client area.

iItem
If the hit test is successful, contains the index of the item at the hit test point.
HDITEM
typedef struct _HDITEM {
    UINT    mask; 
    int     cxy; 
    LPTSTR  pszText; 
    HBITMAP hbm; 
    int     cchTextMax; 
    int     fmt; 
    LPARAM  lParam; 
#if (_WIN32_IE >= 0x0300)
    int     iImage;
    int     iOrder;
#endif
} HDITEM, FAR * LPHDITEM;

Contains information about an item in a header control. This structure supersedes the HD_ITEM structure.

mask
Flags indicating which other structure members contain valid data or must be filled in. This member can be a combination of the following values:
HDI_BITMAP The hbm member is valid.
HDI_FORMAT The fmt member is valid.
HDI_HEIGHT The cxy member is valid and specifies the item's height.
HDI_IMAGE Version 4.70. The iImage member is valid and specifies the image to be displayed with the item.
HDI_LPARAM The lParam member is valid.
HDI_ORDER Version 4.70. The iOrder member is valid and specifies the item's order value.
HDI_TEXT The pszText and cchTextMax members are valid.
HDI_WIDTH The cxy member is valid and specifies the item's width.
cxy
Width or height of the item.
pszText
Address of an item string. If this member is set to LPSTR_TEXTCALLBACK, the control will request text information for this item by sending an HDN_GETDISPINFO notification message.
hbm
Handle to the item bitmap.
cchTextMax
Length of the item string, in characters.
fmt
Set of bit flags that specify the item's format.

This member can include one of the following text justification or right-to-left reading order bit flags:
HDF_CENTER The item's contents are centered.
HDF_LEFT The item's contents are left-aligned.
HDF_RIGHT The item's contents are right-aligned.
HDF_RTLREADING Text is displayed using right-to-left reading order for Hebrew or Arabic systems.

The flag from the preceding list is combined with one of the following values:
HDF_BITMAP The item displays a bitmap.
HDF_BITMAP_ON_RIGHT Version 4.70. The bitmap appears to the right of text. This does not affect an image from an image list assigned to the header item.
HDF_IMAGE Version 4.70. The item displays an image from the image list.
HDF_OWNERDRAW The header control's owner draws the item.
HDF_STRING The item displays a string.

Additionally, the following flag can be combined with any of the preceding flags:
HDF_IMAGE The item displays an image from an image list.

You can use the HDF_JUSTIFYMASK mask to isolate the text justification portion of the fmt member.

lParam
Application-defined item data.
iImage
Version 4.70. Zero-based index of an image within the image list. The specified image will be displayed in the header item in addition to any image specified in the hbm field. If iImage is set to I_IMAGECALLBACK, the control requests text information for this item by using an HDN_GETDISPINFO notification message.
iOrder
Version 4.70. Order in which the item appears within the header control, from left to right. That is, the value for the far left item is 0. The value for the next item to the right is 1, and so on.

The header control can display text, an image, and a bitmap for an item all at the same time. The alignment flags determine the order in which they appear. With HDF_LEFT or HDF_CENTER, the order is image, text, and then bitmap. With HDF_RIGHT the order is bitmap, image, and then text.

HDLAYOUT
typedef struct _HD_LAYOUT {
    RECT FAR*      prc;  
    WINDOWPOS FAR* pwpos; 
} HDLAYOUT, FAR *LPHDLAYOUT; 

Contains information used to set the size and position of a header control. This structure is used with the HDM_LAYOUT message. This structure supersedes the HD_LAYOUT structure.

prc
Address of a RECT structure that contains the coordinates of a rectangle that the header control will occupy.
pwpos
Address of a WINDOWPOS structure that receives information about the appropriate size and position of the header control.
NMHDDISPINFO
typedef struct tagNMHDDISPINFO {
    NMHDR   hdr;
    int     iItem;
    UINT    mask;
    LPTSTR  pszText;
    int     cchTextMax;
    int     iImage;
    LPARAM  lParam;
} NMHDDISPINFO, FAR* LPNMHDDISPINFO;

Contains information used in handling HDN_GETDISPINFO notification messages.

hdr
NMHDR structure containing information about this notification message.
iItem
Zero-based index of the item in the header control.
mask
Set of bit flags specifying which members of the structure must be filled in by the owner of the header control. This value can be a combination of the following values:
HDI_TEXT The pszText field must be filled in.
HDI_IMAGE The iImage field must be filled in.
HDI_LPARAM The lParam field must be filled in.
HDI_DI_SETITEM A return value. Indicates that the header control should store the item information and not ask for it again.
pszText
Address of a null-terminated string containing the text that will be displayed for the header item.
cchTextMax
Size of the buffer that pszText points to.
iImage
Zero-based index of an image within the image list. The specified image will be displayed with the header item, but it does not take the place of the item's bitmap. If iImage is set to I_IMAGECALLBACK, the control requests image information for this item by using an HDN_GETDISPINFO notification message.
lParam
32-bit value to associate with the item.

Version 4.70

NMHEADER
typedef struct tagNMHEADER{
    NMHDR    hdr;
    int      iItem;
    int      iButton;
    HDITEM  FAR* pItem;
} NMHEADER, FAR* LPNMHEADER;

Contains information about header control notification messages. This structure supersedes the HD_NOTIFY structure.

hdr
NMHDR structure that contains information about the notification message.
iItem
Zero-based index of the header item that is the focus of the notification message.
iButton
Value specifying the index of the mouse button used to generate the notification message. This member can be one of the following values:
0 Left button
1 Right button
2 Middle button
pItem
Address of an HDITEM structure containing information specific to the item indicated by iItem.

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