CHeaderCtrl 类

项目
06/16/2023

提供 Windows 公共标头控件的功能。

语法

class CHeaderCtrl : public CWnd

成员

公共构造函数

名称	描述
CHeaderCtrl::CHeaderCtrl	构造 `CHeaderCtrl` 对象。

公共方法

名称	描述
CHeaderCtrl::ClearAllFilters	清除标题控件的所有筛选器。
CHeaderCtrl::ClearFilter	清除标题控件的筛选器。
CHeaderCtrl::Create	创建标题控件并将其附加到 `CHeaderCtrl` 对象。
CHeaderCtrl::CreateDragImage	在标题控件中创建项图像的透明版本。
CHeaderCtrl::CreateEx	创建具有指定 Windows 扩展样式的标题控件，并将其附加到 `CListCtrl` 对象。
CHeaderCtrl::DeleteItem	从标题控件中删除项。
CHeaderCtrl::DrawItem	绘制标题控件的指定项。
CHeaderCtrl::EditFilter	开始编辑标题控件的指定筛选器。
CHeaderCtrl::GetBitmapMargin	检索标题控件中位图边距的宽度。
CHeaderCtrl::GetFocusedItem	获取具有焦点的当前标题控件中项的标识符。
CHeaderCtrl::GetImageList	检索用于在标题控件中绘制标题项的图像列表的句柄。
CHeaderCtrl::GetItem	检索有关标题控件中的项的信息。
CHeaderCtrl::GetItemCount	检索标题控件中的项计数。
CHeaderCtrl::GetItemDropDownRect	获取标题控件中指定下拉按钮的边框信息。
CHeaderCtrl::GetItemRect	检索标题控件中给定项的边框。
CHeaderCtrl::GetOrderArray	检索标题控件中项的从左到右的顺序。
CHeaderCtrl::GetOverflowRect	获取当前标题控件的溢出按钮的边框。
CHeaderCtrl::HitTest	确定位于指定点处的标题项（如果有）。
CHeaderCtrl::InsertItem	将新项插入标题控件。
CHeaderCtrl::Layout	检索给定矩形中标题控件的大小和位置。
CHeaderCtrl::OrderToIndex	根据项在标题控件中的顺序检索项的索引值。
CHeaderCtrl::SetBitmapMargin	设置标题控件中位图边距的宽度。
CHeaderCtrl::SetFilterChangeTimeout	设置筛选器属性发生更改与发布 `HDN_FILTERCHANGE` 通知之间的超时间隔。
CHeaderCtrl::SetFocusedItem	将焦点设置为当前标题控件中的指定标题项。
CHeaderCtrl::SetHotDivider	更改标题项之间的分隔符，以指示标题项的手动拖放。
CHeaderCtrl::SetImageList	将图像列表分配给标题控件。
CHeaderCtrl::SetItem	设置标题控件中指定项的属性。
CHeaderCtrl::SetOrderArray	设置标题控件中项的从左到右的顺序。

注解

标题控件是一个窗口，通常位于一组文本或数字列上方。它包含每列的标题，可以分为多个部分。用户可以拖动分隔符，分隔各个部分以设置每列的宽度。有关标题控件的插图，请参阅标题控件。

此控件（因此决定 CHeaderCtrl 类）仅适用于在 Windows 95/98 和 Windows NT 版本 3.51 及更高版本下运行的程序。

为 Windows 95/Internet Explorer 4.0 常见控件添加的功能包括：

标题项自定义排序。
标题项拖放，用于重新排序标题项。创建 CHeaderCtrl 对象时，请使用 HDS_DRAGDROP 样式。
标题列文本在列大小调整期间始终可查看。创建 CHeaderCtrl 对象时，请使用 HDS_FULLDRAG 样式。
标题热跟踪，当指针悬停在标题项上时突出显示标题项。创建 CHeaderCtrl 对象时，请使用 HDS_HOTTRACK 样式。
图像列表支持。标题项可以包含存储在 CImageList 对象或文本中的图像。

有关使用 CHeaderCtrl 的详细信息，请参阅控件和使用 CHeaderCtrl。

