functionality of the VB ListView controls
The "ListView" control in both Comctl32.ocx and Mscomctl.ocx is simply a wrapper
that superclasses (encapsulates) the real "listview" common control in
Comctl32.dll. This allows the real listview common control messages and definitions to be
used to override almost every aspect of the VB ListView control.
The listview common control messages and definitions can be found in a C header file named
Commctrl.h. This file used to have a friendly URL on the MS site, but doesn't anymore for
some reason. It appears that the only alternatives for obtaining this file are to either
grab a copy of Visual Studio, or download either of the fairly huge INetSDK or PlatformSDK
But, instead of going to all of the trouble to find the darned download that contains
Commctrl.h (wherever it is), and then having to convert the C definitions to VB, well, you
can get the whole shebang right here. The follow zip contains *every* listview definition
and macro converted to VB, through Comctl32.dll v4.71 (IE4, excluding the listview's
CustomDraw definitions). Most listview examples that will eventually appear below will use
only the necessary subset of these definitions, keeping each example as clear and simple
Download lvdefs_471.zip (9kb)
Last update: 08/30/99
LVItemDrag: How to dynamically drag selected
ListItems in the VB ListView.
Even though one or more ListItems can be selected in the ListView whose
MultiSelect property is set to True (whose LVS_SINGLESEL window style is not set), unlike
familiar Explorer functionality, only the focused ListItem moves when dragging the
selection. This demo solves this shortcoming, but not without a little work.
When the left or right mouse button is depressed and moved over ListItem, typically four
pixels in any direction, the real listview sends its parent window a LVN_BEGINDRAG or
LVN_BEGINRDRAG notification message, respectively. For left button dragging, when the VB
ListView receives a LVN_BEGINDRAG, it begins repositioning the ListItem under the cursor.
The ListView does not respond to LVN_BEGINRDRAG, and provides no right button item
dragging facility. Once either notification has been processed and dragging has begun, the
ListView stops raising its MouseMove event, until the respective button is released. So,
in order to provide multiple ListItem repositioning with the left mouse button, right
button ListItem repositioning, and continue the receive the MouseMove event, the
ListView's parent window (typically a Form) must be subclassed, where both notifications
can be detected, and eaten (not passed to the CallWindowProc API function).
Also, when in large or small icon view, the view area inside the ListView's client window
in which its icons reside can grow to be much larger than the size of the ListView's
client window. If an ListItem is dragged to the edge of the ListView client window, the
view becomes enlarged and is shifted in the opposite direction. Because item positions
(ListItem Left and Top properties) are coordinates relative to the view's 0-0 coordinates,
and not the upper-left corner of the ListView client window, this amount of view shifting
must be considered when positioning ListItems using the ListView client cursor position.
The demo makes heavy use of the LVM_GETORIGIN message, which returns the pixel coordinates
of the ListView client window's upper-left corner relative to the shifted view's 0-0
Not only does the demo show how to move all selected ListItems with the mouse during a
dragging operation, but also solves the annoying behavior where the ListView will scroll
wildly when the selected ListItem is dragged near the ListView client window edge.
Download lvitemdrag.zip (9kb)
Last update: 08/30/99
LVDragImage: How to create a drag image of selected
As does the previous demo, this demo also shows how to move selected ListItems in the
ListView, but takes a completely different, and quite a bit more complex approach, by
showing how to create Explorer like drag images for selected ListView ListItems.
If a single item is dragged in Explorer's listview, a faded image of that item is created
and "attached" to the cursor. If multiple items are selected and dragged, on
< Win2K OSs (Win95, Win98, NT4), the drag image is just an outline of the selected
items' icons and labels. On Win2K, the drag image is comprised of the selected items'
actual icons and labels, that are not only faded (just like a single item's drag image),
but are highlighted as well. This demo shows how to create all three drag image styles:
outlined, faded, and faded and highlighted; how to move the drag image with the cursor,
and finally how to reposition all selected items to where they are dropped inside the
To create a faded (and not highlighted) drag image of a single item, the listview's
LVM_CREATEDRAGIMAGE message is normally used. But since the listview has no means to
create a drag image for multiple items, as well as no message for creating an outlined, or
faded and highlighted drag image, the demo shows how to actually construct and draw all
three drag image styles in a memory DC for one or more items. Though not the most
efficient of methods, the demo uses the services of the imagelist drag APIs to move the
constructed image around the screen with the cursor.
Even if the amount of code and overhead required to provide drag image functionality may
not be practical, it is still interesting to see how it can be done.
Download lvdragimage.zip (27kb)
Last update: 08/30/99
SystemImagelist: How to associate the system
imagelist with the VB ListView.
To display icons in the VB ListView, typically a VB ImageList would be added to the
project, filled with icons, and associated with the ListView's Icons and/or SmallIcons
properties. But what if you wanted the ListView to use the icons from the system imagelist
just as Explorer does? The solution seems obvious enough, send the ListView a
LVM_SETIMAGELIST message, specifying the system imagelist's handle for either or both
small or large icons. Well, that works, but there are a few more details to consider...
First, the VB ListView only knows how to talk to and use images from a VB ImageList. As a
result, after assigning the system imagelist to the ListView with the LVM_SETIMAGELIST
message, when it comes time for the ListView to display or update ListItem icons, the
ListView will then send itself another LVM_SETIMAGELIST message, specifying the handle of
the VB ImageList associated with its current view (either the Icons or SmallIcons
ImageLists). If no VB ImageList is associated with the current view, the ListView
will then specify 0 for the message's lParam value. Either way, your system imagelist
assignment is removed and the ListView doesn't use its icons. The solution? Assign the
system imagelist to the ListView with the LVM_SETIMAGELIST message, subclass the ListView,
and eat (don't call CallWindowProc) all subsequent LVM_SETIMAGELIST messages that the
ListView sends itself.
Next, since the ListView is now using the system imagelist, it no longer needs a VB
ImageList. In fact, as far as the VB ListView's internal code is concerned, it's not using
an ImageList. But how do we assign the image indices to each icon? Each ListView icon's
image index must now be explicitly set with the listview's LVM_SETITEM message. The real
listview code that the VB ListView encapsulates will then automatically display the icon
for each ListItem for the icon's specified index within the system imagelist.
But this method presents one problem little. Since there is no VB ImageList holding icon
images for the ListView to talk to, each ListItem's Icon and SmallIcon properties are
uninitialized, and cannot be used. In order to retrieve an ListItem's Icon and SmallIcon
in a Picture object, a four part process must now be used. First the real listview icon
index of the specified item must be obtained (real listview item indices correspond to
zero-based *physical item positions* in the listview, as opposed to ListItem.Index that
corresponds to the one-based position in the ListItems collection). Second, the specified
item's assigned icon index in the system imagelist is obtained with the LVM_GETITEM
listview message. Third, the item's icon handle is obtained from its system imagelist
index with the ImageList_GetIcon API. And finally, the icon handle is converted into a
Picture object with the OleCreatePictureIndirect API.
Though much more code intensive and complicated than using the VB ImageList, assigning a
real imagelist to the ListView is not only many more times faster than the VB ImageList,
but is also incredibly less resource intensive as well (the real imagelist use only one
GDI handle for a single bitmap that includes all icon images within it, where anywhere
from two to four GDI handles are used **for each ListImage in the VB ImageList**). Not
much of consideration there...
The following code example demonstrates all which was discussed above by showing not only
how to fill the ListView with all icons found in the system imagelist, but also how to
fill the ListView with all icons of registered file types, including their corresponding
file type descriptions.
Download systemimagelist.zip (11kb)
Last update: 08/30/99
LVCustomDraw: How to use custom draw in the
Listview custom draw allows any font, text color, and background color to be specified for
any or all ListItems. No long explanation about what custom draw is, and how it works,
just a demo that shows the interesting effects it can produce (uses subclassing).
Download lvcustomdraw.zip (9kb)
Last update: 08/30/99
LVItemTree: How to create a hierarchical ListView
(with buttons like a treeview)
This example shows how to set ListView item state images and indent values simulating a
hierarchical tree with expandable and collapsible items, identical to that of the Outlook
news reader's message list pane.
The working code is fairly simple: a "+" state icon is added to a collapsed
parent ListItem with the LVM_SETITEM message; when the parent ListItem is expanded, the
state icon is replaced with the "-" icon; as each child ListItem is Added under
the expanded parent, its indent is increased by setting the LVITEM's iIndent member, and
is also given a "+" state icon. When an expanded parent ListItem is collapsed,
the "-" state icon is replaced with the "+" icon, and all ListItems
with an indent value greater than the parent ListItem are removed.
11-14-99 update (v1.20)
- Now toggles the expanded state of parent items on a left mouse button double click
- Now scrolls selected items and child items of expanded parent items fully into view
- Modified keyboard support for expanding/collapsing parent items providing keyboard
navigational functionality identical to that of the TreeView.
- Now provides functionality for the full range of TreeView Node relational properties:
Parent, Child, FirstSibling, LastSibling, PrevSibling, NextSibling; and then some:
Parents, Siblings, Children
10-24-99 update (v1.10)
- Added keyboard support for expanding/collapsing parent items
- Added dynamic column header resizing
09-17-99 initial release (v1.00)
Download lvitemtree2.zip (8kb)
Last update: 11/14/99
LVHeaderSortIcons: How to display custom sort icons
in ListView column headers
Another fairly simple, yet useful example showing how to display the "\/" and
"/\" icons in ListView column headers indicating the actively sorted column and
its sort direction.
The demo contains a class that can be added to any project that uses a ListView in report
view. The class creates its own real imagelist with the ImageList_Create API, and the two
sort direction icons are added with the ImageList_AddIcon macro. When a ListView
ColumnHeader is clicked, the client calls the class' SetHeaderIcons method, specifying the
active ColumnHeader's Index, and its sort direction.The code in the method then removes
any icon from the previously sorted ColumnHeader, and sets the new icon with the
HDM_SETITEM header message. Note that this code only works on IE3 and greater
Much of this demo's inspiration was drawn from Randy Birch's "How to Add Images to a
ListView Header" code at http://www.mvps.org/vbnet/code/comctl/lvheaderimage.htm,
which does things a bit differently...
Download lvheadersorticons.zip (5kb)
Last update: 10/03/99
VBDirectoryLV: How to create a hierarchical
ListView that thinks its a TreeView (and displays directories)
This demo picks up where the LVItemTree demo above left off, and incorporates all of the
functionality in the Directory TreeView demo. Though the result
is code not having a whole lot of practical every day value, it is rather interesting
study of ListView functionality none the less: a ListView that does folders just like VB
For all intents and purposes, the ListView in this demo looks and behaves exactly like the
TreeView, and it is difficult to distinguish the differences, except for three key
elements: no tree lines; folder icons become selected along with their item labels; and
there are no item tips for obscured item labels. But other than that, the ListView is a
Download vbdirectorylv.zip (19kb)
Last update: 11/14/99
LVItemTips: ListView item tips galore
As always, the demos available here tend to be a little more involved and bigger than
most, but this one pushes the ragged edge of what may be viewed as practical and usable.
It none the less does provide some rather necessary functionality: item tips anywhere any
everywhere in the VB ListView, including report view subitems.
Attempting to describe what the demo does and why it does it could take thousands of
words, it's just not a simple task. But the demo's concept is essentially this: a class
module is used to create, position and control the visibility of a real tooltip common
control, allowing it to appear over any ListItem or SubItem whose label text is not
entirely visible (either obscured by the ListView's client window or truncated with an
ellipsis), in all ListView views. Though the code is as always heavily commented, even if
it can't be fully understood, it least what it does can be appreciated...
The class has been tested on and was found to work successfully with both the Comctl32.ocx
and Mscomctl.ocx ListViews, the real common control listview, and on all current flavors
of Windows that are running Comctl32.dll v4.70 (IE3) and greater.
Download lvitemtips.zip (15kb)
Last update: 11/14/99
Miscellaneous ListView demos that never got much
Below is a list of VB ListView demos that were developed in response to newsgroup
inquiries. Though they weren't deemed worthy of having their own separate sections here on
this page, they still may provide some usefulness to those interested...
setshellview1.zip (3kb) Shows how to change the view of
any SHELLDLL_DefView listview, including the desktop and common dialog listviews. (last
lvselectionex.zip (3kb) Shows how to provide individual
item click selection in the VB ListView so that other selected items do not become
de-selected, identical to a multiselect ListBox. (last update 09/26/99)
lvsubitemedit.zip (5kb) Shows how to provide in-place
editing of VB ListView report view subitems. Though not 100% clean in functionality, this
demo does provide the essential core concept of positioning a VB TextBox directly over
subitems. (last update 10/04/99)
lv16x16dragicon.zip (10kb) Though nowhere near the
robustness of the LV Drag Image demo above, this demo does provide some rather useful
code: it shows two distinct methods of creating a 32x32 drag image from a 16x16 drag image
in code (ala CreateDragImage) that can be assigned directly to the ListView's DragIcon
property. (last update 11/01/99)