This topic has not yet been rated Rate this topic

BindingList(Of T) Class

Provides a generic collection that supports data binding.

System.Object
  System.Collections.ObjectModel.Collection(Of T)
    System.ComponentModel.BindingList(Of T)

Namespace:  System.ComponentModel
Assembly:  System (in System.dll)
[SerializableAttribute]
[HostProtectionAttribute(SecurityAction.LinkDemand, SharedState = true)]
public class BindingList<T> : Collection<T>, 
	IBindingList, IList, ICollection, IEnumerable, ICancelAddNew, 
	IRaiseItemChangedEvents

Type Parameters

T

The type of elements in the list.

The BindingList(Of T) type exposes the following members.

  Name Description
Public method Supported by the XNA Framework BindingList(Of T) Initializes a new instance of the BindingList(Of T) class using default values.
Public method Supported by the XNA Framework BindingList(Of T)(IList(Of T)) Initializes a new instance of the BindingList(Of T) class with the specified list.
Top
  Name Description
Public property Supported by the XNA Framework AllowEdit Gets or sets a value indicating whether items in the list can be edited.
Public property Supported by the XNA Framework AllowNew Gets or sets a value indicating whether you can add items to the list using the AddNew method.
Public property Supported by the XNA Framework AllowRemove Gets or sets a value indicating whether you can remove items from the collection.
Public property Supported by the XNA Framework Count Gets the number of elements actually contained in the Collection(Of T). (Inherited from Collection(Of T).)
Protected property Supported by the XNA Framework IsSortedCore Gets a value indicating whether the list is sorted.
Public property Supported by the XNA Framework Item Gets or sets the element at the specified index. (Inherited from Collection(Of T).)
Protected property Supported by the XNA Framework Items Gets a IList(Of T) wrapper around the Collection(Of T). (Inherited from Collection(Of T).)
Public property Supported by the XNA Framework RaiseListChangedEvents Gets or sets a value indicating whether adding or removing items within the list raises ListChanged events.
Protected property Supported by the XNA Framework SortDirectionCore Gets the direction the list is sorted.
Protected property Supported by the XNA Framework SortPropertyCore Gets the property descriptor that is used for sorting the list if sorting is implemented in a derived class; otherwise, returns Nothing.
Protected property Supported by the XNA Framework SupportsChangeNotificationCore Gets a value indicating whether ListChanged events are enabled.
Protected property Supported by the XNA Framework SupportsSearchingCore Gets a value indicating whether the list supports searching.
Protected property Supported by the XNA Framework SupportsSortingCore Gets a value indicating whether the list supports sorting.
Top
  Name Description
Public method Supported by the XNA Framework Add Adds an object to the end of the Collection(Of T). (Inherited from Collection(Of T).)
Public method Supported by the XNA Framework AddNew Adds a new item to the collection.
Protected method Supported by the XNA Framework AddNewCore Adds a new item to the end of the collection.
Protected method Supported by the XNA Framework ApplySortCore Sorts the items if overridden in a derived class; otherwise, throws a NotSupportedException.
Public method Supported by the XNA Framework CancelNew Discards a pending new item.
Public method Supported by the XNA Framework Clear Removes all elements from the Collection(Of T). (Inherited from Collection(Of T).)
Protected method Supported by the XNA Framework ClearItems Removes all elements from the collection. (Overrides Collection(Of T).ClearItems.)
Public method Supported by the XNA Framework Contains Determines whether an element is in the Collection(Of T). (Inherited from Collection(Of T).)
Public method Supported by the XNA Framework CopyTo Copies the entire Collection(Of T) to a compatible one-dimensional Array, starting at the specified index of the target array. (Inherited from Collection(Of T).)
Public method Supported by the XNA Framework EndNew Commits a pending new item to the collection.
Public method Supported by the XNA Framework Equals(Object) Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Protected method Supported by the XNA Framework Finalize Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Protected method Supported by the XNA Framework FindCore Searches for the index of the item that has the specified property descriptor with the specified value, if searching is implemented in a derived class; otherwise, a NotSupportedException.
Public method Supported by the XNA Framework GetEnumerator Returns an enumerator that iterates through the Collection(Of T). (Inherited from Collection(Of T).)
Public method Supported by the XNA Framework GetHashCode Serves as a hash function for a particular type. (Inherited from Object.)
Public method Supported by the XNA Framework GetType Gets the Type of the current instance. (Inherited from Object.)
Public method Supported by the XNA Framework IndexOf Searches for the specified object and returns the zero-based index of the first occurrence within the entire Collection(Of T). (Inherited from Collection(Of T).)
Public method Supported by the XNA Framework Insert Inserts an element into the Collection(Of T) at the specified index. (Inherited from Collection(Of T).)
Protected method Supported by the XNA Framework InsertItem Inserts the specified item in the list at the specified index. (Overrides Collection(Of T).InsertItem(Int32, T).)
Protected method Supported by the XNA Framework MemberwiseClone Creates a shallow copy of the current Object. (Inherited from Object.)
Protected method Supported by the XNA Framework OnAddingNew Raises the AddingNew event.
Protected method Supported by the XNA Framework OnListChanged Raises the ListChanged event.
Public method Supported by the XNA Framework Remove Removes the first occurrence of a specific object from the Collection(Of T). (Inherited from Collection(Of T).)
Public method Supported by the XNA Framework RemoveAt Removes the element at the specified index of the Collection(Of T). (Inherited from Collection(Of T).)
Protected method Supported by the XNA Framework RemoveItem Removes the item at the specified index. (Overrides Collection(Of T).RemoveItem(Int32).)
Protected method Supported by the XNA Framework RemoveSortCore Removes any sort applied with ApplySortCore if sorting is implemented in a derived class; otherwise, raises NotSupportedException.
Public method Supported by the XNA Framework ResetBindings Raises a ListChanged event of type Reset.
Public method Supported by the XNA Framework ResetItem Raises a ListChanged event of type ItemChanged for the item at the specified position.
Protected method Supported by the XNA Framework SetItem Replaces the item at the specified index with the specified item. (Overrides Collection(Of T).SetItem(Int32, T).)
Public method Supported by the XNA Framework ToString Returns a string that represents the current object. (Inherited from Object.)
Top
  Name Description
