CHeaderCtrl 類別

發行項
08/04/2024

提供 Windows 通用標頭控制項的功能。

語法

class CHeaderCtrl : public CWnd

成員

公用建構函式

名稱	描述
CHeaderCtrl：：CHeaderCtrl	建構 `CHeaderCtrl` 物件。

公用方法

名稱	描述
CHeaderCtrl：：ClearAllFilters	清除標頭控件的所有篩選。
CHeaderCtrl：：ClearFilter	清除標頭控件的篩選。
CHeaderCtrl：：Create	建立標頭控件，並將它附加至 `CHeaderCtrl` 物件。
CHeaderCtrl：：CreateDragImage	在標頭控件中建立專案的影像透明版本。
CHeaderCtrl：：CreateEx	使用指定的 Windows 擴充樣式建立標頭控件，並將它附加至 `CListCtrl` 物件。
CHeaderCtrl：:D eleteItem	從標頭控件刪除專案。
CHeaderCtrl：:D rawItem	繪製標題控件的指定專案。
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。

備註

此方法會實作 Win32 訊息 HDM_CLEARFILTER 的行為，其數據行值為 -1，如 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
指定標頭控件的識別碼。

傳回值

如果初始化成功，則為非零;否則為零。

備註

您會在兩個步驟中建構 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
控制件的子視窗識別碼。

傳回值

如果成功則為非零；否則為 0。

備註

使用 CreateEx 而不是 Create 套用擴充的 Windows 樣式，由 Windows 擴充樣式前文WS_EX_指定。

CHeaderCtrl：：CreateDragImage

在標頭控件中建立專案的影像透明版本。

CImageList* CreateDragImage(int nIndex);

參數

nIndex
標頭控件內專案之以零起始的索引。指派給此專案的影像是透明影像的基礎。

傳回值

如果成功，則為 CImageList 物件的指標，否則為 NULL。傳回的清單只包含一個影像。

備註

此成員函式會實作 Win32 訊息 HDM_CREATEDRAGIMAGE的行為，如 Windows SDK 中所述。它提供以支持標題專案拖放。

傳 CImageList 回指標點所在的物件是暫存物件，並在下一個閑置時間處理中刪除。

CHeaderCtrl：:D eleteItem

從標頭控件刪除專案。

BOOL DeleteItem(int nPos);

參數

nPos
指定要刪除之專案之以零起始的索引。

傳回值

如果成功則為非零；否則為 0。

範例

int nCount = m_myHeaderCtrl.GetItemCount();

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

CHeaderCtrl：:D rawItem

當擁有者繪製標頭控件的視覺層面變更時，由架構呼叫。

virtual void DrawItem(LPDRAWITEMSTRUCT lpDrawItemStruct);

參數

lpDrawItemStruct
DRAWITEMSTRUCT 結構的指標，描述要繪製的專案。

備註

結構 itemAction 的成員 DRAWITEMSTRUCT 會定義要執行的繪圖動作。

根據預設，此成員函式不會執行任何動作。覆寫這個成員函式，以實作擁有者繪製對象的繪圖 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;

傳回值

具有焦點之標頭專案的以零起始的索引。

備註

這個方法會傳送 windows SDK 中所述的HDM_GETFOCUSEDITEM 訊息。

範例

第一個程式代碼範例會定義用來存取目前標頭控件的變數 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 結構的指標。這個結構會與和 SetItem 成員函式搭配InsertItem使用。元素中 mask 設定的任何旗標，可確保在傳回時正確填入對應元素中的值。如果元素 mask 設定為零，則其他結構元素中的值毫無意義。

傳回值

如果成功則為非零；否則為 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：:D eleteItem 的範例。

CHeaderCtrl：：GetItemDropDownRect

取得目前標題控件中標題專案的下拉式按鈕周框。

BOOL GetItemDropDownRect(
    int iItem,
    LPRECT lpRect) const;

參數

iItem
[in]標題專案的以零起始的索引，其樣式為HDF_SPLITBUTTON。如需詳細資訊，請參閱 fmt HDITEM 結構的成員。

lpRect
[out] 要接收周框資訊的 RECT 結構的指標。

傳回值

如果此函式成功，則為TRUE;否則為 FALSE。

備註

這個方法會傳送 windows SDK 中所述的 HDM_GETITEMDROPDOWNRECT訊息。

範例

第一個程式代碼範例會定義用來存取目前標頭控件的變數 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。

備註

此方法會實作 Win32 訊息 HDM_GETITEMRECT的行為，如 Windows SDK 中所述。

CHeaderCtrl：：GetOrderArray

擷取標頭控件中專案的由左至右順序。

BOOL GetOrderArray(
    LPINT piArray,
    int iCount);

參數

piArray
緩衝區位址的指標，接收標頭控件中專案的索引值，依它們從左至右出現的順序。

iCount
標頭控件項目的數目。必須是非負數。

傳回值

如果成功則為非零；否則為 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樣式，才能顯示溢位按鈕。周框會括住溢位按鈕，而且只有在顯示溢位按鈕時才存在。如需詳細資訊，請參閱標頭控件樣式。

這個方法會傳送 windows SDK 中所述的 HDM_GETOVERFLOWRECT訊息。

範例

第一個程式代碼範例會定義用來存取目前標頭控件的變數 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。

備註

這個方法會傳送 windows SDK 中所述的 HDM_HITTEST訊息。

範例

第一個程式代碼範例會定義用來存取目前標頭控件的變數 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
要插入之項目之以零起始的索引。如果值為零，則會在標頭控件的開頭插入專案。如果值大於最大值，則會在標頭控件的結尾插入專案。

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。

備註

此函式用來判斷要佔用指定矩形之新標頭控件的適當維度。

範例

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。

備註

這個方法會傳送 windows SDK 中所述的 HDM_SETFOCUSEDITEM訊息。

範例

第一個程式代碼範例會定義用來存取目前標頭控件的變數 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。

範例

請參閱 CHeaderCtrl：：GetItem 的範例。

CHeaderCtrl：：SetOrderArray

設定標頭控件中專案的由左至右順序。

BOOL SetOrderArray(
    int iCount,
    LPINT piArray);

參數

iCount
標頭控件項目的數目。

piArray
緩衝區位址的指標，接收標頭控件中專案的索引值，依它們從左至右出現的順序。

傳回值

如果成功則為非零；否則為 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：:D eleteItem

參數

傳回值

範例

CHeaderCtrl：:D rawItem

參數

備註

範例

CHeaderCtrl：：EditFilter

參數

傳回值

備註

範例

CHeaderCtrl：：GetBitmapMargin

傳回值

備註

範例

CHeaderCtrl：：GetFocusedItem

傳回值

備註

範例

CHeaderCtrl：：GetImageList

傳回值

備註

範例

CHeaderCtrl：：GetItem

參數

傳回值

範例

CHeaderCtrl：：GetItemCount

傳回值

範例

CHeaderCtrl：：GetItemDropDownRect

參數

傳回值

備註

範例

CHeaderCtrl：：GetItemRect

參數

傳回值

備註

CHeaderCtrl：：GetOrderArray

參數

傳回值

備註

範例

CHeaderCtrl：：GetOverflowRect