[.NET 2.0+] Custom Typed Collections and Data-binding Support

[jmcilhinney]

C# version here.

If we want to use a standard collection in .NET 2.0 or later we use a generic List. If we want to create our own strongly-typed collection we used to have to inherit CollectionBase. That was a pain because, in the days before generics, we used to have to define all the type-specific members ourselves. We would inherit members like Clear and RemoveAt from CollectionBase because they didn't depend on the type of the items. Members like Item and Add though, whose return type or parameter type(s) depends on the type of the items, were left up to us. Since the introduction of generics, life has become much easier. To create a strongly typed collection with all the standard functionality we simply inherit the generic Collection class and that's it:

Public Class ThingCollection
    Inherits System.Collections.ObjectModel.Collection(Of Thing)
End Class

All the standard functionality is inherited from the base class so we don't need to add any members of our own. That said, if we want to provide custom functionality then we can add our own members. The generic Collection class provides methods that you can override to process items as they are added and removed from the collection. One common use for those members is custom validation, e.g.

Public Class ThingCollection
    Inherits System.Collections.ObjectModel.Collection(Of Thing)
 
    Protected Overrides Sub InsertItem(ByVal index As Integer, ByVal item As Thing)
        Dim duplicateID As Boolean = False
 
        For Each existingItem As Thing In Me.Items
            If item.ID = existingItem.ID Then
                duplicateID = True
 
                Exit For
            End If
        Next
 
        If duplicateID Then
            'Don't add an item with a duplicate ID.
            Throw New ArgumentException("An item with the specified ID already exists")
        Else
            'Allow the item to be added.
            MyBase.InsertItem(index, item)
        End If
    End Sub
 
    Protected Overrides Sub SetItem(ByVal index As Integer, ByVal item As Thing)
        Dim duplicateID As Boolean = False
 
        For existingIndex As Integer = 0 To Me.Count - 1
            'Ignore the existing item at the index being set because it is being replaced.
            If existingIndex <> index AndAlso _
               item.ID = Me.Items(existingIndex).ID Then
                duplicateID = True
 
                Exit For
            End If
        Next
 
        If duplicateID Then
            'Don't add an item with a duplicate ID.
            Throw New ArgumentException("An item with the specified ID already exists")
        Else
            'Allow the item to be added.
            MyBase.SetItem(index, item)
        End If
    End Sub
 
End Class

So, that's nice and easy. Now, with regards to data-binding, you can quite easily bind either a generic List or your own strongly-typed collection to controls in your UI and the data they contain will be displayed. That's because they all implement the IList interface, which is all data-binding requires. The problem is, if you intend to make changes to your collection in code, like adding or removing items or editing properties of the items, then you'll be disappointed if you expect to see those changes reflected in the UI.

That's because the bound control is not implicitly aware of any changes taking place in the data source. It must be explicitly notified of changes in order to know that it should update its display. In order to provide such notification your data source must implement the IBindingList interface, which neither the generic List nor generic Collection class does. The easy way out of this is to bind your data to a BindingSource and then bind that to the control(s). You can then call ResetCurrentItem, ResetItem or RestBindings on the BindingSource to raise its ListChanged event and thereby notify the bound control to update.

That's all well and good, but what if the changes to the collection are occurring in code that can't see the BindingSource, like a business logic layer? In that case you need your collection to implement IBindingList itself. You could do that from scratch but you don't actually need to. Instead of deriving your collection directly from the generic Collection class, you can instead inherit the generic BindingList class, which itself inherits Collection and adds an IBindingList implementation. Again, you don't have to add any code of your own if you only want the standard functionality:

Public Class ThingCollection
    Inherits System.ComponentModel.BindingList(Of Thing)
End Class

Now your collection will raise its ListChanged event automatically whenever you add, insert, set or remove an item or clear the list. Any bound controls will automatically update as a result.

Now, that's fine for making changes to the list but what about if you make changes to items that are already in the list? Bound controls will not update automatically because the BindingList doesn't raise a ListChanged event automatically because it doesn't inherently know when an item changes. This is where you need to do a little bit of work.

What needs to happen is that your item class needs to raise an event when a property value changes, e.g.

Public Class Thing
 
    Private _name As String
 
    Public Property Name() As String
        Get
            Return Me._name
        End Get
        Set(ByVal value As String)
            If Me._name <> value Then
                Me._name = value
                Me.OnNameChanged(EventArgs.Empty)
            End If
        End Set
    End Property
 
    Public Event NameChanged As EventHandler
 
    Protected Overridable Sub OnNameChanged(ByVal e As EventArgs)
        RaiseEvent NameChanged(Me, e)
    End Sub
 
End Class

Your typed collection can now handle that event and raise its own ListChanged event to notify any bound controls of the change:

Public Class ThingCollection
    Inherits System.ComponentModel.BindingList(Of Thing)
 
    Private Sub HandleNameChanged(ByVal sender As Object, ByVal e As EventArgs)
        Me.OnListChanged(New ListChangedEventArgs(ListChangedType.ItemChanged, _
                                                  Me.Items.IndexOf(DirectCast(sender,  _
                                                                              Thing))))
    End Sub
 
End Class

Note that you specify ItemChanged as the change type.

Now, that method isn't going to handle any events on its own. We need to attach it to the NameChanged event of each item as it gets added to the list. We also need to make sure we detach when an item gets removed from the list. For that we need to override methods inherited from the Collection class, much as we did for the validation earlier:

Public Class ThingCollection
    Inherits System.ComponentModel.BindingList(Of Thing)
 
    Protected Overrides Sub InsertItem(ByVal index As Integer, ByVal item As Thing)
        MyBase.InsertItem(index, item)
 
        'Attach the event handler to the item being added.
        AddHandler item.NameChanged, AddressOf HandleNameChanged
    End Sub
 
    Protected Overrides Sub SetItem(ByVal index As Integer, ByVal item As Thing)
        'Remove the event handler from the item being removed.
        RemoveHandler Me.Items(index).NameChanged, AddressOf HandleNameChanged
 
        MyBase.SetItem(index, item)
 
        'Attach the event handler to the item being added.
        AddHandler item.NameChanged, AddressOf HandleNameChanged
    End Sub
 
    Protected Overrides Sub RemoveItem(ByVal index As Integer)
        'Remove the event handler from the item being removed.
        RemoveHandler Me.Items(index).NameChanged, AddressOf HandleNameChanged
 
        MyBase.RemoveItem(index)
    End Sub
 
    Protected Overrides Sub ClearItems()
        'Remove the event handler from all existing items.
        For Each item As Thing In Me.Items
            RemoveHandler item.NameChanged, AddressOf HandleNameChanged
        Next
 
        MyBase.ClearItems()
    End Sub
 
    Private Sub HandleNameChanged(ByVal sender As Object, ByVal e As EventArgs)
        Me.OnListChanged(New ListChangedEventArgs(ListChangedType.ItemChanged, _
                                                  Me.Items.IndexOf(DirectCast(sender,  _
                                                                              Thing))))
    End Sub
 
End Class

Another useful feature of the IBindingList interface is simple sorting support, i.e. sorting by a single column/property. By adding such support to your typed collection you enable, for instance, a user to click a column header in a DataGridView bound to your collection and have the data sorted automatically. I'll look at that in the next installment. Stay tuned!