WinapiZone.net

How to use groups in a listview

The first time i saw that the MSDN docs weren't good enough was when i tried to use the "group in listview" feature in one of my softwares. It seemed easy and well documented (although without any example) but when i started using it, it didn't work at all. That's why i'm making this tutorial: but, of course, i've managed to do it! But let's start from the beginning.

How to add a group

Before you add a group, you must meet these requirements:

• the application must include a manifest to tell windows to load the CommonControls dll version 6 (comclt32.dll)
• the listview must have the LVS_REPORT style
• you have already added some columns

Now, before adding a group, you must enable the group view mode by sending LVM_ENABLEGROUPVIEW or by calling the ListView_EnableGroupView macro. It's somewhat like switching between list and details view.

We're ready now. Add a group is easy, the same as adding a listview item: you just need to fill a structure (the LVGROUP structure) and pass it to the listview by sending the LVM_INSERTGROUP message or by calling the ListView_InsertGroup macro. A group should have an ID, that is necessary to add items to it and can be used to retrieve and set informations about a group (you can't do it through index). Here's an example:
The comments should explain everything. Now, if you try and compile, you'll see no group. Why? Well, because a group will not be visible until you add items to it. This is at the same time a good feature and a bad feature. It's a good feature because you may insert a lot of groups, but it's not sure you will fill all of them (for example, what if each group is a letter?): you'll agree that empty groups should be hidden. But, it's a bad feature because, especially in the beginning, how do you know that you're doing everything right? You'll see this when we will try to add items to a group.
As of now, i assure you have correctly added a group.

How to add items to a group

Here comes the problematic part.
You should already know how to add an item to a listview: through the LVITEM structure and the LVM_INSERTITEM message or the ListView_InsertItem macro. Looking to the LVITEM structure documentation, the only thing that seems related to groups is the member variable iGroupID and the LVIF_GROUPID flag for the mask variable.
Let's set it then:
Compile and run. Still no group visible? Now you see what was the problem before. I went looking to the code to insert a group and tried different solutions, but the problem was not there.

The solution, although i don't quite understand it (!), is to add the LVIF_COLUMNS flag to the mask flags, without even filling the associated member variable, cColumns. This will bring up the group and all its items.
So the "correct" code (well, the WORKING code) to add an item to a group is:


Tada!
You should also know that, like a group is hidden when it has no items, an item is hidden when it has no group.

See the example sources for a complete example with more than one group and item.

Comments

JugglerRick wrote:

jean wrote:

Eoin wrote:

thewasp wrote:

Your comment:
Name:	E-mail or homepage:
Captcha:

Script by Alex