CMFCListCtrl Class

The CMFCListCtrl class extends the functionality of CListCtrl Class class by supporting the advanced header control functionality of the CMFCHeaderCtrl Class.

Syntax

class CMFCListCtrl : public CListCtrl

Members

Public Methods

Name Description
CMFCListCtrl::EnableMarkSortedColumn Enables the ability to mark a sorted column with a different background color.
CMFCListCtrl::EnableMultipleSort Enables multiple sort mode.
CMFCListCtrl::GetHeaderCtrl Returns a reference to the underlined header control.
CMFCListCtrl::IsMultipleSort Checks if the list control is in multiple sort mode.
CMFCListCtrl::OnCompareItems Called by the framework when it must compare two list control items.
CMFCListCtrl::OnGetCellBkColor Called by the framework when it must determine the background color of an individual cell.
CMFCListCtrl::OnGetCellFont Called by the framework when it must obtain the font for the cell being drawn.
CMFCListCtrl::OnGetCellTextColor Called by the framework when it must determine the text color of an individual cell.
CMFCListCtrl::RemoveSortColumn Removes a sort column from the list of sorted columns.
CMFCListCtrl::SetSortColumn Sets the current sorted column and the sort order.
CMFCListCtrl::Sort Sorts the list control.

Remarks

CMFCListCtrl offers two enhancements to CListCtrl Class class. First, it indicates that column sorting is an available option by automatically drawing a sort arrow on the header. Second, it supports data sorting on multiple columns at the same time.

Example

The following example demonstrates how to use various methods in the CMFCListCtrl class. The example shows how to create a list control, insert columns, insert items, set the text of an item, and set the font of the list control. This code snippet is part of the Visual Studio Demo sample.

CMFCListCtrl m_wndWatch;
// DWORD dwStyle
// CRect rectDummy
m_wndWatch.Create(dwStyle, rectDummy, this, ID_LIST_1);
m_wndWatch.SendMessage(LVM_SETEXTENDEDLISTVIEWSTYLE, 0, LVS_EX_FULLROWSELECT | LVS_EX_GRIDLINES);
m_wndWatch.InsertColumn(0, _T("Variable"), LVCFMT_LEFT, 100);
m_wndWatch.InsertColumn(1, _T("Value"), LVCFMT_LEFT, 100);

m_wndWatch.InsertItem(0, _T("m_nCount"));
m_wndWatch.SetItemText(0, 1, _T("100"));

m_wndWatch.SetFont(&m_Font);

Inheritance Hierarchy

CObject

CCmdTarget

CWnd

CListCtrl

CMFCListCtrl

Requirements

Header: afxlistctrl.h

CMFCListCtrl::EnableMarkSortedColumn

Marks the sorted columns with a different background color.

void EnableMarkSortedColumn(
    BOOL bMark = TRUE,
    BOOL bRedraw = TRUE);

Parameters

bMark
[in] A Boolean parameter that determines whether to enable a different background color.

bRedraw
[in] A Boolean parameter that determines whether to redraw the control immediately.

Remarks

EnableMarkSortedColumn uses the method CDrawingManager::PixelAlpha to calculate what color to use for sorted columns. The color picked is based upon the regular background color.

CMFCListCtrl::EnableMultipleSort

Enables sorting the rows of data in the list control by multiple columns.

void EnableMultipleSort(BOOL bEnable = TRUE);

Parameters

bEnable
[in] A Boolean that specifies whether to enable multiple column sort mode.

Remarks

When you enable sorting based on multiple columns, the columns do have a hierarchy. The rows of data will first be sorted by the primary column. Any equivalent values are then sorted by each subsequent column based on priority.

CMFCListCtrl::GetHeaderCtrl

Returns a reference to the header control.

virtual CMFCHeaderCtrl& GetHeaderCtrl();

Return Value

A reference to the underlying CMFCHeaderCtrl object.

Remarks

The header control for a list control is the window that contains the titles for the columns. It's usually positioned directly above the columns.

CMFCListCtrl::IsMultipleSort