Public event Supported by the XNA Framework AddingNew Occurs before an item is added to the list.
Public event Supported by the XNA Framework ListChanged Occurs when the list or an item in the list changes.
Top
  Name Description
Public Extension Method AsParallel Enables parallelization of a query. (Defined by ParallelEnumerable.)
Public Extension Method AsQueryable Converts an IEnumerable to an IQueryable. (Defined by Queryable.)
Public Extension Method Supported by the XNA Framework Cast(Of TResult) Converts the elements of an IEnumerable to the specified type. (Defined by Enumerable.)
Public Extension Method Supported by the XNA Framework OfType(Of TResult) Filters the elements of an IEnumerable based on a specified type. (Defined by Enumerable.)
Top
  Name Description
Explicit interface implemetation Private method Supported by the XNA Framework IBindingList.AddIndex For a description of this member, see AddIndex.
Explicit interface implemetation Private method Supported by the XNA Framework IBindingList.AddNew Adds a new item to the list. For more information, see AddNew.
Explicit interface implemetation Private property Supported by the XNA Framework IBindingList.AllowEdit Gets a value indicating whether items in the list can be edited.
Explicit interface implemetation Private property Supported by the XNA Framework IBindingList.AllowNew Gets a value indicating whether new items can be added to the list using the AddNew method.
Explicit interface implemetation Private property Supported by the XNA Framework IBindingList.AllowRemove Gets a value indicating whether items can be removed from the list.
Explicit interface implemetation Private method Supported by the XNA Framework IBindingList.ApplySort Sorts the list based on a PropertyDescriptor and a ListSortDirection. For a complete description of this member, see ApplySort.
Explicit interface implemetation Private method Supported by the XNA Framework IBindingList.Find For a description of this member, see Find.
Explicit interface implemetation Private property Supported by the XNA Framework IBindingList.IsSorted For a description of this member, see IsSorted.
Explicit interface implemetation Private method Supported by the XNA Framework IBindingList.RemoveIndex For a description of this member, see RemoveIndex.
Explicit interface implemetation Private method Supported by the XNA Framework IBindingList.RemoveSort For a description of this member, see RemoveSort
Explicit interface implemetation Private property Supported by the XNA Framework IBindingList.SortDirection For a description of this member, see SortDirection.
Explicit interface implemetation Private property Supported by the XNA Framework IBindingList.SortProperty For a description of this member, see SortProperty.
Explicit interface implemetation Private property Supported by the XNA Framework IBindingList.SupportsChangeNotification For a description of this member, see SupportsChangeNotification.
Explicit interface implemetation Private property Supported by the XNA Framework IBindingList.SupportsSearching For a description of this member, see SupportsSearching.
Explicit interface implemetation Private property Supported by the XNA Framework IBindingList.SupportsSorting For a description of this member, see SupportsSorting.
Explicit interface implemetation Private method Supported by the XNA Framework ICollection.CopyTo Copies the elements of the ICollection to an Array, starting at a particular Array index. (Inherited from Collection(Of T).)
Explicit interface implemetation Private property Supported by the XNA Framework ICollection(Of T).IsReadOnly Gets a value indicating whether the ICollection(Of T) is read-only. (Inherited from Collection(Of T).)
Explicit interface implemetation Private property Supported by the XNA Framework ICollection.IsSynchronized Gets a value indicating whether access to the ICollection is synchronized (thread safe). (Inherited from Collection(Of T).)
Explicit interface implemetation Private property Supported by the XNA Framework ICollection.SyncRoot Gets an object that can be used to synchronize access to the ICollection. (Inherited from Collection(Of T).)
Explicit interface implemetation Private method Supported by the XNA Framework IEnumerable.GetEnumerator Returns an enumerator that iterates through a collection. (Inherited from Collection(Of T).)
Explicit interface implemetation Private method Supported by the XNA Framework IList.Add Adds an item to the IList. (Inherited from Collection(Of T).)
Explicit interface implemetation Private method Supported by the XNA Framework IList.Contains Determines whether the IList contains a specific value. (Inherited from Collection(Of T).)
Explicit interface implemetation Private method Supported by the XNA Framework IList.IndexOf Determines the index of a specific item in the IList. (Inherited from Collection(Of T).)
Explicit interface implemetation Private method Supported by the XNA Framework IList.Insert Inserts an item into the IList at the specified index. (Inherited from Collection(Of T).)
Explicit interface implemetation Private property Supported by the XNA Framework IList.IsFixedSize Gets a value indicating whether the IList has a fixed size. (Inherited from Collection(Of T).)
Explicit interface implemetation Private property Supported by the XNA Framework IList.IsReadOnly Gets a value indicating whether the IList is read-only. (Inherited from Collection(Of T).)
Explicit interface implemetation Private property Supported by the XNA Framework IList.Item Gets or sets the element at the specified index. (Inherited from Collection(Of T).)
Explicit interface implemetation Private method Supported by the XNA Framework IList.Remove Removes the first occurrence of a specific object from the IList. (Inherited from Collection(Of T).)
Explicit interface implemetation Private property Supported by the XNA Framework IRaiseItemChangedEvents.RaisesItemChangedEvents Gets a value indicating whether item property value changes raise ListChanged events of type ItemChanged. This member cannot be overridden in a derived class.
Top

