The ListView grouping feature (in Windows XP)

Size: px

Start display at page:

Download "The ListView grouping feature (in Windows XP)"

Theodora Henry
5 years ago
Views:

1 The ListView grouping feature (in Windows XP) Introduction The introduction of version 6 of the Common Controls Library in Windows XP didn t bring much improvement for the Windows (Common) Controls grouped in the Standard and Win32 tab of the component palette in Borland Delphi. Except for Theme support and a new control named SysLink, you won t notice anything revolutionary in the new Windows Operating system (at least in terms of Windows Controls). There is however one exception, the ListView control. If you study the CommCtrl header file provided with the latest Platform SDK, you will find about 30 new messages, 30 new constants and 10 new/changed structures for this control alone. These changes enable you to use three new features: Grouping. As its name suggests, this feature allows you to group items based on particular information. It s conceptually a way to create horizontal columns to group related sets of items, and use the ListView a bit like a simplified grid control. Windows XP uses it to display the content of My computer in explorer in a hierarchical way. Figure 1: A file explorer that would group entries by categories. Insertion marks. An insertion mark shows the user where a dragged item will be placed. Windows uses it when you move items of the Start menu, the Favorites menu, etc... Figure2: Insertion mark (MSDN picture). Tile view. This new view completes the icon, small icon, list and report views, and it combines the report view and the icon view styles.

