CHeaderCtrl Class
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
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;
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::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.
See also
CWnd Class
Hierarchy Chart
CTabCtrl Class
CListCtrl Class
CImageList Class
Palaute
https://aka.ms/ContentUserFeedback.
Tulossa pian: Vuoden 2024 aikana poistamme asteittain GitHub Issuesin käytöstä sisällön palautemekanismina ja korvaamme sen uudella palautejärjestelmällä. Lisätietoja on täällä:Lähetä ja näytä palaute kohteelle