继承层次结构

CObject

CCmdTarget

CWnd

CHeaderCtrl

要求

标头： afxcmn.h

CHeaderCtrl::CHeaderCtrl

构造 CHeaderCtrl 对象。

CHeaderCtrl();

示例

// Declare a local CHeaderCtrl object.
CHeaderCtrl myHeaderCtrl;

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

CHeaderCtrl::ClearAllFilters

清除标题控件的所有筛选器。

BOOL ClearAllFilters();

返回值

如果此方法成功，则返回 TRUE；否则返回 FALSE。

注解

此方法使用列值 -1 实现 Win32 消息 HDM_CLEARFILTER 的行为，如 Windows SDK 中所述。

示例

m_myHeaderCtrl.ClearAllFilters();

CHeaderCtrl::ClearFilter

清除标题控件的筛选器。

BOOL ClearFilter(int nColumn);

参数

nColumn
指示要清除的筛选器的列值。

返回值

如果此方法成功，则返回 TRUE；否则返回 FALSE。

备注

此方法实现 Win32 消息 HDM_CLEARFILTER 的行为，如 Windows SDK 中所述。

示例

int iFilt = m_myHeaderCtrl.ClearFilter(1);

CHeaderCtrl::Create

创建标题控件并将其附加到 CHeaderCtrl 对象。

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

参数

dwStyle
指定标题控件的样式。有关标题控件样式的说明，请参阅 Windows SDK 中的标题控件样式。

rect
指定标题控件的大小和位置。它可以是 CRect 对象或 RECT 结构。

pParentWnd
指定标题控件的父窗口，通常为 CDialog。不得为 NULL。

nID
指定标题控件的 ID。

返回值

如果初始化成功，则为非 0；否则为 0。

注解

请分两步构造 CHeaderCtrl 对象。首先，调用构造函数，然后调用 Create，这将创建标题控件并将其附加到 CHeaderCtrl 对象。

除了标题控件样式之外，还可以使用以下常用控件样式来确定标题控件如何定位和调整自身大小（有关详细信息，请参阅常用控件样式）：

CCS_BOTTOM 使控件将自身定位在父窗口工作区的底部，并将宽度设置为与父窗口的宽度相同。
CCS_NODIVIDER 防止在控件顶部绘制一个两像素的突出显示。
CCS_NOMOVEY 使控件调整大小并水平移动（而不是垂直移动）自身，以响应 WM_SIZE 消息。如果使用 CCS_NORESIZE 样式，则此样式不适用。默认情况下，标题控件具有此样式。
CCS_NOPARENTALIGN 防止控件自动移动到父窗口的顶部或底部。相反，尽管父窗口的大小发生了变化，但控件仍保持其在父窗口中的位置。如果同时使用 CCS_TOP 或 CCS_BOTTOM 样式，则将高度调整为默认值，但位置和宽度保持不变。
CCS_NORESIZE 防止控件在设置其初始大小或新大小时使用默认宽度和高度。相反，控件使用在创建或调整大小的请求中指定的宽度和高度。
CCS_TOP 使控件将自身定位在父窗口工作区的顶部，并将宽度设置为与父窗口的宽度相同。

还可以将以下窗口样式应用于标题控件（有关详细信息，请参阅窗口样式）：

WS_CHILD 创建子窗口。不能与 WS_POPUP 样式一起使用。
WS_VISIBLE 创建初始可见的窗口。
WS_DISABLED 创建初始禁用的窗口。
WS_GROUP 指定一组控件中的第一个控件，用户可以在其中使用箭头键从一个控件移动到下一个控件。在第一个控件之后使用 WS_GROUP 样式定义的所有控件属于同一组。具有 WS_GROUP 样式的下一个控件结束样式组并开始下一个组（即，一个组在下一个开始的地方结束）。
WS_TABSTOP 指定任意数量的控件之一，用户可以使用 Tab 键在其中移动。 Tab 键将用户移动到由 WS_TABSTOP 样式指定的下一个控件。

如果要将扩展窗口样式与控件一起使用，请调用 CreateEx 而不是 Create。