2 Figure3: Tile-view style (MSDN picture). This article will focus only on the grouping feature. I will introduce you to the feature, then to the API calls, and I will end with my Delphi wrapper around the grouping feature. This article will assume that you are experienced enough to know what a handle is, and understand how to send Windows messages to controls (API calls), etc The grouping feature The grouping API is poorly documented and on several occasions misleading; in fact the whole feature looks like it is a first draft. One thing you can critisize immediately is that the API calls for the grouping feature are not consistent with the API calls for the columns; being conceptually the same thing you would have tought they would harmonize the way you create and, more importantly, manage the groups and the columns. The philosophy behind the groups is simple: you add groups by providing an ID and a caption (LVM_INSERTGROUP message); you update ListView items by changing the igroupid member of the updated LVITEM structure (LVM_SETITEM message) and make the groups visible by switching on the group view (LVM_ENABLEGROUPVIEW message). Note that the groups won t show if you are in list view style. If you are running Windows XP, you can use this new feature by calling these few API calls no matter what your Delphi version (4, 5, 6, or 7) and given that you have the CommCtrlEx.pas unit which is provided with this article (you need it even if you have Delphi 7). The unit is not a replacement of the CommCtrl unit but a necessary add-on to use the new ListView features. To enable the feature though, you also need to drop a TXPManifest component onto your form (for Delphi 7) or a TThemeManager component (for Delphi 4, 5 and 6; available from The component, when dropped on a form, includes a manifest file in your project and for Delphi 4, 5 and 6 also fixes a problem with the ListView control (which would otherwise generate a general protection fault). If you run the application on a previous operating system (Windows NT/2000, 9X/ME), nothing will happen; the groups simply won t show, so there will be no harm. You can call the DllGetversion function that the Common Controls Library exports to determine which library version is installed on the system and avoid using the XP features if needed (see Demo application). The API calls step by step Let s suppose you have a form with a ListView control and a XP component. A. Creating a group In order to create a group, you need to fill a LVGROUP structure with the appropriate flags and values and send a LVM_INSERTGROUP message to the ListView. Let s have a look at the structure first and then the way to use it in order to create the group. taglvgroup = packed record cbsize: UINT; mask: UINT; pszheader: PWideChar; cchheader: Integer;

3 pszfooter: PWideChar; cchfooter: Integer; igroupid: Integer; statemask: UINT; state: UINT; ualign: UINT; Listing 1: The LVGROUP structure. cbsize. Size of the LVGROUP structure used for internal Windows versioning. mask. This field can have one or several of these three working flags: LVGF_ALIGN, LVGF_HEADER and LVGF_GROUPID. LVGF_FOOTER and LVGF_STATE flags are ignored by Windows. When creating a new group, the LVGF_GROUPID is required. pszheader and cchheader. Header string and its size. Note that the header is in Unicode format. pszfooter and cchfooter. Ignored by Windows XP. igroupid: Unique identifier of the group. You need it to assign a ListView item to the group and also to change the attributes of the group. state. Ignored by Windows XP. ualign. Header alignment flag that can have one of the following values: LVGA_HEADER_LEFT, LVGA_HEADER_CENTER or LVGA_HEADER_RIGHT (left is default). Group: TLVGROUP; FillChar(Group, SizeOf(Group), 0); Group.cbSize := SizeOf(Group); Group.mask := LVGF_GROUPID or LVGF_HEADER; Group.pszHeader := 'Group 1'; Group.iGroupId := 101; ListView_InsertGroup(ListView1.Handle, -1, Group); Listing 2: Creating a group. There are three parts to Listing 2: The initialization part. Zeroing the LVGROUP structure, and assigning the size of the structure to the cbsize member. The data part. The minimal information you have to provide is a unique identifier. In this case, an ID and a caption are provided so the mask member is filled with the appropriate flags. The message. You can use the LVM_INSERTGROUP message or its associated macro ListView_InsertGroup(). In all case, you need to provide the handle of the ListView control, the 0-based index where the group is to be added (-1 adds the group at the end of the internal array), and the LVGROUP structure. If the call is successful, it returns the index of the new group, otherwise -1. The group is now added, but nothing will be visible yet. B. Moving ListView items to the appropriate groups When you enable the group feature with the LVM_ENABLEGROUPVIEW message, any ListView item whose igroupid member doesn t correspond to an existing group ID is hidden; all the others are grouped under the caption of their associated group. The updated LVITEM structure that is used to add and maintain a ListView item has a igroupid member that needs to be modified using this simple code:

4 Item: CommCtrlEx.TLVITEM; FillChar(Item, SizeOf(Item), 0); Item.mask := LVIF_GROUPID; Item.iItem := 0; Item.iGroupId := 101; CommCtrlEx.ListView_SetItem(ListView1.Handle, Item); Listing 3: Modifying the group id of a ListView item. Again three parts in Listing 3: The initialization part. Zeroing the LVITEM structure. The data part. The mask member specifies that only the group ID of the item is modified, iitem is the 0-based index of the ListView item and finally igroupid is the new group ID of the item. The message. You can use the LVM_SETITEM message or its associated macro ListView_SetItem(). If the call is successful, it returns True. Note that you have to use the updated LVITEM structure and ListView_SetItem() macro declared in the CommCtrlEx unit provided with this article. Unlike what you would expect the LVM_MOVEITEMTOGROUP message / ListView_MoveItemToGroup() macro aren t modifying the group ID of a ListView item In fact, that message isn t working at all. C. Enabling the group view This is as simple as sending the LVM_ENABLEGROUPVIEW message to the ListView or its associated macro ListView_EnableGroupView(). The macro requires two parameters: the ListView handle and a Boolean that indicates whether to enable or disable the group view. The call returns 1 if successful, 0 if the ListView is already enabled or disabled and -1 if the operation fails. Note that if you try this message on an older system, the call returns always 0. D. Managing the groups Checking if the group view mode is enabled Use the LVM_ISGROUPVIEWENABLED message / ListView_IsGroupViewEnabled() macro to check if the ListView is in group view mode. The macro requires the ListView handle and returns True is the group view is enabled otherwise False. Checking if a particular group exists To determine if a ListView has a specific group (identified by its ID), use the LVM_HASGROUP message / ListView_HasGroup() macro. The macro requires two parameters: the ListView handle and the group ID. It returns True if the group is present, otherwise False. Remove one or all groups To remove a group from the ListView control, use the LVM_REMOVEGROUP message / ListView_RemoveGroup() macro. The macro requires two parameters: the ListView handle and the group ID. To remove all groups, use the LVM_REMOVEALLGROUPS message / ListView_RemoveAllGroups() macro. Only the ListView handle is required. Keep in mind that a ListView item with an igroupid value that doesn t match an existing group is not displayed. When in group view mode, all items need to belong to a group.

5 Retrieving / Changing the data of a group To retrieve the caption and/or the alignment settings of a group, you have to use the LVM_GETGROUPINFO message / ListView_GetGroupInfo() macro. The macro requires three parameters: the ListView handle, the group ID and a LVGROUP structure with the appropriate flags for its mask member (see Listing 4). function GetGroupCaption(const GroupID: Integer): string; Group: TLVGROUP; FillChar(Group, SizeOf(Group), 0); Group.cbSize := SizeOf(Group); Group.mask := LVGF_HEADER; ListView_GetGroupInfo(ListView1.Handle, GroupID, Group); Result := string(widestring(group.pszheader)); Listing 4: Retrieving the caption string of a group Changing the caption (or alignment) of a group follows the same philosophy except that you have to use a workaround because of a bug in the LVM_SETGROUPINFO message / ListView_SetGroupInfo() macro. The bug (unless Microsoft defines it as a feature) prevents you from changing the caption if you don t change the identifier of the group. So the workaround is to work in two steps, first you change the caption and the identifier and then you change back the identifier to its original value (see Listing 5). procedure SetGroupCaption(const GroupID: Integer; const ACaption: string); Group: TLVGROUP; FillChar(Group, SizeOf(Group), 0); Group.cbSize := SizeOf(Group); Group.mask := LVGF_HEADER or LVGF_GROUPID; Group.iGroupId := MaxInt; Group.pszHeader := PWideChar(WideString(ACaption)); ListView_SetGroupInfo(ListView1.Handle, GroupID, Group); Group.mask := LVGF_GROUPID; Group.iGroupId := GroupID; ListView_SetGroupInfo(ListView1.Handle, MaxInt, Group); ListView1.Refresh; Listing 5: Changing the caption string of a group You have four parts in Listing 5: The initialization part. Zeroing the LVGROUP structure, and assigning the size of the structure to the cbsize member. Modification 1. The caption and the identifier of the group are modified. The mask, igroupid and pszheader members of the LVGROUP structure are filled accordingly. The new identifier is an arbitrary value that has no real importance. The ListView_SetGroupInfo() macro requires the three same parameters as the ListView_GetGroupInfo() macro. Modification 2. The caption is now modified; let s change back the identifier of the group to its original value. The ListView won t reflect the changes unless you call its refresh method.

6 Moving / Sorting groups You would think that the LVM_MOVEGROUP message / ListView_MoveGroup() macro would move a group to a new location (and that s what the SDK is saying). Unfortunately the message is not implemented (yet?). Fortunately you can sort the groups based on any criteria with the LVM_SORTGROUPS message / ListView_SortGroups() macro. To do so, you need to declare a non-method comparison function of this form (a function which is not a method of an object): function SortGroups(Group1_ID, Group2_ID: Integer; pvdata: Pointer): Integer stdcall; The macro requires three parameters: the ListView handle, a pointer to the comparison function and an optional pointer parameter (you can provide the ListView pointer for instance): ListView1); The comparison function is called each time the order to two groups needs to be compared. The Group1_ID parameter is the identifier of the first group being compared; and Group2_ID is the identifier of the second group. The pvdata parameter has the same value as the last parameter passed to the ListView_SortGroups() macro. The function has to return a negative value if the first group (that is the group with the Group1_ID identifier) should precede the second one, a positive value if it should follow it and zero if the two groups are equivalent. During the sorting process avoid sending any messages to the ListView, the results are unpredictable. So provided you want to sort the groups alphabetically, save the groups captions in a temporary array before the call. In Listing 6, the ListView control has 10 groups (ID 101 to ID 111) with an arbitrary caption and Button1, when pressed, sorts the groups alphabetically. function SortGroups(Group1_ID, Group2_ID: Integer; pvdata: Pointer): Integer; stdcall; Captions: array of string; Captions := pvdata; if Captions[Group1_ID-100-1] > Captions[Group2_ID-100-1] then Result := 1 else Result := -1; procedure TForm1.Button1Click(Sender: TObject); i: Integer; Captions: array of string; SetLength(Captions, 10); for i := 1 to 10 do Captions[i-1] := GetGroupCaption(100+i); Captions); Listing 6: sorting the groups alphabetically Retrieving / Changing the group metrics Behind the word group metrics is hiding two features: the ability to change the text color, and the border color and size at least in theory. Let s have a look at the LVGROUPMETRICS structure and discuss the difference between the theory and the reality. taglvgroupmetrics = packed record cbsize: UINT; mask: UINT; Left: UINT;

