Demonstrating List-View Backgrounds

List-View backgrounds turn out to have a rather rich configurability, but with the richness comes complexity that Microsoft seems to have some trouble keeping under control. Various bits of the functionality are either not documented at all, or only vaguely, and the whole is riddled with quirks.

In preparing these notes on List-View backgrounds and the relevant messages and structures, I have resorted not just to an occasional scrap of code to test this or that deduction: I have instead ended up with a substantial test rig which I make available here as a demonstration of both the good about List-View backgrounds and the plainly silly.

The LVBKTEST program presents a main window, containing a List-View control and a menu for acting on this control. The Window menu provides for enabling, disabling and redrawing the control. The View menu sets a view, e.g., Details rather than Icons, but works only with COMCTL32 version 6.0 and higher. The Styles menu provides for doing much the same but through the older method of setting the style bits masked by LVS_TYPEMASK. Use the Extended Styles menu to set or clear the LVS_EX_TRANSPARENTBKGND style, which is supported in COMCTL32 version 6.10 and higher. The Background menu provides for setting, clearing and asking about a background colour or image. The Column menu tells you what column is currently selected and lets you set, clear or ask about the colour that applies to the selected column. To select a column, get to the Details view and click on a column header.

Broadly speaking, each menu item corresponds to one window message. This helps demonstrate, for instance, that changing the background colour is two operations: one to send an LVM_SETBKCOLOR message, and another to redraw the control. Some menu items produce dialog boxes to gather parameters for the corresponding window message.

The program provides two hard-coded backgrounds to demonstrate cases where the List-View control does not itself draw its background. One of these is a custom background, implemented by having the control’s parent window handle the WM_ERASEBKGND message when the control has its background colour cleared. For this demonstration, the parent gives different list items different background colours set against another background colour for any of the control that isn’t occupied by list items. The other hard-coded background is the parent window’s own background, which for this demonstration is a gradient. This shows automatically in any part of the main window that is not occupied by the List-View control, and through the control if given the LVS_EX_TRANSPARENTBKGND style.

The List-View is populated only with a little sample data. Indeed, it is the same data that Microsoft uses for an SDK sample, because I mean to make the point that a demonstration (or test rig) such as this ought to be Microsoft’s work. There seems a reasonable suspicion that the feature’s bugs and quirks exist (and persist) mainly because Microsoft’s development of the feature is more about supporting Microsoft’s higher-level products than about providing a platform for the generality of non-Microsoft programming. While Microsoft makes an operating system, including its shell, it is not enough for Microsoft to test just that the features work in the various cases that Microsoft happens to use for Microsoft’s other purposes. General features need to be tested generally. That this hasn’t been done for List-View controls will be plain enough from a few minutes with the LVBKTEST program to verify any points of behaviour that are documented in these notes.

Run with /? for the syntax of configurable options:

• perform COM initialisation (the default), or not;
• load the best available COMCTL32 assembly (the default), else revert to version 5.82 or earlier;
• call the InitCommonControlsEx function (for List-View controls as the default), or not;
• operate on the control by sending window messages (the default), else by calling methods of the IListView interface;
• set the position and size of the control within the main window.

Note that COM initialisation is needed to set a background image specified by a URL and also to use the IListView interface. The dynamically loaded manifest asks for whatever version of COMCTL32 assembly is recommended by Windows itself through the windowsshell.manifest file in the Windows directory. Whether InitCommonControlsEx is required depends on the COMCTL32 version. The IListView interface is new for version 6.0. The program does not presently accommodate the new form of this interface in the version 6.10 from Windows 7.

For distribution, the built program (x86) is supplied with source code, compressed into one zip file: click here to download the List-View Background Test program (56KB).