示例

// 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

创建一个控件（子窗口）并将其与 CHeaderCtrl 对象相关联。

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

参数

dwExStyle
指定要创建的控件的扩展样式。有关扩展 Windows 样式的列表，请参阅 Windows SDK 中 CreateWindowEx 的 dwExStyle 参数。

dwStyle
标题控件的样式。有关标题控件样式的说明，请参阅 Windows SDK 中的标题控件样式。有关其他样式的列表，请参阅创建。

rect
对 RECT 结构的引用，该结构描述了要在客户端坐标 pParentWnd 中创建的窗口的大小和位置。

pParentWnd
指向作为控件父级的窗口的指针。

nID
控件的子窗口 ID。

返回值

如果成功，则不为 0；否则为 0。

备注

使用 CreateEx（而不是 Create）应用由 Windows 扩展样式前缀 WS_EX_ 指定的扩展 Windows 样式。

CHeaderCtrl::CreateDragImage

在标题控件中创建项图像的透明版本。

CImageList* CreateDragImage(int nIndex);

参数

nIndex
标题控件中该项的从零开始的索引。分配给此项的图像是透明图像的基础。

返回值

如果成功，则为指向 CImageList 对象的指针；否则为 NULL。返回的列表仅包含一个图像。

备注

此成员函数实现 Win32 消息 HDM_CREATEDRAGIMAGE 的行为，如 Windows SDK 中所述。提供它以支持标题项拖放。

返回的指针指向的 CImageList 对象是一个临时对象，并在下一个空闲时间处理中被删除。

CHeaderCtrl::DeleteItem

从标题控件中删除项。

BOOL DeleteItem(int nPos);

参数

nPos
指定要删除项的从零开始的索引。

返回值

如果成功，则不为 0；否则为 0。

示例

int nCount = m_myHeaderCtrl.GetItemCount();

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

CHeaderCtrl::DrawItem

当所有者绘制的标题控件的可视特征发生变化时由框架调用。

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

参数

lpDrawItemStruct
指向描述要绘制的项的 DRAWITEMSTRUCT 结构的指针。

注解

DRAWITEMSTRUCT 结构的 itemAction 成员定义要执行的绘制操作。

默认情况下，此成员函数不执行任何操作。替代此成员函数以实现所有者绘制 CHeaderCtrl 对象的绘制。

在此成员函数终止之前，应用程序应还原为 lpDrawItemStruct 中提供的显示上下文选择的所有图形设备接口 (GDI) 对象。

示例

// 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

开始编辑标题控件的指定筛选器。

BOOL EditFilter(
    int nColumn,
    BOOL bDiscardChanges);

参数

nColumn
要编辑的列。

bDiscardChanges
一个值，用于指定在发送 HDM_EDITFILTER 消息时如果用户正在编辑筛选器应如何处理用户的编辑更改。

指定 TRUE 放弃用户所做的更改，或指定 FALSE 接受用户所做的更改。

返回值

如果此方法成功，则返回 TRUE；否则返回 FALSE。

注解

此方法实现 Win32 消息 HDM_EDITFILTER 的行为，如 Windows SDK 中所述。

示例

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

CHeaderCtrl::GetBitmapMargin

检索标题控件中位图边距的宽度。

int GetBitmapMargin() const;

返回值

位图边距的宽度（以像素为单位）。

备注

此成员函数实现 Win32 消息 HDM_GETBITMAPMARGIN 的行为，如 Windows SDK 中所述。

示例

int iMargin = m_myHeaderCtrl.GetBitmapMargin();

CHeaderCtrl::GetFocusedItem

获取当前标题控件中具有焦点的项的索引。

int GetFocusedItem() const;

返回值

具有焦点的标题项的从零开始的索引。

备注

此方法将发送 HDM_GETFOCUSEDITEM 消息，如 Windows SDK 中所述。

示例

第一个代码示例定义一个变量 m_headerCtrl，用于访问当前标题控件。此变量将在下一个示例中使用。

CHeaderCtrl m_headerCtrl;
CSplitButton m_splitButton;

