Export (0) Print
Expand All

ListViewGroupCollection Class

Represents the collection of groups within a ListView control.

System.Object
  System.Windows.Forms.ListViewGroupCollection

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

'Declaration
<ListBindableAttribute(False)> _
Public Class ListViewGroupCollection _
	Implements IList, ICollection, IEnumerable

The ListViewGroupCollection type exposes the following members.

  NameDescription
Public propertyCountGets the number of groups in the collection.
Public propertyItem(Int32)Gets or sets the ListViewGroup at the specified index within the collection.
Public propertyItem(String)Gets or sets the ListViewGroup with the specified ListViewGroup.Name property value.
Top

  NameDescription
Public methodAdd(ListViewGroup)Adds the specified ListViewGroup to the collection.
Public methodAdd(String, String)Adds a new ListViewGroup to the collection using the specified values to initialize the Name and Header properties
Public methodAddRange(ListViewGroup())Adds an array of groups to the collection.
Public methodAddRange(ListViewGroupCollection)Adds the groups in an existing ListViewGroupCollection to the collection.
Public methodClearRemoves all groups from the collection.
Public methodContainsDetermines whether the specified group is located in the collection.
Public methodCopyToCopies the groups in the collection to a compatible one-dimensional Array, starting at the specified index of the target array.
Public methodEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodGetEnumeratorReturns an enumerator used to iterate through the collection.
Public methodGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodIndexOfReturns the index of the specified ListViewGroup within the collection.
Public methodInsertInserts the specified ListViewGroup into the collection at the specified index.
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodRemoveRemoves the specified ListViewGroup from the collection.
Public methodRemoveAtRemoves the ListViewGroup at the specified index within the collection.
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Top

  NameDescription
Public Extension MethodAsParallelEnables parallelization of a query. (Defined by ParallelEnumerable.)
Public Extension MethodAsQueryableConverts an IEnumerable to an IQueryable. (Defined by Queryable.)
Public Extension MethodCast(Of TResult)Casts the elements of an IEnumerable to the specified type. (Defined by Enumerable.)
Public Extension MethodOfType(Of TResult)Filters the elements of an IEnumerable based on a specified type. (Defined by Enumerable.)
Top

  NameDescription
Explicit interface implemetationPrivate propertyICollection.IsSynchronizedInfrastructure. Gets a value indicating whether access to the collection is synchronized (thread safe).
Explicit interface implemetationPrivate propertyICollection.SyncRootInfrastructure. Gets an object that can be used to synchronize access to the collection.
Explicit interface implemetationPrivate methodIList.AddInfrastructure. Adds a new ListViewGroup to the ListViewGroupCollection.
Explicit interface implemetationPrivate methodIList.ContainsInfrastructure. Determines whether the specified value is located in the collection.
Explicit interface implemetationPrivate methodIList.IndexOfReturns the index within the collection of the specified value.
Explicit interface implemetationPrivate methodIList.InsertInserts a ListViewGroup into the ListViewGroupCollection.
Explicit interface implemetationPrivate propertyIList.IsFixedSizeGets a value indicating whether the collection has a fixed size.
Explicit interface implemetationPrivate propertyIList.IsReadOnlyGets a value indicating whether the collection is read-only.
Explicit interface implemetationPrivate propertyIList.ItemGets or sets the ListViewGroup at the specified index within the collection.
Explicit interface implemetationPrivate methodIList.RemoveRemoves the ListViewGroup from the ListViewGroupCollection.
Top

Use the ListView.Groups property to get the ListViewGroupCollection associated with a ListView control. This collection contains the ListViewGroup objects that represent the groups shown in the control when the ListView.View property is set to a value other than View.List. Any items that are not assigned to a group will appear in the default group, which has the header label "DefaultGroup{0}". The default group is not contained in the ListView.Groups collection, and cannot be altered. It is primarily useful in debugging to ensure that all items have been properly added to groups. If there are no groups in the ListView.Groups collection, the grouping feature is disabled.

Use the Add method to add a single group to the collection. Use the Insert method to add a group at a particular index within the collection. To remove a group, use the Remove method. Use the RemoveAt method to remove the group at a particular index.

