ListView.Groups Property


The .NET API Reference documentation has a new home. Visit the .NET API Browser on to see the new experience.

Gets the collection of ListViewGroup objects assigned to the control.

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

Public ReadOnly Property Groups As ListViewGroupCollection

Property Value

Type: System.Windows.Forms.ListViewGroupCollection

A ListViewGroupCollection that contains all the groups in the ListView control.

The ListView grouping feature lets you create visual groups of logically related ListView items. Each group consists of a textual header followed by a horizontal line and the items assigned to that group. You can align the header text to the left, right, or center of the control. Any groups assigned to a ListView control appear whenever the View property is set to a value other than View.List.

ListView groups help your users find the items they are looking for by separating the items into useful categories. You can create whatever categories you need. One typical approach is to group the items based on the way the list is sorted. For example, you can group the items by the initial letter of the item name when the list is sorted alphabetically or by subitems such as type or date when the list is sorted by clicking a column header in the details view. Windows Explorer uses this type of grouping.

To use the grouping feature, add one or more ListViewGroup objects to the Groups collection of a ListView control. Set the group header text and header alignment in the ListViewGroup constructor, or set them using the ListViewGroup.Header and ListViewGroup.HeaderAlignment properties.

To temporarily disable the grouping feature, set the ShowGroups property to false.

You can assign an item to a group by specifying the group in the ListViewItem constructor, by setting the ListViewItem.Group property, or by directly adding the item to the ListViewGroup.Items collection of a group. All items should be assigned to groups before they are displayed. 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 Groups collection, and cannot be altered. It is primarily useful in debugging to ensure that all items have been properly added to groups.

An item can only be in one group at a time. You can change the group to which an item belongs by setting the ListViewItem.Group property at run time or by adding it to the ListViewGroup.Items collection of another group, which automatically removes it from the previous group.

The insertion mark feature is disabled when using groups. This is because the grouping feature orders items by group membership, while the insertion mark feature is used with drag-and-drop repositioning in a ListView control that does not already order its items.

ListView groups are available only on Windows XP and Windows Server 2003 when your application calls the Application.EnableVisualStyles method. On earlier operating systems, any code relating to groups has no effect 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 code 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 grouping 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 code 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 = _

    ' 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.
        End If

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

    <STAThread()> _
    Shared Sub Main()
        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
            myListView.Sorting = SortOrder.Descending
        End If
        groupColumn = e.Column

        ' Set the groups to those created for the clicked column.
        If isRunningXPOrLater Then
        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.

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

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

        ' 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
                Return -result
            End If
        End Function 'Compare
    End Class 'ListViewGroupSorter 

End Class 'ListViewGroupsExample

.NET Framework
Available since 2.0
Return to top