下一个代码示例演示了 SetFocusedItem 和 GetFocusedItem 方法。在代码的前面部分中，我们创建了一个包含五列的标题控件。但是，可以拖动列分隔符，使列不可见。以下示例设置并确认最后一个列标题为焦点项。

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

检索用于在标题控件中绘制标题项的图像列表的句柄。

CImageList* GetImageList() const;

返回值

指向 CImageList 对象的指针。

备注

此成员函数实现 Win32 消息 HDM_GETIMAGELIST 的行为，如 Windows SDK 中所述。返回的指针指向的 CImageList 对象是一个临时对象，并在下一个空闲时间处理中被删除。

示例

// 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

检索有关标题控件项的信息。

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

参数

nPos
指定要检索项的从零开始的索引。

pHeaderItem
指向接收新项的 HDITEM 结构的指针。此结构与 InsertItem 和 SetItem 成员函数一起使用。 mask 元素中设置的任何标志可确保在返回时正确填写相应元素中的值。如果 mask 元素设置为 0，则其他结构元素中的值毫无意义。

返回值

如果成功，则不为 0；否则为 0。

示例

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

检索标题控件中的项计数。

int GetItemCount() const;

返回值

如果成功，则为标题控件项的数目；否则为 -1。

示例

请参阅 CHeaderCtrl::DeleteItem 的示例。

CHeaderCtrl::GetItemDropDownRect

获取当前标题控件中标题项的下拉按钮的边框。

BOOL GetItemDropDownRect(
    int iItem,
    LPRECT lpRect) const;

参数

iItem
[in] 样式为 HDF_SPLITBUTTON 的标题项的从零开始的索引。有关详细信息，请参阅 fmtHDITEM 结构的成员。

lpRect
[out] 指向 RECT 结构以接收边框信息的指针。

返回值

如果此函数成功，则为 TRUE；否则为 FALSE。

备注

此方法将发送 HDM_GETITEMDROPDOWNRECT 消息，如 Windows SDK 中所述。

示例

第一个代码示例定义一个变量 m_headerCtrl，用于访问当前标题控件。此变量将在下一个示例中使用。

CHeaderCtrl m_headerCtrl;
CSplitButton m_splitButton;

下一个代码示例演示了 GetItemDropDownRect 方法。在代码的前面部分中，我们创建了一个包含五列的标题控件。下面的代码示例在为标题下拉按钮保留的第一列的位置周围绘制一个 3D 矩形。

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

检索标题控件中给定项的边框。

BOOL GetItemRect(
    int nIndex,
    LPRECT lpRect) const;

参数

nIndex
标题控件项的从零开始的索引。

lpRect
指向接收边框信息的 RECT 结构的地址的指针。

返回值

如果成功，则不为 0；否则为 0。

备注

此方法实现 Win32 消息 HDM_GETITEMRECT 的行为，如 Windows SDK 中所述。

CHeaderCtrl::GetOrderArray

检索标题控件中项的从左到右的顺序。

BOOL GetOrderArray(
    LPINT piArray,
    int iCount);

参数

piArray
指向缓冲区地址的指针，该缓冲区按照它们从左到右出现的顺序接收标题控件中项目的索引值。

iCount
标题控件项的数目。必须为非负值。

返回值

如果成功，则不为 0；否则为 0。

注解

此成员函数实现 Win32 消息 HDM_GETORDERARRAY 的行为，如 Windows SDK 中所述。提供它以支持标题项排序。

示例

// 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

获取当前标题控件的溢出按钮的边框。

BOOL GetOverflowRect(LPRECT lpRect) const;

参数

lpRect
[out] 指向接收边框信息的 RECT 结构的指针。

返回值

如果此函数成功，则为 TRUE；否则为 FALSE。

备注

如果标题控件包含的项多于可以同时显示的项，则该控件可以显示一个溢出按钮，该按钮可以滚动到不可见的项。标题控件必须具有 HDS_OVERFLOW 和 HDF_SPLITBUTTON 样式才能显示溢出按钮。边框包围了溢出按钮，并且仅在显示溢出按钮时才存在。有关详细信息，请参阅标题控件样式。