7 Top: UINT; Right: UINT; Bottom: UINT; crleft: COLORREF; crtop: COLORREF; crright: COLORREF; crbottom: COLORREF; crheader: COLORREF; crfooter: COLORREF; Listing 7: The LVGROUPMETRICS structure. cbsize. Size of the LVGROUPMETRICS structure used for internal Windows versioning. mask. This field can have one of these two working flags: LVGF_BORDERSIZE and LVGF_TEXTCOLOR. The LVGF_BORDERCOLOR flag is ignored by Windows XP. Left, Top, Right and Bottom. Values of the new border; those values are reflected differently depending of the ListView s view style: for instance the Left member is ignored in Report style. crleft, crtop, crright, crbottom. Values that should be used in conjunction with the LVGF_BORDERCOLOR flag currently ignored by the call. crheader. Text colour of the group string caption. crfooter. Ignored. The thing to keep in mind is that the group metrics settings are global to the ListView control, you cannot change the text colour for just one group. The ListView_SetGroupMetrics() macro requires then only two parameters: the ListView handle and a LVGROUPMETRICS structure. GroupMetrics: TLVGROUPMETRICS; FillChar(GroupMetrics, Sizeof(GroupMetrics), 0); GroupMetrics.cbSize := SizeOf(GroupMetrics); GroupMetrics.mask := LVGMF_TEXTCOLOR or LVGMF_BORDERSIZE; GroupMetrics.Top := 20; GroupMetrics.crHeader := ColorToRGB(clBlue); ListView_SetGroupMetrics(ListView1.Handle, GroupMetrics); Listing 8: Changing the group metrics. To retrieve the group metrics use the LVM_GETGROUPMETRICS / ListView_GetGroupMetrics() macro that requires the very same parameters as the ones to change the group metrics. The wrapper Included with this article is a TListViewEx component that wraps the grouping feature (unit ListViewEx provided with the article). This is my first component, so please be tolerant; my implementation follows very closely the implementation of the columns property. The ListView component has been modified and three new components have been created: TListGroups, TListGroup and TBordersWidth. Since the group feature needs a manifest to work, nothing is visible at design-time. The ListViewEx control has four new published properties and one unpublished: property GroupView: Boolean. Enables or disables the group mode. property GroupsHeaderTextColor: TColor. Specifies the color of the captions.

