CHeaderCtrl Class

Article
08/06/2021

Provides the functionality of the Windows common header control.

Syntax

class CHeaderCtrl : public CWnd

Members

Public Constructors

Name	Description
CHeaderCtrl::CHeaderCtrl	Constructs a `CHeaderCtrl` object.

Public Methods

Name	Description
CHeaderCtrl::ClearAllFilters	Clears all filters for a header control.
CHeaderCtrl::ClearFilter	Clears the filter for a header control.
CHeaderCtrl::Create	Creates a header control and attaches it to a `CHeaderCtrl` object.
CHeaderCtrl::CreateDragImage	Creates a transparent version of an item's image within a header control.
CHeaderCtrl::CreateEx	Creates a header control with the specified Windows extended styles and attaches it to a `CListCtrl` object.
CHeaderCtrl::DeleteItem	Deletes an item from a header control.
CHeaderCtrl::DrawItem	Draws the specified item of a header control.
CHeaderCtrl::EditFilter	Starts editing the specified filter of a header control.
CHeaderCtrl::GetBitmapMargin	Retrieves the width of the margin of a bitmap in a header control.
CHeaderCtrl::GetFocusedItem	Gets the identifier of the item in the current header control that has the focus.
CHeaderCtrl::GetImageList	Retrieves the handle of an image list used for drawing header items in a header control.
CHeaderCtrl::GetItem	Retrieves information about an item in a header control.
CHeaderCtrl::GetItemCount	Retrieves a count of the items in a header control.
CHeaderCtrl::GetItemDropDownRect	Gets the bounding rectangle information for the specified drop-down button in a header control.
CHeaderCtrl::GetItemRect	Retrieves the bounding rectangle for a given item in a header control.
CHeaderCtrl::GetOrderArray	Retrieves the left-to-right order of items in a header control.
CHeaderCtrl::GetOverflowRect	Gets the bounding rectangle of the overflow button for the current header control.
CHeaderCtrl::HitTest	Determines which header item, if any, is located at a specified point.
CHeaderCtrl::InsertItem	Inserts a new item into a header control.
CHeaderCtrl::Layout	Retrieves the size and position of a header control within a given rectangle.
CHeaderCtrl::OrderToIndex	Retrieves the index value for an item based on its order in the header control.
CHeaderCtrl::SetBitmapMargin	Sets the width of the margin of a bitmap in a header control.
CHeaderCtrl::SetFilterChangeTimeout	Sets the timeout interval between the time a change takes place in the filter attributes and the posting of an `HDN_FILTERCHANGE` notification.
CHeaderCtrl::SetFocusedItem	Sets the focus to a specified header item in the current header control.
CHeaderCtrl::SetHotDivider	Changes the divider between header items to indicate a manual drag and drop of a header item.
CHeaderCtrl::SetImageList	Assigns an image list to a header control.
CHeaderCtrl::SetItem	Sets the attributes of the specified item in a header control.
CHeaderCtrl::SetOrderArray	Sets the left-to-right order of items in a header control.

Remarks

A header control is a window that is usually positioned above a set of 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. For an illustration of a header control, see Header Controls.

This control (and therefore the CHeaderCtrl class) is available only to programs that run under Windows 95/98 and Windows NT version 3.51 and later.

Functionality added for Windows 95/Internet Explorer 4.0 common controls includes the following:

Header item custom ordering.
Header item drag and drop, for reordering of header items. Use the HDS_DRAGDROP style when you create the CHeaderCtrl object.
Header column text constantly viewable during column resizing. Use the HDS_FULLDRAG style when you create a CHeaderCtrl object.
Header hot tracking, which highlights the header item when the pointer is hovering over it. Use the HDS_HOTTRACK style when you create the CHeaderCtrl object.
Image list support. Header items can contain images stored in a CImageList object or text.

For more information about using CHeaderCtrl, see Controls and Using CHeaderCtrl.

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CHeaderCtrl

Requirements

Header: afxcmn.h

CHeaderCtrl::CHeaderCtrl

Constructs a CHeaderCtrl object.

CHeaderCtrl();

Example

// Declare a local CHeaderCtrl object.
CHeaderCtrl myHeaderCtrl;

// Declare a dynamic CHeaderCtrl object.
CHeaderCtrl *pmyHeaderCtrl = new CHeaderCtrl;

CHeaderCtrl::ClearAllFilters

Clears all filters for a header control.