此方法将发送 HDM_GETOVERFLOWRECT 消息，如 Windows SDK 中所述。

示例

第一个代码示例定义一个变量 m_headerCtrl，用于访问当前标题控件。此变量将在下一个示例中使用。

CHeaderCtrl m_headerCtrl;
CSplitButton m_splitButton;

下一个代码示例演示了 GetOverflowRect 方法。在代码的前面部分中，我们创建了一个包含五列的标题控件。但是，可以拖动列分隔符，使列不可见。如果某些列不可见，则标题控件会绘制一个溢出按钮。下面的代码示例在溢出按钮的位置周围绘制一个 3D 矩形。

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

确定位于指定点处的标题项（如果有）。

int HitTest(LPHDHITTESTINFO* phdhti);

参数

phdhti
[in, out] 指向 HDHITTESTINFO 结构的指针，该结构指定要测试的点并接收测试结果。

返回值

指定位置的标题项的从零开始的索引（如果有）；否则为 -1。

备注

此方法将发送 HDM_HITTEST 消息，如 Windows SDK 中所述。

示例

第一个代码示例定义一个变量 m_headerCtrl，用于访问当前标题控件。此变量将在下一个示例中使用。

CHeaderCtrl m_headerCtrl;
CSplitButton m_splitButton;

下一个代码示例演示了 HitTest 方法。在此代码示例的前面部分中，我们创建了一个包含五列的标题控件。但是，可以拖动列分隔符，使列不可见。如果列可见，则此示例报告列的索引，如果列不可见，则报告 -1。

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

在指定索引处将新项插入标题控件。

int InsertItem(
    int nPos,
    HDITEM* phdi);

参数

nPos
要插入的项的索引（索引从零开始）。如果该值为 0，则将项插入到标题控件的开头。如果该值大于最大值，则将项插入到标题控件的末尾。

phdi
指向包含要插入的项信息的 HDITEM 结构的指针。

返回值

如果成功，则为新项的索引；否则为 -1。

示例

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

检索给定矩形中标题控件的大小和位置。

BOOL Layout(HDLAYOUT* pHeaderLayout);

参数

pHeaderLayout
指向 HDLAYOUT 结构的指针，该结构包含用于设置标题控件大小和位置的信息。

返回值

如果成功，则不为 0；否则为 0。

注解

此函数用于确定要占用给定矩形的新标题控件的相应尺寸。

示例

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

根据项在标题控件中的顺序检索项的索引值。

int OrderToIndex(int nOrder) const;

参数

nOrder
项从左到右显示在标题控件中的从零开始的顺序。

返回值

项的索引，基于其在标题控件中的顺序。索引从左到右计数，从 0 开始。

备注

此成员函数实现 Win32 宏 HDM_ORDERTOINDEX 的行为，如 Windows SDK 中所述。提供它以支持标题项排序。

CHeaderCtrl::SetBitmapMargin

设置标题控件中位图边距的宽度。

int SetBitmapMargin(int nWidth);

参数

nWidth
现有标题控件内围绕位图的边距的宽度（以像素为单位）。

返回值

位图边距的宽度（以像素为单位）。

备注

此成员函数实现 Win32 消息 HDM_SETBITMAPMARGIN 的行为，如 Windows SDK 中所述。

示例

int iOldMargin = m_myHeaderCtrl.SetBitmapMargin(15);

CHeaderCtrl::SetFilterChangeTimeout

设置筛选器属性发生更改与发布 HDN_FILTERCHANGE 通知之间的超时间隔。

int SetFilterChangeTimeout(DWORD dwTimeOut);

参数

dwTimeOut
超时值（以毫秒为单位）。

返回值

正在修改的筛选器控件的索引。

备注

此成员函数实现 Win32 消息 HDM_SETFILTERCHANGETIMEOUT 的行为，如 Windows SDK 中所述。

示例

int iFltr = m_myHeaderCtrl.SetFilterChangeTimeout(15);

CHeaderCtrl::SetFocusedItem

将焦点设置为当前标题控件中的指定标题项。

