CListCtrl For Beginners


Click here to change the theme.

The List Control (MFC CListCtrl class) is the type of control that the Windows Explorer uses for it's right-side pane, but figuring out how to use the control can be a different kind of pain. The control is usually used only in "report view", which provides columns for each item. The following shows the basics of adding data to a List Control:

	int Index;
// Insert columns
ListCtrl.InsertColumn(0, "One", LVCFMT_LEFT, -1, 0);
ListCtrl.InsertColumn(1, "Two", LVCFMT_LEFT, -1, 1);
// Insert first row
Index = ListCtrl.InsertItem(LVIF_TEXT, 0, "One one", 0, 0, 0, NULL);
ListCtrl.SetItem(Index, 1, LVIF_TEXT, "One two", 0, 0, 0, NULL);
// Insert second row
Index = ListCtrl.InsertItem(LVIF_TEXT, 1, "Two one", 0, 0, 0, NULL);
ListCtrl.SetItem(Index, 1, LVIF_TEXT, "Two two", 0, 0, 0, NULL);
// Set column widths (an optional nice touch)
ListCtrl.SetColumnWidth(0, LVSCW_AUTOSIZE);
ListCtrl.SetColumnWidth(1, LVSCW_AUTOSIZE);

If you are using CListView, then you will need to use something such as the following to access the CListCtrl:

CListCtrl &ListCtrl = GetListCtrl();

Note that for these to work, the control must have the "LVS_REPORT" style. For list controls in dialogs, including dialogs for CFormView, this style can be set in the dialog editor. If you are using CListView or you are creating list controls using Create, the style can be set in a PreCreateWindow override, as in:

BOOL CDumpView::PreCreateWindow(CREATESTRUCT& cs) {
cs.style |= LVS_REPORT;
return CListView::PreCreateWindow(cs);
}

Getting a Count of Columns

The solution for determining the number of columns is not obvious. You must get the header control from the list control and get the number of items (rows) in the header control. So I suggest putting the following in your header:

CHeaderCtrl *GetHeaderCtrl() const {return (CHeaderCtrl*)GetDlgItem(0);};
int GetColumnsCount() const {return GetHeaderCtrl()->GetItemCount();};

Deleting All Columns

Using GetColumnsCount() from above, it is easy to delete all columns.

void CListControl::DeleteAllColumns() {
	int i, n;
n = GetColumnsCount();
for (i=0; i<n; ++i)
	DeleteColumn(0);
}

Confusing Terminology

Microsoft has made things very confusing because the Platform SDK name for a listbox is "ListBox Control" but MFC programmers usually use "list control" to refer to an instance of the CListCtrl class, which is confusing. Also, the MFC class name for a "List View Control" is CListCtrl and CListView is the view class for it. The MFC class name for a "ListBox Control" is CListBox so we would expect the view class for it to also be CListView except there is not a view class. The following summarizes this.

Platform SDK name: List Boxes
Window class name: ListBox (See under "Predefined Controls" in User Controls and the documentation for CreateWindow and CreateWindowEx)
MFC class name: CListBox
MFC view class name: none

Platform SDK name: ListView Control
Window class name: SysListView32 (use WC_LISTVIEW in source code instead, which is defined as "SysListView32")
MFC class name: CListCtrl
MFC view class name: CListView