BOOL ClearAllFilters();

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

This method implements the behavior of the Win32 message HDM_CLEARFILTER with a column value of -1, as described in the Windows SDK.

Example

m_myHeaderCtrl.ClearAllFilters();

CHeaderCtrl::ClearFilter

Clears the filter for a header control.

BOOL ClearFilter(int nColumn);

Parameters

nColumn
Column value indicating which filter to clear.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

This method implements the behavior of the Win32 message HDM_CLEARFILTER, as described in the Windows SDK.

Example

int iFilt = m_myHeaderCtrl.ClearFilter(1);

CHeaderCtrl::Create

Creates a header control and attaches it to a CHeaderCtrl object.

virtual BOOL Create(
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

Parameters

dwStyle
Specifies the header control's style. For a description of header control styles, see Header Control Styles in the Windows SDK.

rect
Specifies the header control's size and position. It can be either a CRect object or a RECT structure.

pParentWnd
Specifies the header control's parent window, usually a CDialog. It must not be NULL.

nID
Specifies the header control's ID.

Return Value

Nonzero if initialization was successful; otherwise zero.

Remarks

You construct a CHeaderCtrl object in two steps. First, call the constructor and then call Create, which creates the header control and attaches it to the CHeaderCtrl object.

In addition to the header control styles, you can use the following common control styles to determine how the header control positions and resizes itself (see Common Control Styles for more information):

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.
CCS_NODIVIDER Prevents a two-pixel highlight from being drawn at the top of the control.
CCS_NOMOVEY Causes the control to resize and move itself horizontally, but not vertically, in response to a WM_SIZE message. If the CCS_NORESIZE style is used, this style does not apply. Header controls 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 window. If the CCS_TOP or CCS_BOTTOM style 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_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.

You can also apply the following window styles to a header control (see Window Styles for more information):

WS_CHILD Creates a child window. Cannot be used with the WS_POPUP style.
WS_VISIBLE Creates a window that is initially visible.
WS_DISABLED Creates a window that is initially disabled.
WS_GROUP Specifies the first control of a group of controls in which the user can move from one control to the next with the arrow keys. All controls defined with the WS_GROUP style after the first control belong to the same group. The next control with the WS_GROUP style ends the style group and starts the next group (that is, one group ends where the next begins).
WS_TABSTOP Specifies one of any number of controls through which the user can move by using the TAB key. The TAB key moves the user to the next control specified by the WS_TABSTOP style.

If you want to use extended windows styles with your control, call CreateEx instead of Create.

Example

// pParentWnd is a pointer to the parent window.
m_myHeaderCtrl.Create(WS_CHILD | WS_VISIBLE | HDS_HORZ,
                      CRect(10, 10, 600, 50), pParentWnd, 1);

CHeaderCtrl::CreateEx

Creates a control (a child window) and associate it with the CHeaderCtrl object.

virtual BOOL CreateEx(
    DWORD dwExStyle,
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

Parameters

dwExStyle
Specifies the extended style of the control being created. For a list of extended Windows styles, see the dwExStyle parameter for CreateWindowEx in the Windows SDK.

dwStyle
The header control's style. For a description of header control styles, see Header Control Styles in the Windows SDK. See Create for a list of additional styles.

rect
A reference to a RECT structure describing the size and position of the window to be created, in client coordinates of pParentWnd.

pParentWnd
A pointer to the window that is the control's parent.

nID
The control's child-window ID.

Return Value

Nonzero if successful; otherwise 0.

Remarks

Use CreateEx instead of Create to apply extended Windows styles, specified by the Windows extended style preface WS_EX_.

CHeaderCtrl::CreateDragImage

Creates a transparent version of an item's image within a header control.

CImageList* CreateDragImage(int nIndex);

Parameters

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

Return Value

A pointer to a CImageList object if successful; otherwise NULL. The returned list contains only one image.

Remarks

This member function implements the behavior of the Win32 message HDM_CREATEDRAGIMAGE, as described in the Windows SDK. It is provided to support header item drag and drop.

The CImageList object to which the returned pointer points is a temporary object and is deleted in the next idle-time processing.

CHeaderCtrl::DeleteItem

Deletes an item from a header control.

BOOL DeleteItem(int nPos);

Parameters

nPos
Specifies the zero-based index of the item to delete.

Return Value

Nonzero if successful; otherwise 0.

Example

int nCount = m_myHeaderCtrl.GetItemCount();

// Delete all of the items.
for (int i = 0; i < nCount; i++)
{
   m_myHeaderCtrl.DeleteItem(0);
}

CHeaderCtrl::DrawItem

Called by the framework when a visual aspect of an owner-draw header control changes.

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

Parameters

lpDrawItemStruct
A pointer to a DRAWITEMSTRUCT structure describing the item to be painted.

Remarks

The itemAction member of the DRAWITEMSTRUCT structure defines the drawing action that is to be performed.

By default, this member function does nothing. Override this member function to implement drawing for an owner-draw CHeaderCtrl object.

The application should restore all graphics device interface (GDI) objects selected for the display context supplied in lpDrawItemStruct before this member function terminates.

Example

// NOTE: CMyHeaderCtrl is a class derived from CHeaderCtrl.
// The CMyHeaderCtrl object was created as follows:
//
//   CMyHeaderCtrl m_myHeader;
//   myHeader.Create(WS_CHILD | WS_VISIBLE | HDS_HORZ,
//      CRect(10, 10, 600, 50), pParentWnd, 1);

// This example implements the DrawItem method for a
// CHeaderCtrl-derived class that draws every item as a
// 3D button using the text color red.
void CMyHeaderCtrl::DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct)
{
   // This code only works with header controls.
   ASSERT(lpDrawItemStruct->CtlType == ODT_HEADER);

   HDITEM hdi;
   const int c_cchBuffer = 256;
   TCHAR lpBuffer[c_cchBuffer];

   hdi.mask = HDI_TEXT;
   hdi.pszText = lpBuffer;
   hdi.cchTextMax = c_cchBuffer;

   GetItem(lpDrawItemStruct->itemID, &hdi);

   // Draw the button frame.
   ::DrawFrameControl(lpDrawItemStruct->hDC,
                      &lpDrawItemStruct->rcItem, DFC_BUTTON, DFCS_BUTTONPUSH);

   // Draw the items text using the text color red.
   COLORREF crOldColor = ::SetTextColor(lpDrawItemStruct->hDC,
                                        RGB(255, 0, 0));
   ::DrawText(lpDrawItemStruct->hDC, lpBuffer,
              (int)_tcsnlen(lpBuffer, c_cchBuffer),
              &lpDrawItemStruct->rcItem, DT_SINGLELINE | DT_VCENTER | DT_CENTER);
   ::SetTextColor(lpDrawItemStruct->hDC, crOldColor);
}

CHeaderCtrl::EditFilter

Begins to edit the specified filter of a header control.

BOOL EditFilter(
    int nColumn,
    BOOL bDiscardChanges);

Parameters

nColumn
The column to edit.

bDiscardChanges
A value that specifies how to handle the user's editing changes if the user is in the process of editing the filter when the HDM_EDITFILTER message is sent.

Specify TRUE to discard the changes made by the user, or FALSE to accept the changes made by the user.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

This method implements the behavior of the Win32 message HDM_EDITFILTER, as described in the Windows SDK.

Example

int iFilter = m_myHeaderCtrl.EditFilter(1, TRUE);

CHeaderCtrl::GetBitmapMargin

Retrieves the width of the margin of a bitmap in a header control.

int GetBitmapMargin() const;

Return Value

The width of the bitmap margin in pixels.

Remarks

This member function implements the behavior of the Win32 message HDM_GETBITMAPMARGIN, as described in the Windows SDK.

Example

int iMargin = m_myHeaderCtrl.GetBitmapMargin();

CHeaderCtrl::GetFocusedItem

Gets the index of the item that has the focus in the current header control.

int GetFocusedItem() const;

Return Value

The zero-based index of the header item that has the focus.

Remarks

This method sends the HDM_GETFOCUSEDITEM message, which is described in the Windows SDK.

Example

The first code example defines the variable, m_headerCtrl, that is used to access the current header control. This variable is used in the next example.

CHeaderCtrl m_headerCtrl;
CSplitButton m_splitButton;

The next code example demonstrates the SetFocusedItem and GetFocusedItem methods. In an earlier section of the code, we created a header control with five columns. However, you can drag a column separator so that the column is not visible. The following example sets and then confirms the last column header as the focus item.

void CNVC_MFC_CHeaderCtrl_s4Dlg::OnXSetfocuseditem()
{
   if (controlCreated == FALSE)
   {
      MessageBox(_T("Header control has not been created yet."));
      return;
   }

   // Check that we get the value we set.
   int item = m_headerCtrl.GetItemCount() - 1;
   m_headerCtrl.SetFocusedItem(item);
   int itemGet = m_headerCtrl.GetFocusedItem();
   CString str = _T("Set: focused item = %d\nGet: focused item = %d");
   str.Format(str, item, itemGet);
   MessageBox(str, _T("Set/GetFocused Item"));
}

CHeaderCtrl::GetImageList

Retrieves the handle of an image list used for drawing header items in a header control.

CImageList* GetImageList() const;

Return Value

A pointer to a CImageList object.

Remarks

This member function implements the behavior of the Win32 message HDM_GETIMAGELIST, as described in the Windows SDK. The CImageList object to which the returned pointer points is a temporary object and is deleted in the next idle-time processing.

Example

// The new image list of the header control.
m_HeaderImages.Create(16, 16, ILC_COLOR, 2, 2);
m_HeaderImages.Add(AfxGetApp()->LoadIcon(IDI_ICON1));
m_HeaderImages.Add(AfxGetApp()->LoadIcon(IDI_ICON2));
m_HeaderImages.Add(AfxGetApp()->LoadIcon(IDI_ICON3));

ASSERT(m_myHeaderCtrl.GetImageList() == NULL);

m_myHeaderCtrl.SetImageList(&m_HeaderImages);
ASSERT(m_myHeaderCtrl.GetImageList() == &m_HeaderImages);

CHeaderCtrl::GetItem

Retrieves information about a header control item.

BOOL GetItem(
    int nPos,
    HDITEM* pHeaderItem) const;

Parameters

nPos
Specifies the zero-based index of the item to retrieve.

pHeaderItem
Pointer to an HDITEM structure that receives the new item. This structure is used with the InsertItem and SetItem member functions. Any flags set in the mask element ensure that values in the corresponding elements are properly filled in upon return. If the mask element is set to zero, values in the other structure elements are meaningless.

Return Value

Nonzero if successful; otherwise 0.

Example

LPCTSTR lpszmyString = _T("column 2");
LPCTSTR lpszmyString2 = _T("vertical 2");

// Find the item whose text matches lpszmyString, and
// replace it with lpszmyString2.
int i, nCount = m_myHeaderCtrl.GetItemCount();
HDITEM hdi;
enum
{
   sizeOfBuffer = 256
};
TCHAR lpBuffer[sizeOfBuffer];
bool fFound = false;

hdi.mask = HDI_TEXT;
hdi.pszText = lpBuffer;
hdi.cchTextMax = sizeOfBuffer;

for (i = 0; !fFound && (i < nCount); i++)
{
   m_myHeaderCtrl.GetItem(i, &hdi);

   if (_tcsncmp(hdi.pszText, lpszmyString, sizeOfBuffer) == 0)
   {
      _tcscpy_s(hdi.pszText, sizeOfBuffer, lpszmyString2);
      m_myHeaderCtrl.SetItem(i, &hdi);
      fFound = true;
   }
}

CHeaderCtrl::GetItemCount

Retrieves a count of the items in a header control.

int GetItemCount() const;

Return Value

Number of header control items if successful; otherwise - 1.

Example

See the example for CHeaderCtrl::DeleteItem.

CHeaderCtrl::GetItemDropDownRect

Gets the bounding rectangle of the drop-down button for a header item in the current header control.

BOOL GetItemDropDownRect(
    int iItem,
    LPRECT lpRect) const;

Parameters

iItem
[in] Zero-based index of a header item whose style is HDF_SPLITBUTTON. For more information, see the fmt member of the HDITEM structure.

lpRect
[out] Pointer to a RECT structure to receive the bounding rectangle information.

Return Value

TRUE if this function is successful; otherwise, FALSE.

Remarks

This method sends the HDM_GETITEMDROPDOWNRECT message, which is described in the Windows SDK.

Example

The first code example defines the variable, m_headerCtrl, that is used to access the current header control. This variable is used in the next example.

CHeaderCtrl m_headerCtrl;
CSplitButton m_splitButton;

The next code example demonstrates the GetItemDropDownRect method. In an earlier section of the code, we created a header control with five columns. The following code example draws a 3D rectangle around the location on the first column that is reserved for the header drop-down button.

void CNVC_MFC_CHeaderCtrl_s4Dlg::OnXGetitemdropdownrect()
{
   if (controlCreated == FALSE)
   {
      MessageBox(_T("Header control has not been created yet."));
      return;
   }

   // Get the dropdown rect for the first column.
   CRect rect;
   BOOL bRetVal = m_headerCtrl.GetItemDropDownRect(0, &rect);
   if (bRetVal == TRUE)
   {
      // Draw around the dropdown rect a rectangle that has red
      // left and top sides, and blue right and bottom sides.
      CDC *pDC = m_headerCtrl.GetDC();
      pDC->Draw3dRect(rect, RGB(255, 0, 0), RGB(0, 0, 255));
   }
}

CHeaderCtrl::GetItemRect

Retrieves the bounding rectangle for a given item in a header control.

BOOL GetItemRect(
    int nIndex,
    LPRECT lpRect) const;

Parameters

nIndex
The zero-based index of the header control item.

lpRect
A pointer to the address of a RECT structure that receives the bounding rectangle information.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This method implements the behavior of the Win32 message HDM_GETITEMRECT, as described in the Windows SDK.

CHeaderCtrl::GetOrderArray

Retrieves the left-to-right order of items in a header control.

BOOL GetOrderArray(
    LPINT piArray,
    int iCount);

Parameters

piArray
A pointer to the address of a buffer that receives the index values of the items in the header control, in the order in which they appear from left to right.

iCount
The number of header control items. Must be non-negative.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This member function implements the behavior of the Win32 message HDM_GETORDERARRAY, as described in the Windows SDK. It is provided to support header item ordering.

Example

// Reverse the order of the items in the header control.
// (i.e. make the first item the last one, the last item
// the first one, and so on ...).
int nCount = m_myHeaderCtrl.GetItemCount();
LPINT pnOrder = (LPINT)malloc(nCount * sizeof(int));
ASSERT(pnOrder != NULL);
if (NULL != pnOrder)
{
   m_myHeaderCtrl.GetOrderArray(pnOrder, nCount);

   int i, j, nTemp;
   for (i = 0, j = nCount - 1; i < j; i++, j--)
   {
      nTemp = pnOrder[i];
      pnOrder[i] = pnOrder[j];
      pnOrder[j] = nTemp;
   }

   m_myHeaderCtrl.SetOrderArray(nCount, pnOrder);
   free(pnOrder);
}

CHeaderCtrl::GetOverflowRect

Gets the bounding rectangle of the overflow button of the current header control.

BOOL GetOverflowRect(LPRECT lpRect) const;

Parameters

lpRect
[out] Pointer to a RECT structure that receives the bounding rectangle information.

Return Value

TRUE if this function is successful; otherwise, FALSE.

Remarks

If the header control contains more items than can be simultaneously displayed, the control can display an overflow button that scrolls to items that are not visible. The header control must have the HDS_OVERFLOW and HDF_SPLITBUTTON styles to display the overflow button. The bounding rectangle encloses the overflow button and exists only when the overflow button is displayed. For more information, see Header Control Styles.

This method sends the HDM_GETOVERFLOWRECT message, which is described in the Windows SDK.

Example

The first code example defines the variable, m_headerCtrl, that is used to access the current header control. This variable is used in the next example.

CHeaderCtrl m_headerCtrl;
CSplitButton m_splitButton;

The next code example demonstrates the GetOverflowRect method. In an earlier section of the code, we created a header control with five columns. However, you can drag a column separator so that the column is not visible. If some columns are not visible, the header control draws an overflow button. The following code example draws a 3D rectangle around the location of the overflow button.

void CNVC_MFC_CHeaderCtrl_s4Dlg::OnXGetoverflowrect()
{
   if (controlCreated == FALSE)
   {
      MessageBox(_T("Header control has not been created yet."));
      return;
   }
   CRect rect;
   // Get the overflow rectangle.
   BOOL bRetVal = m_headerCtrl.GetOverflowRect(&rect);
   // Get the device context.
   CDC *pDC = m_headerCtrl.GetDC();
   // Draw around the overflow rect a rectangle that has red
   // left and top sides, and green right and bottom sides.
   pDC->Draw3dRect(rect, RGB(255, 0, 0), RGB(0, 255, 0));
}

CHeaderCtrl::HitTest

Determines which header item, if any, is located at a specified point.

int HitTest(LPHDHITTESTINFO* phdhti);

Parameters

phdhti
[in, out] Pointer to a HDHITTESTINFO structure that specifies the point to test and receives the results of the test.

Return Value

The zero-based index of the header item, if any, at the specified position; otherwise, -1.

Remarks

This method sends the HDM_HITTEST message, which is described in the Windows SDK.

Example

The first code example defines the variable, m_headerCtrl, that is used to access the current header control. This variable is used in the next example.

CHeaderCtrl m_headerCtrl;
CSplitButton m_splitButton;

The next code example demonstrates the HitTest method. In an earlier section of this code example, we created a header control with five columns. However, you can drag a column separator so that the column is not visible. This example reports the index of the column if it is visible and -1 if the column is not visible.

void CNVC_MFC_CHeaderCtrl_s4Dlg::OnXHittest()
{
   if (controlCreated == FALSE)
   {
      MessageBox(_T("Header control has not been created yet."));
      return;
   }
   // Initialize HDHITTESTINFO structure.
   HDHITTESTINFO hdHitIfo;
   memset(&hdHitIfo, 0, sizeof(HDHITTESTINFO));

   CString str;
   CRect rect;
   int iRetVal = -1;
   for (int i = 0; i < m_headerCtrl.GetItemCount(); i++)
   {
      m_headerCtrl.GetItemRect(i, &rect);
      hdHitIfo.pt = rect.CenterPoint();
      // The hit test depends on whether the header item is visible.
      iRetVal = m_headerCtrl.HitTest(&hdHitIfo);
      str.AppendFormat(_T("Item = %d, Hit item = %d\n"), i, iRetVal);
   }
   MessageBox(str, _T("Hit test results"));
}

CHeaderCtrl::InsertItem

Inserts a new item into a header control at the specified index.

int InsertItem(
    int nPos,
    HDITEM* phdi);

Parameters

nPos
The zero-based index of the item to be inserted. If the value is zero, the item is inserted at the beginning of the header control. If the value is greater than the maximum value, the item is inserted at the end of the header control.

phdi
Pointer to an HDITEM structure that contains information about the item to be inserted.

Return Value

Index of the new item if successful; otherwise - 1.

Example

CString str;
HDITEM hdi;

hdi.mask = HDI_TEXT | HDI_WIDTH | HDI_FORMAT | HDI_IMAGE;
hdi.cxy = 100; // Make all columns 100 pixels wide.
hdi.fmt = HDF_STRING | HDF_CENTER;

// Insert 6 columns in the header control.
for (int i = 0; i < 6; i++)
{
   str.Format(TEXT("column %d"), i);
   hdi.pszText = str.GetBuffer(0);
   hdi.iImage = i % 3;

   m_myHeaderCtrl.InsertItem(i, &hdi);
}

CHeaderCtrl::Layout

Retrieves the size and position of a header control within a given rectangle.

BOOL Layout(HDLAYOUT* pHeaderLayout);

Parameters

pHeaderLayout
Pointer to an HDLAYOUT structure, which contains information used to set the size and position of a header control.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This function is used to determine the appropriate dimensions for a new header control that is to occupy the given rectangle.

Example

HDLAYOUT hdl;
WINDOWPOS wpos;
RECT rc;

// Reposition the header control so that it is placed at
// the top of its parent window's client area.
m_myHeaderCtrl.GetParent()->GetClientRect(&rc);

hdl.prc = &rc;
hdl.pwpos = &wpos;
if (m_myHeaderCtrl.Layout(&hdl))
{
   m_myHeaderCtrl.SetWindowPos(
       CWnd::FromHandle(wpos.hwndInsertAfter),
       wpos.x,
       wpos.y,
       wpos.cx,
       wpos.cy,
       wpos.flags | SWP_SHOWWINDOW);
}

CHeaderCtrl::OrderToIndex

Retrieves the index value for an item based on its order in the header control.

int OrderToIndex(int nOrder) const;

Parameters

nOrder
The zero-based order that the item appears in the header control, from left to right.

Return Value

The index of the item, based on its order in the header control. The index counts from left to right, beginning with 0.

Remarks

This member function implements the behavior of the Win32 macro HDM_ORDERTOINDEX, as described in the Windows SDK. It is provided to support header item ordering.

CHeaderCtrl::SetBitmapMargin

Sets the width of the margin of a bitmap in a header control.

int SetBitmapMargin(int nWidth);

Parameters

nWidth
Width, specified in pixels, of the margin that surrounds a bitmap within an existing header control.

Return Value

The width of the bitmap margin in pixels.

Remarks

This member function implements the behavior of the Win32 message HDM_SETBITMAPMARGIN, as described in the Windows SDK.

Example

int iOldMargin = m_myHeaderCtrl.SetBitmapMargin(15);

CHeaderCtrl::SetFilterChangeTimeout

Sets the timeout interval between the time a change takes place in the filter attributes and the posting of an HDN_FILTERCHANGE notification.

int SetFilterChangeTimeout(DWORD dwTimeOut);

Parameters

dwTimeOut
Timeout value, in milliseconds.

Return Value

The index of the filter control being modified.

Remarks

This member function implements the behavior of the Win32 message HDM_SETFILTERCHANGETIMEOUT, as described in the Windows SDK.

Example

int iFltr = m_myHeaderCtrl.SetFilterChangeTimeout(15);

CHeaderCtrl::SetFocusedItem

Sets the focus to a specified header item in the current header control.

BOOL SetFocusedItem(int iItem);

Parameters

iItem
[in] Zero-based index of a header item.

Return Value

TRUE if this method is successful; otherwise, FALSE.

Remarks

This method sends the HDM_SETFOCUSEDITEM message, which is described in the Windows SDK.

Example

The first code example defines the variable, m_headerCtrl, that is used to access the current header control. This variable is used in the next example.

CHeaderCtrl m_headerCtrl;
CSplitButton m_splitButton;

void CNVC_MFC_CHeaderCtrl_s4Dlg::OnXSetfocuseditem()
{
   if (controlCreated == FALSE)
   {
      MessageBox(_T("Header control has not been created yet."));
      return;
   }

   // Check that we get the value we set.
   int item = m_headerCtrl.GetItemCount() - 1;
   m_headerCtrl.SetFocusedItem(item);
   int itemGet = m_headerCtrl.GetFocusedItem();
   CString str = _T("Set: focused item = %d\nGet: focused item = %d");
   str.Format(str, item, itemGet);
   MessageBox(str, _T("Set/GetFocused Item"));
}

CHeaderCtrl::SetHotDivider

Changes the divider between header items to indicate a manual drag and drop of a header item.

int SetHotDivider(CPoint pt);
int SetHotDivider(int nIndex);

Parameters

pt
The position of the pointer. The header control highlights the appropriate divider based on the pointer's position.

nIndex
The index of the highlighted divider.

Return Value

The index of the highlighted divider.

Remarks

This member function implements the behavior of the Win32 message HDM_SETHOTDIVIDER, as described in the Windows SDK. It is provided to support header item drag and drop.

Example

void CMyHeaderCtrl::OnMouseMove(UINT nFlags, CPoint point)
{
   SetHotDivider(point);

   CHeaderCtrl::OnMouseMove(nFlags, point);
}

CHeaderCtrl::SetImageList

Assigns an image list to a header control.

CImageList* SetImageList(CImageList* pImageList);

Parameters

pImageList
A pointer to a CImageList object containing the image list to be assigned to the header control.

Return Value

A pointer to the CImageList object previously assigned to the header control.

Remarks

This member function implements the behavior of the Win32 message HDM_SETIMAGELIST, as described in the Windows SDK. The CImageList object to which the returned pointer points is a temporary object and is deleted in the next idle-time processing.

Example

See the example for CHeaderCtrl::GetImageList.

CHeaderCtrl::SetItem

Sets the attributes of the specified item in a header control.

BOOL SetItem(
    int nPos,
    HDITEM* pHeaderItem);

Parameters

nPos
The zero-based index of the item to be manipulated.

pHeaderItem
Pointer to an HDITEM structure that contains information about the new item.

Return Value

Nonzero if successful; otherwise 0.

Example

See the example for CHeaderCtrl::GetItem.

CHeaderCtrl::SetOrderArray

Sets the left-to-right order of items in a header control.

BOOL SetOrderArray(
    int iCount,
    LPINT piArray);

Parameters

iCount
The number of header control items.

piArray
A pointer to the address of a buffer that receives the index values of the items in the header control, in the order in which they appear from left to right.

Return Value

Nonzero if successful; otherwise 0.

Remarks

This member function implements the behavior of the Win32 macro HDM_SETORDERARRAY, as described in the Windows SDK. It is provided to support header item ordering.

Example

See the example for CHeaderCtrl::GetOrderArray.