The BindingList(Of T) class can be used as a base class to create a two-way data-binding mechanism. BindingList(Of T) provides a concrete, generic implementation of the IBindingList interface. This is an alternative to implementing the complete IBindingList interface, which can be difficult because of the subtle interaction between IBindingList, IEditableObject, and the associated CurrencyManager. However, the typical solutions programmer will use a class that provides data binding functionality, such as BindingSource, instead of directly using BindingList(Of T).

BindingList(Of T) supports factory-created instances through the extensible AddNew method. (This same type of extensibility is also found in other classes, such as BindingSource) In addition, since this class implements the ICancelAddNew interface, it enables transactional commits or rollbacks of the new item through the EndNew and CancelNew methods.

Note Note

The HostProtectionAttribute attribute applied to this type or member has the following Resources property value: SharedState. The HostProtectionAttribute does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the HostProtectionAttribute class or SQL Server Programming and Host Protection Attributes.

The following code example demonstrates binding to a BindingList(Of T) component containing a business object. This is a complete example that contains a Main method.


using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Drawing;
using System.Text;
using System.Windows.Forms;

namespace BindingListOfTExamples
{
    public partial class Form1 : Form
    {
        private TextBox textBox2;
        private ListBox listBox1;
        private Button button1;
        private TextBox textBox1;
        Random randomNumber = new Random();

        public Form1()
        {
           this.AutoScaleMode = System.Windows.Forms.AutoScaleMode.Font;
           this.textBox1 = new System.Windows.Forms.TextBox();
           this.textBox2 = new System.Windows.Forms.TextBox();
           this.listBox1 = new System.Windows.Forms.ListBox();
           this.button1 = new System.Windows.Forms.Button();
           this.textBox1.Location = new System.Drawing.Point(169, 26);
           this.textBox1.Size = new System.Drawing.Size(100, 20);
           this.textBox1.Text = "Bracket";
           this.textBox2.Location = new System.Drawing.Point(169, 57);
           this.textBox2.ReadOnly = true;
           this.textBox2.Size = new System.Drawing.Size(100, 20);
           this.textBox2.Text = "4343";
           this.listBox1.FormattingEnabled = true;
           this.listBox1.Location = new System.Drawing.Point(12, 12);
           this.listBox1.Size = new System.Drawing.Size(120, 95);
           this.button1.Location = new System.Drawing.Point(180, 83);
           this.button1.Size = new System.Drawing.Size(75, 23);
           this.button1.Text = "Add New Item";
           this.button1.Click += new System.EventHandler(this.button1_Click);
           this.ClientSize = new System.Drawing.Size(292, 266);
           this.Controls.Add(this.button1);
           this.Controls.Add(this.listBox1);
           this.Controls.Add(this.textBox2);
           this.Controls.Add(this.textBox1);
           this.Text = "Parts Form";
           this.Load += new EventHandler(Form1_Load);

        }

