ListViewGroupCollection.AddRange Method

Definition

Namespace:

System.Windows.Forms

Assembly:

System.Windows.Forms.dll

Adds multiple groups to the collection.

Overloads

AddRange(ListViewGroup[])	Adds an array of groups to the collection.
AddRange(ListViewGroupCollection)	Adds the groups in an existing ListViewGroupCollection to the collection.

AddRange(ListViewGroup[])

Adds an array of groups to the collection.

public:
 void AddRange(... cli::array <System::Windows::Forms::ListViewGroup ^> ^ groups);

public void AddRange (params System.Windows.Forms.ListViewGroup[] groups);

member this.AddRange : System.Windows.Forms.ListViewGroup[] -> unit

Public Sub AddRange (ParamArray groups As ListViewGroup())

Parameters

groups

ListViewGroup[]

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

Exceptions

ArgumentException

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.

InvalidOperationException

The ListView that this collection is assigned to is in virtual mode.

Examples

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.
      myListView->Groups->Clear();

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

      // Copy the groups for the column to an array.
      array<ListViewGroup^>^ groupsArray = gcnew array<ListViewGroup^>(groups->Count);
      groups->Values->CopyTo(groupsArray, 0);

      // Sort the groups and add them to myListView.
      Array::Sort(groupsArray, gcnew ListViewGroupSorter(myListView->Sorting));
      myListView->Groups->AddRange(groupsArray);

      // Iterate through the items in myListView, assigning each 
      // one to the appropriate group.
      IEnumerator^ myEnum = myListView->Items->GetEnumerator();
      while (myEnum->MoveNext())
      {
         ListViewItem^ item = safe_cast<ListViewItem^>(myEnum->Current);
         // 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 = dynamic_cast<ListViewGroup^>(groups[subItemText]);
      }
   }

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

    // 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));
    myListView.Groups.AddRange(groupsArray);

    // 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];
    }
}

' Sets myListView to the groups created for the specified column.
Private Sub SetGroups(column As Integer)
    ' Remove the current groups.
    myListView.Groups.Clear()
    
    ' Retrieve the hash table corresponding to the column.
    Dim groups As Hashtable = CType(groupTables(column), Hashtable)
    
    ' Copy the groups for the column to an array.
    Dim groupsArray(groups.Count - 1) As ListViewGroup
    groups.Values.CopyTo(groupsArray, 0)
    
    ' Sort the groups and add them to myListView.
    Array.Sort(groupsArray, New ListViewGroupSorter(myListView.Sorting))
    myListView.Groups.AddRange(groupsArray)
    
    ' Iterate through the items in myListView, assigning each 
    ' one to the appropriate group.
    Dim item As ListViewItem
    For Each item In myListView.Items
        ' Retrieve the subitem text corresponding to the column.
        Dim subItemText As String = item.SubItems(column).Text
        
        ' For the Title column, use only the first letter.
        If column = 0 Then
            subItemText = subItemText.Substring(0, 1)
        End If 

        ' Assign the item to the matching group.
        item.Group = CType(groups(subItemText), ListViewGroup)
    Next item
End Sub

Remarks

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.

See also

• ListViewGroup

AddRange(ListViewGroupCollection)

Adds the groups in an existing ListViewGroupCollection to the collection.

public:
 void AddRange(System::Windows::Forms::ListViewGroupCollection ^ groups);

public void AddRange (System.Windows.Forms.ListViewGroupCollection groups);

member this.AddRange : System.Windows.Forms.ListViewGroupCollection -> unit

Public Sub AddRange (groups As ListViewGroupCollection)

Parameters

groups

ListViewGroupCollection

A ListViewGroupCollection containing the groups to add to the collection.

Exceptions

ArgumentException

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.

InvalidOperationException

The ListView that this collection is assigned to is in virtual mode.

Remarks

Use this version of the AddRange method to add the elements of a ListViewGroupCollection that you retrieve through the ListView.Groups property of a different ListView control.

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.