Introduction

The use of list controls is becoming very common now, and is used by many apps with the need for some sort of list display. I have used list controls in many projects, and naturally have developed my own classes to display different colors, fonts, and progress bars in list control.

Recently I needed a list control with a checkbox like Hotmail. With a list like Hotmail you have checkbox in column header, and checkboxes in each subitem in that column. To set a check in every subitem, you check the checkbox in the column header. Similarly, if you uncheck one of the subitems, then the checkbox in the column header also gets unchecked.

What's New in 1.4

Subitem editing - thanks to Oleg Matcovsky for providing code that I based this implementation on.

Header checkboxes do not require resource bitmap - the file checkboxes.bmp, is still included in download, but it is no longer really necessary.

Enable ellipsis for text display.

Get modified flag for subitems.

More demo build configurations - 1.4 includes both DLL and static link build configurations, with 3 types of demo apps — dialogs, MDI, and property sheet — and 12 versions of the XListCtrl libraries, including both Unicode and ANSI.

DLL and static library versions - beginning with this version, all XListCtrl code has been organized as libraries that you link with. Table below shows library versions available.

Many bug fixes!

XListCtrl Features

The new CXListCtrl list control class supports these features:

Text and background colors may be specified for each subitem.

One or more subitem text may be displayed as normal or bold font.

One or more subitems may be switched from displaying text to displaying a progress bar, and then back again to text.

Custom text may be specified for progress bar, instead of just displaying usual 10%, 20%, etc. Also, there is option to display no text for progress bar, just the bar itself.

One or more subitems may contain checkbox, with or without text.

One or more subitems may contain combobox control.

One or more subitems may contain edit control.

A row may be disabled, so that checkboxes are unclickable.

The header is displayed flat like Outlook.

XListCtrl Demo

The demo project provides a sample app that shows what the various features look like. Press the Start button and the list control is filled with data.

First column is specified with checkboxes

The second column shows subitem with bold text

The second column shows subitem with different background color

The third column contains progress bar in row 2

The fourth column also contains checkboxes

The fifth column shows subitem with different background color

The sixth column shows subitem with different text and background colors

The second column shows combobox

The sixth row is disabled

The fifth column shows edit control

How To Use

To integrate XListCtrl into your own app, you first need to decide if you want to include XListCtrl code into your own exe (using XListCtrl static link library), or if you want to link to XListCtrl DLL. Using DLL version of XListCtrl makes sense if you plan to use XListCtrl in several apps. The XListCtrl DLL is an MFC extension DLL, so your app must also be MFC-based.

If you plan to use and distribute DLL version of XListCtrl, do not put DLL in Windows directory. This could cause conflicts with other apps that use XListCtrl, and some future version of XListCtrl may not be compatible with the one that you distribute.

To use static XListCtrl library, define symbol XLISTCTRLLIB_STATIC before including header file XListCtrl.h. Otherwise, DLL version of XListCtrl will be linked to your app. Regardless of which version you link with, you must change your app's build environment as follows:

Go to Project | Settings | C/C++ | Preprocessor and add the XListCtrl source directory to Additional include directories. Also, on the left side of the Settings dialog, choose All Configurations. Click OK to save this setting.

Go to Project | Settings | Link | Input and add the XListCtrl library directory to Additional library path. Again, on the left side of the Settings dialog, choose All Configurations. Click OK to save this setting.

Automatic Library Selection

Using symbols _AFXDLL, XLISTCTRLLIB_STATIC, _DEBUG, and _UNICODE, the following code in XListCtrl.h automatically determines which XListCtrl library to link to your app:

Building XListCtrl Libraries

To build the XListCtrl libraries, go to Build | Batch Build and select the libraries you wish to build:

Then click on Rebuild All and the libraries will be built. By default, the .lib and .dll files are copied to the bin directory.

Tips and Tricks

Rebuilding dialog demos - If you rebuild any of the dialog demos, be sure to use Rebuild All command. Reason: the dialog demos all share the same output file directories, and you will get linker errors if you compile only one module, and try to link with modules that were compiled with different set of build options.

Eliminate flickering - When updating or filling the list control, there is sometimes flickering of list control and/or other controls on dialog. To eliminate this flickering, you may try one of the following methods:

Use CListCtrl::LockWindowUpdate()/CListCtrl::UnlockWindowUpdate() to bracket the updating code.

Use CListCtrl::SetRedraw(FALSE)/CListCtrl::SetRedraw(TRUE) to bracket the updating code.

After using one of these methods, you probably should call list.UpdateWindow() to make sure control is updated. If one method doesn't completely eliminate flickering in your application, try other method to determine which works best.

Using tooltips - You must first call CListCtrl::EnableToolTips(TRUE).

Using combobox and edit controls - You must set LVS_EX_FULLROWSELECT style.

Revision History

Version 1.4 Changes

Subitem editing

New combo box implementation

Skip disabled items

APIs to set header alignment, text color, and divider lines

Set cell padding

Reduced flickering

Header checkboxes do not require resource bitmap

Enable ellipsis for text display

API to get modified flag for subitems