You cannot add a ListViewGroup to the collection more than once. To reposition a group within the collection, it must first be removed from the collection, and then inserted at the desired location. Use the Contains method to determine whether a particular group is already in the collection. To retrieve the index of a group within the collection, use the IndexOf method. You can get or set the group at a particular index with the Item indexer.

Use the AddRange method to add multiple groups to the collection. You can add multiple groups either as an array of groups or as a ListViewGroupCollection that you retrieve through the ListView.Groups property of another ListView control. Use the Clear method to remove all the groups from the collection.

NoteNote

The Remove, RemoveAt, and Clear methods remove groups from the collection, but do not remove any items from the ListView control. If there are no groups in the ListView.Groups collection, the grouping feature is disabled and all items in the control are displayed normally.

The AddRange and Clear methods are 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 the next array of groups to display.

Use the CopyTo method to copy the groups in a collection to a compatible array starting at a specified index. This is useful, for example, when you want to sort the groups in the collection using the Array.Sort method. To do this, copy the groups into a compatible array, then sort the array. Next, use the Clear method to remove all the groups from the collection, then use the AddRange method to add the sorted array back to the collection.

Use the Count property to determine how many groups are in the collection. To iterate through the collection, use the IEnumerator returned from the GetEnumerator method.

NoteNote

The grouping feature is available only on Windows XP and the Windows Server 2003 family when your application calls the Application.EnableVisualStyles method. On earlier operating systems, any code relating to groups will be ignored and the groups will not appear. As a result, any code that depends on the grouping feature might not work correctly. You might want to include a test that determines whether the grouping feature is available, and provide alternate functionality when it is unavailable. For example, you might want to provide alternate sorting when running on operating systems that do not support sorting by group.

The insertion mark feature is provided by the same library that provides the operating system themes feature. To check for the availability of this library, call the FeatureSupport.IsPresent(Object) method overload and pass in the OSFeature.Themes value.

The following example demonstrates how to use the ListView grouping feature to organize 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. Clicking the header of a column sorts the items into the groups created for that column. Clicking the same column header again reverses the order of the groups.

Imports System
Imports System.Collections
Imports System.Windows.Forms

