ListViewGroupCollection.AddRange Method (ListViewGroup[])


Adds an array of groups to the collection.

Namespace:   System.Windows.Forms
Assembly:  System.Windows.Forms (in System.Windows.Forms.dll)

public void AddRange(
	ListViewGroup[] groups


Type: System.Windows.Forms.ListViewGroup[]

An array of type ListViewGroup that specifies the groups to add to the collection.

Exception Condition

groups contains at least one group with at least one ListViewItem that belongs to a ListView control other than the one that owns this ListViewGroupCollection.

Use this version of the AddRange method to add an array of groups to the group collection. This method is useful when you create multiple ListViewGroup objects and want to add them to the collection with a single method call. To add individual groups to the collection, use the Add method.

This method is also useful when you want to provide multiple ways to group the items in a ListView control. To do this, create multiple group arrays. To change the grouping, first use the Clear method to remove all the groups from the collection, then use the AddRange method to add a different array of groups.

Unlike the Add method, the AddRange method does not have a return value that can be used to determine whether a group being added is already in the collection. If you need this information, use the Contains method before using the AddRange method.

The following example demonstrates how the AddRange method can be used in an application that organizes ListView items by subitem value in the details view. This form of grouping is similar to the grouping used in Windows Explorer. In the example, the groups are created dynamically. For each subitem column, one group is created for each unique subitem value. For the parent item column, one group is created for each unique initial letter. The groups created for each column are stored in a hash table along with the subitem text or initial letter. When a column header is clicked, the ListViewGroupCollection is cleared. The hash table corresponding to the clicked column is then retrieved and each item is assigned to the appropriate group. Finally, a sorted array of the groups in the hash table is added to the ListViewGroupCollection.

For the complete example, see the ListViewGroupCollection overview reference topic.

// Sets myListView to the groups created for the specified column.
private void SetGroups(int column)
    // Remove the current groups.

    // Retrieve the hash table corresponding to the column.
    Hashtable groups = (Hashtable)groupTables[column];

    // Copy the groups for the column to an array.
    ListViewGroup[] groupsArray = new ListViewGroup[groups.Count];
    groups.Values.CopyTo(groupsArray, 0);

    // Sort the groups and add them to myListView.
    Array.Sort(groupsArray, new ListViewGroupSorter(myListView.Sorting));

    // Iterate through the items in myListView, assigning each 
    // one to the appropriate group.
    foreach (ListViewItem item in myListView.Items)
        // Retrieve the subitem text corresponding to the column.
        string subItemText = item.SubItems[column].Text;

        // For the Title column, use only the first letter.
        if (column == 0) 
            subItemText = subItemText.Substring(0, 1);

        // Assign the item to the matching group.
        item.Group = (ListViewGroup)groups[subItemText];

.NET Framework
Available since 2.0
Return to top