More demo build configurations

DLL and static library versions

Many bug fixes!

Version 1.3 Changes

This version includes many bug fixes that have been accumulating. My thanks for all who have reported bugs. Please try this new version and let me know if you find any bugs, or have suggestions for future enhancements.

Added hot-tracking to combo's listbox.

Added compile-time option to remove support for comboboxes. (This reduce exe size by about 8 Kb). To remove combobox support, put this line in stdafx.h:

#define DO_NOT_INCLUDE_XCOMBOLIST

If you insert this define, you do not need to include XComboList.cpp or XComboList.h in your project.

Fixed bug that caused string to not be displayed when clicking outside item string (reported by James Moore). This also caused problems in property pages and other places.

Fixed bug that caused some strings not to be selected, when drag-selecting several items quickly (reported by James Moore).

Fixed several problems with displaying images in header and list control (reported by Scot Brennecke).

Changed message map macros for NM_CLICK and LVN_COLUMNCLICK to use ON_NOTIFY_REFLECT_EX(), to allow parent to handle message also (suggested by bkupcins).

Fixed problem in XHeaderCtrl caused when XP theming is enabled. The GetHeaderCheckedState()/SetHeaderCheckedState() functions now use 0 = no check box, 1 = unchecked check box, 2 = checked check box. Note: The checkboxes.bmp file has also been updated, and must be replaced in all project that use 1.3 XListCtrl. The new defines XHEADERCTRL_NO_IMAGE, XHEADERCTRL_UNCHECKED_IMAGE, and XHEADERCTRL_CHECKED_IMAGE should be used when setting the image in the header control (see XListCtrlTestDlg.cpp for example).

Replaced calls to GetSysColor() with class variables that are set in ctor. Class variables are reloaded in response to WM_SYSCOLORCHANGE message (suggested by KarstenK).

Added ASSERT if combo boxes are used without LVS_EX_FULLROWSELECT style.

Added two registered messages that XListCtrl will send to its parent when combo box selection is changed (WM_XLISTCTRL_COMBO_SELECTION) and when check box is clicked (WM_XLISTCTRL_CHECKBOX_CLICKED). The sample app shows how to handle these new messages.

Added support for tooltips. To enable tooltips, you must call CListCtrl::EnableToolTips(TRUE). If you #define constant NO_XLISTCTRL_TOOL_TIPS, the tooltip support will not be included. New API's for tooltips:

Version 1.2.1 Changes

Version 1.2 Changes

Comboboxes!!! Now you can specify drop-list combobox for one or more subitem.

Combobox will be drawn when item is highlighted. Demo now has item hot-tracking.

Incorporated David Patrick's suggestion on how to subclass header control if CXListCtrl is created dynamically via Create() instead of via dialog template. See XListCtrlTestDlg.cpp for details on how to convert the demo project to create CXListCtrl dynamically.

Usage

This software is released into the public domain. You are free to use it in any way you like, except that you may not sell this source code. If you modify it or extend it, please to consider posting new code here for everyone to share. This software is provided "as is" with no expressed or implied warranty. I accept no liability for any damage or loss of business that this software may cause.

Share

About the Author

I attended St. Michael's College of the University of Toronto, with the intention of becoming a priest. A friend in the University's Computer Science Department got me interested in programming, and I have been hooked ever since.

Recently, I have moved to Los Angeles where I am doing consulting and development work.

For consulting and custom software development, please see www.hdsoft.org.

Has anyone been able to purchase the latest version of this software from the Hans Dietrich website. It does not work for me and I would like to use some of the features he has added to the latest version.

Hi,
I am using xlistctrl, but I found that there is a bug about xlistctrl when you create a combo box(droplist) in it, and I click the combo box, just click, no need to select one of the droplist, so when I click it(not one , click them randomly) very fast, then program will crash down.

Very nice control! Here are some suggestions for enhancements (perhaps they are already in v2.4 but there is a problem with Hans' website on the XListCtrl page when purchasing - has anyone successfully purchased v2.4?):

1) Allow enable/disable by item and subitem.2) Allow set text length by item and subitem.3) Get and Set Combo box selection by index instead of by text string only.4) Handle VK_TAB and go to the next item/subitem that is enabled (see item 1).5) Remove code in OnXEditKillFocus() that restores the original string. That way the user can clear out their text if desired.

Using v1.3, I've got a control with two columns. The first is a checkbox column, the second is a text column. No matter what alignment I try, they both want to be centered. I'd like them to be left justified instead. I also pulled code from the sample (VIEWCLASS::InitListCtrl) and it centers everything as well.

Any ideas? Is this a problem with v1.3 and was fixed in v1.4, perhaps?

Using v1.4, I got XListCtrlDDDU.dll and XListCtrlDDRU.dll successfully compiled, but when I run my test app (which is an MFC app that compiles and links fine), I get nothing. I briefly see it show up in Task Manager, but then it goes away. I copied the appropriate DLL into the same folder as my test EXE. Trying to run it from outide the IDE produces the same. If I change CXListCtrl to CListCtrl, the app starts and the list control is populated.