8 property Groups: TListGroups. Describes the properties of the groups in the list view. Use Groups to add or delete groups in the list view, or to edit their display properties (see below). property GroupsBordersWidth: TBordersWidth. Use GroupsBordersWidth to specify the left, top, right and bottom borders of the groups. [not published] property Group[Index: Integer]: TListGroup. Describes the group specified by the Index parameter (see below). The TListGroups represents a collection of TListGroup objects in a TListViewEx. At design time, use the list view control s Groups editor to add, remove, or modify columns. The TListGroup represents a group in a group-style list view and it has two important properties: property Alignment: TAlignment. Specifies how text is aligned within the group. property HeaderCaption: string. Specifies the text that appears at the top of the group. The ListViewEx control has also a new method: function SortGroups(SortProc: TLVGroupCompare; lparam: Longint): Boolean. Returns True if the group list is successfully sorted. type TLVGroupCompare = function(group1_id, Group2_ID: Integer; pvdata: Pointer): Integer stdcall; Conclusion The grouping feature brings something really useful because it enables you to visually group related items and this whatever the ListView view-style; or quite since the groups are not displayed in List view but it leaves you with Icons, Small icons, Report and the new Tile view-style. The documentation on this new feature is, as you may have noticed, misleading because several API calls and structure s members are not implemented yet. The philosophy behind the groups is quite easy once you have figured what works and what doesn t. If API calls gives you a big headache, then use the ListViewEx component provided with this article. If this component works, it was written by Fabio Lucarelli. If not, I don't know who wrote it (ok I admit it, I ve stolen this quote from P. DiLascia [MSDN]). You can use the group feature in many different types of applications. I personally use it a lot to display databases in a more hierarchical way (male/female, regions, etc ). I really hope that Microsoft will extend this feature in an upcoming version of the Common Controls Library.

Taskbar: Working with Several Windows at Once

Taskbar: Working with Several Windows at Once Your Best Friend at the Bottom of the Screen How to Make the Most of Your Taskbar The taskbar is the wide bar that stretches across the bottom of your screen,