Checks whether the list control currently supports sorting on multiple columns.

BOOL IsMultipleSort() const;

Return Value

TRUE if the list control supports multiple sort; FALSE otherwise.

Remarks

When a CMFCListCtrl Class supports multiple sorting, the user can sort the data in the list control by multiple columns. To enable multiple sorting, call CMFCListCtrl::EnableMultipleSort.

CMFCListCtrl::OnCompareItems

The framework calls this method when it compares two items.

virtual int OnCompareItems(
    LPARAM lParam1,
    LPARAM lParam2,
    int iColumn);

Parameters

lParam1
[in] The first item to compare.

lParam2
[in] The second item to compare.

iColumn
[in] The index of the column that this method is sorting.

Return Value

An integer that indicates the relative position of the two items. A negative value indicates the first item should precede the second, a positive value indicates the first item should follow the second, and zero means the two items are equivalent.

Remarks

The default implementation always returns 0. Override this function to provide your own sorting algorithm.

CMFCListCtrl::OnGetCellBkColor

The framework calls this method when it must determine the background color of an individual cell.

virtual COLORREF OnGetCellBkColor(
    int nRow,
    int nColumn);

Parameters

nRow
[in] The row of the cell in question.

nColumn
[in] The column of the cell in question.

Return Value

A COLOREF value that specifies the background color of the cell.

Remarks

The default implementation of OnGetCellBkColor doesn't use the supplied input parameters and instead simply calls GetBkColor. Therefore, by default, the whole list control will have the same background color. You can override OnGetCellBkColor in a derived class to mark individual cells with a separate background color.

CMFCListCtrl::OnGetCellFont

The framework calls this method when it obtains the font for an individual cell.

virtual HFONT OnGetCellFont(
    int nRow,
    int nColumn,
    DWORD dwData = 0);

Parameters

nRow
[in] The row of the cell in question.

nColumn
[in] The column of the cell in question.

dwData
[in] User-defined data. The default implementation doesn't use this parameter.

Return Value

A handle to the font that is used for the current cell.

Remarks

By default, this method returns NULL. All of the cells in a list control have the same font. Override this method to provide different fonts for different cells.

CMFCListCtrl::OnGetCellTextColor

The framework calls this method when it must determine the text color of an individual cell.

virtual COLORREF OnGetCellTextColor(
    int nRow,
    int nColumn);

Parameters

nRow
[in] The row of the cell in question.

nColumn
[in] The column of the cell in question.

Return Value

A COLOREF value that specifies the text color of the cell.

Remarks

By default, this method calls GetTextColor regardless of input parameters. The whole list control will have the same text color. You can override OnGetCellTextColor in a derived class to mark individual cells with a separate text color.

CMFCListCtrl::RemoveSortColumn

Removes a sort column from the list of sorted columns.

void RemoveSortColumn(int iColumn);

Parameters

iColumn
[in] The column to remove.

Remarks

This method removes a sort column from the header control. It calls CMFCHeaderCtrl::RemoveSortColumn.

CMFCListCtrl::SetSortColumn

Sets the current sorted column and the sort order.

void SetSortColumn(
    int iColumn,
    BOOL bAscending = TRUE,
    BOOL bAdd = FALSE);

Parameters

iColumn
[in] The column to sort.

bAscending
[in] A Boolean that specifies the sort order.

bAdd
[in] A Boolean that specifies whether the method adds the column indicated by iColumn to the list of sort columns.

Remarks

This method passes the input parameters to the header control by using the method CMFCHeaderCtrl::SetSortColumn.

CMFCListCtrl::Sort

Sorts the list control.

virtual void Sort(
    int iColumn,
    BOOL bAscending = TRUE,
    BOOL bAdd = FALSE);

Parameters

iColumn
[in] The column to sort.

bAscending
[in] A Boolean that specifies the sort order.

bAdd
[in] A Boolean that specifies whether this method adds the column indicated by iColumn to the list of sort columns.

See also

Hierarchy Chart
Classes
CListCtrl Class