BOOL SetFocusedItem(int iItem);

参数

iItem
[in] 标题项的从零开始的索引。

返回值

如果此方法成功，则返回 TRUE；否则返回 FALSE。

注解

此方法将发送 HDM_SETFOCUSEDITEM 消息，如 Windows SDK 中所述。

示例

第一个代码示例定义一个变量 m_headerCtrl，用于访问当前标题控件。此变量将在下一个示例中使用。

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

更改标题项之间的分隔符，以指示标题项的手动拖放。

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

参数

pt
指针的位置。标题控件根据指针的位置突出显示相应的分隔符。

nIndex
突出显示的分隔符的索引。

返回值

突出显示的分隔符的索引。

注解

此成员函数实现 Win32 消息 HDM_SETHOTDIVIDER 的行为，如 Windows SDK 中所述。提供它以支持标题项拖放。

示例

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

   CHeaderCtrl::OnMouseMove(nFlags, point);
}

CHeaderCtrl::SetImageList

将图像列表分配给标题控件。

CImageList* SetImageList(CImageList* pImageList);

参数

pImageList
指向 CImageList 对象的指针，该对象包含要分配给标题控件的图像列表。

返回值

指向先前分配给标题控件的 CImageList 对象的指针。

备注

此成员函数实现 Win32 消息 HDM_SETIMAGELIST 的行为，如 Windows SDK 中所述。返回的指针指向的 CImageList 对象是一个临时对象，并在下一个空闲时间处理中被删除。

示例

请参阅 CHeaderCtrl::GetImageList 的示例。

CHeaderCtrl::SetItem

设置标题控件中指定项的属性。

BOOL SetItem(
    int nPos,
    HDITEM* pHeaderItem);

参数

nPos
要操作的项的从零开始的索引。

pHeaderItem
指向包含新项信息的 HDITEM 结构的指针。

返回值

如果成功，则不为 0；否则为 0。

示例

请参阅 CHeaderCtrl::GetItem 的示例。

CHeaderCtrl::SetOrderArray

设置标题控件中项的从左到右的顺序。

BOOL SetOrderArray(
    int iCount,
    LPINT piArray);

参数

iCount
标题控件项的数目。

piArray
指向缓冲区地址的指针，该缓冲区按照它们从左到右出现的顺序接收标题控件中项目的索引值。

返回值

如果成功，则不为 0；否则为 0。

备注

此成员函数实现 Win32 宏 HDM_SETORDERARRAY 的行为，如 Windows SDK 中所述。提供它以支持标题项排序。

示例

请参阅 CHeaderCtrl::GetOrderArray 的示例。

另请参阅

CWnd 类
 层次结构图
 CTabCtrl 类
 CListCtrl 类
 CImageList 类

通过

CHeaderCtrl 类

语法

成员

公共构造函数

公共方法

注解

继承层次结构

要求

CHeaderCtrl::CHeaderCtrl

示例

CHeaderCtrl::ClearAllFilters

返回值

注解

示例

CHeaderCtrl::ClearFilter

参数

返回值

备注

示例

CHeaderCtrl::Create

参数

返回值

注解

示例

CHeaderCtrl::CreateEx

参数

返回值

备注

CHeaderCtrl::CreateDragImage

参数

返回值

备注

CHeaderCtrl::DeleteItem

参数

返回值

示例

CHeaderCtrl::DrawItem

参数

注解

示例

CHeaderCtrl::EditFilter

参数

返回值

注解

示例

CHeaderCtrl::GetBitmapMargin

返回值

备注

示例

CHeaderCtrl::GetFocusedItem

返回值

备注

示例

CHeaderCtrl::GetImageList

返回值

备注

示例

CHeaderCtrl::GetItem

参数

返回值

示例

CHeaderCtrl::GetItemCount

返回值

示例

CHeaderCtrl::GetItemDropDownRect

参数

返回值

备注

示例

CHeaderCtrl::GetItemRect

参数

返回值

备注

CHeaderCtrl::GetOrderArray

参数

返回值

注解

示例

CHeaderCtrl::GetOverflowRect