        void Form1_Load(object sender, EventArgs e)
        {
            InitializeListOfParts();
            listBox1.DataSource = listOfParts;
            listBox1.DisplayMember = "PartName";
            listOfParts.AddingNew += new AddingNewEventHandler(listOfParts_AddingNew);
            listOfParts.ListChanged += new ListChangedEventHandler(listOfParts_ListChanged);

        }



        // Declare a new BindingListOfT with the Part business object.
        BindingList<Part> listOfParts; 
        private void InitializeListOfParts()
        {
            // Create the new BindingList of Part type.
            listOfParts = new BindingList<Part>();

            // Allow new parts to be added, but not removed once committed.        
            listOfParts.AllowNew = true;
            listOfParts.AllowRemove = false;

            // Raise ListChanged events when new parts are added.
            listOfParts.RaiseListChangedEvents = true;

            // Do not allow parts to be edited.
            listOfParts.AllowEdit = false;

            // Add a couple of parts to the list.
            listOfParts.Add(new Part("Widget", 1234));
            listOfParts.Add(new Part("Gadget", 5647));
        }


        // Create a new part from the text in the two text boxes.
        void listOfParts_AddingNew(object sender, AddingNewEventArgs e)
        {
            e.NewObject = new Part(textBox1.Text, int.Parse(textBox2.Text));

        }


        // Add the new part unless the part number contains
        // spaces. In that case cancel the add.
        private void button1_Click(object sender, EventArgs e)
        {
            Part newPart = listOfParts.AddNew();

            if (newPart.PartName.Contains(" "))
            {
                MessageBox.Show("Part names cannot contain spaces.");
                listOfParts.CancelNew(listOfParts.IndexOf(newPart));
            }
            else
            {
                textBox2.Text = randomNumber.Next(9999).ToString();
                textBox1.Text = "Enter part name";
            }
        }

        void listOfParts_ListChanged(object sender, ListChangedEventArgs e)
        {
            MessageBox.Show(e.ListChangedType.ToString());
        }

        [STAThread]
        static void Main()
        {
            Application.EnableVisualStyles();
            Application.Run(new Form1());
        }

    }

    // A simple business object for example purposes.
    public class Part
    {
        private string name;
        private int number;
        public Part() { }
        public Part(string nameForPart, int numberForPart)
        {
            PartName = nameForPart;
            PartNumber = numberForPart;
        }

        public string PartName
        {
            get { return name; }
            set { name = value; }
        }

        public int PartNumber
        {
            get { return number; }
            set { number = value; }
        }
    }
}


.NET Framework

Supported in: 4, 3.5, 3.0, 2.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

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.
Did you find this helpful?
(2000 characters remaining)
Community Content Add
Annotations FAQ
Fails in Visual Studio 2010 with .NET 4
I was testing the above VB code block in Visual Studio 2010 with the .NET 4 framework. The code works until you alter the properties of in item already in the list. The item updates but the list doesn't until you call Me.listBox1.ResetBindings() I thought the whole point of using the BindingList was so that it would update automatically. Can anyone confirm this, or illuminate me. Thanks. $0$0 $0 $0Edit: The associated properties are only updated when ResetBindings() is called. Note that there is also a method ResetItem, and that has its own pitfalls.$0
Also...Try...Implements INotifyPropertyChanged
'// VB example....
'// try adding to class T ...

Public Class MyBindClass
    Implements INotifyPropertyChanged
'
'IMPLEMENT THE "PROPERTY CHANGED" EVENT:
Public Event PropertyChanged As PropertyChangedEventHandler Implements INotifyPropertyChanged.PropertyChanged
'
' Create A CENTRALIZE subroutine for OnPropertyChanged method to raise the "PROPERTY CHANGED" event
Protected Sub OnPropertyChanged(ByVal name As String)
RaiseEvent PropertyChanged(Me, New PropertyChangedEventArgs(name))
End Sub
'
'// then add to each property the call to the Event...
'
    Private _someprop As String
    Public Property SomeProp() As String
        Get
            Return _someprop
        End Get
        Set(ByVal value As String)
            _someprop = value
            'Call PropertyChanged whenever the property is updated:
            OnPropertyChanged("SomeProp")
        End Set
    End Property
'
End Class
'// end.