Public Class ListViewGroupsExample
    Inherits Form

    Private myListView As ListView

    ' Determine whether Windows XP or a later 
    ' operating system is present. 
    Private isRunningXPOrLater As Boolean = _
        OSFeature.Feature.IsPresent(OSFeature.Themes)

    ' Declare a Hashtable array in which to store the groups. 
    Private groupTables() As Hashtable

    ' Declare a variable to store the current grouping column. 
    Private groupColumn As Integer = 0

    Public Sub New()
        ' Initialize myListView.
        myListView = New ListView()
        myListView.Dock = DockStyle.Fill
        myListView.View = View.Details
        myListView.Sorting = SortOrder.Ascending

        ' Create and initialize column headers for myListView. 
        Dim columnHeader0 As New ColumnHeader()
        columnHeader0.Text = "Title"
        columnHeader0.Width = -1
        Dim columnHeader1 As New ColumnHeader()
        columnHeader1.Text = "Author"
        columnHeader1.Width = -1
        Dim columnHeader2 As New ColumnHeader()
        columnHeader2.Text = "Year"
        columnHeader2.Width = -1

        ' Add the column headers to myListView.
        myListView.Columns.AddRange( New ColumnHeader() _
            {columnHeader0, columnHeader1, columnHeader2} )

        ' Add a handler for the ColumnClick event. 
        AddHandler myListView.ColumnClick, AddressOf myListView_ColumnClick

        ' Create items and add them to myListView. 
        Dim item0 As New ListViewItem( New String() _
            {"Programming Windows", _
            "Petzold, Charles", _
            "1998"} )
        Dim item1 As New ListViewItem( New String() _
            {"Code: The Hidden Language of Computer Hardware and Software", _
            "Petzold, Charles", _
            "2000"} )
        Dim item2 As New ListViewItem( New String() _
            {"Programming Windows with C#", _
            "Petzold, Charles", _
            "2001"} )
        Dim item3 As New ListViewItem( New String() _
            {"Coding Techniques for Microsoft Visual Basic .NET", _
            "Connell, John", _
            "2001"} )
        Dim item4 As New ListViewItem( New String() _
            {"C# for Java Developers", _
            "Jones, Allen / Freeman, Adam", _
            "2002"} )
        Dim item5 As New ListViewItem( New String() _
            {"Microsoft .NET XML Web Services Step by Step", _
            "Jones, Allen / Freeman, Adam", _
            "2002"} )
        myListView.Items.AddRange( _
            New ListViewItem() {item0, item1, item2, item3, item4, item5})

        If isRunningXPOrLater
            ' Create the groupsTable array and populate it with one  
            ' hash table for each column.
            groupTables = New Hashtable(myListView.Columns.Count) {}
            Dim column As Integer 
            For column = 0 To myListView.Columns.Count - 1
                ' Create a hash table containing all the groups  
                ' needed for a single column.
                groupTables(column) = CreateGroupsTable(column)
            Next column

            ' Start with the groups created for the Title column.
            SetGroups(0)
        End If 

        ' Initialize the form. 
        Me.Controls.Add(myListView)
        Me.Size = New System.Drawing.Size(550, 330)
        Me.Text = "ListView Groups Example" 
    End Sub 'New

    <STAThread()> _
    Shared Sub Main()
        Application.EnableVisualStyles()
        Application.Run(New ListViewGroupsExample())
    End Sub 'Main

    ' Groups the items using the groups created for the clicked  
    ' column. 
    Private Sub myListView_ColumnClick( _
        sender As Object, e As ColumnClickEventArgs)

        ' Set the sort order to ascending when changing 
        ' column groups; otherwise, reverse the sort order. 
        If myListView.Sorting = SortOrder.Descending OrElse _
            isRunningXPOrLater And e.Column <> groupColumn Then
            myListView.Sorting = SortOrder.Ascending
        Else
            myListView.Sorting = SortOrder.Descending
        End If
        groupColumn = e.Column

        ' Set the groups to those created for the clicked column. 
        If isRunningXPOrLater Then
            SetGroups(e.Column)
        End If 
    End Sub 'myListView_ColumnClick

    ' 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 'SetGroups

    ' Creates a Hashtable object with one entry for each unique 
    ' subitem value (or initial letter for the parent item) 
    ' in the specified column. 
    Private Function CreateGroupsTable(column As Integer) As Hashtable
        ' Create a Hashtable object. 
        Dim groups As New Hashtable()

        ' Iterate through the items in myListView. 
        Dim item As ListViewItem
        For Each item In myListView.Items
            ' Retrieve the text value for the column. 
            Dim subItemText As String = item.SubItems(column).Text

            ' Use the initial letter instead if it is the first column. 
            If column = 0 Then
                subItemText = subItemText.Substring(0, 1)
            End If  

            ' If the groups table does not already contain a group 
            ' for the subItemText value, add a new group using the  
            ' subItemText value for the group header and Hashtable key. 
            If Not groups.Contains(subItemText) Then
                groups.Add( subItemText, New ListViewGroup(subItemText, _
                    HorizontalAlignment.Left) )
            End If 
        Next item

        ' Return the Hashtable object. 
        Return groups
    End Function 'CreateGroupsTable

    ' Sorts ListViewGroup objects by header value. 
    Private Class ListViewGroupSorter
        Implements IComparer 

        Private order As SortOrder

        ' Stores the sort order. 
        Public Sub New(theOrder As SortOrder)
            order = theOrder
        End Sub 'New 

        ' Compares the groups by header value, using the saved sort 
        ' order to return the correct value. 
        Public Function Compare(x As Object, y As Object) As Integer _
            Implements IComparer.Compare
            Dim result As Integer = String.Compare( _
                CType(x, ListViewGroup).Header, _
                CType(y, ListViewGroup).Header )
            If order = SortOrder.Ascending Then 
                Return result
            Else 
                Return -result
            End If 
        End Function 'Compare
    End Class 'ListViewGroupSorter 

End Class 'ListViewGroupsExample

.NET Framework

Supported in: 4.5.2, 4.5.1, 4.5, 4, 3.5, 3.0, 2.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Show:
© 2014 Microsoft