BindingSource Class

Definition

Namespace:

System.Windows.Forms

Assembly:

System.Windows.Forms.dll

Source:

BindingSource.cs

Encapsulates the data source for a form.

public ref class BindingSource : System::ComponentModel::Component, System::Collections::IList, System::ComponentModel::IBindingListView, System::ComponentModel::ICancelAddNew, System::ComponentModel::ISupportInitialize, System::ComponentModel::ISupportInitializeNotification, System::ComponentModel::ITypedList, System::Windows::Forms::ICurrencyManagerProvider

[System.ComponentModel.ComplexBindingProperties("DataSource", "DataMember")]
public class BindingSource : System.ComponentModel.Component, System.Collections.IList, System.ComponentModel.IBindingListView, System.ComponentModel.ICancelAddNew, System.ComponentModel.ISupportInitialize, System.ComponentModel.ISupportInitializeNotification, System.ComponentModel.ITypedList, System.Windows.Forms.ICurrencyManagerProvider

[<System.ComponentModel.ComplexBindingProperties("DataSource", "DataMember")>]
type BindingSource = class
    inherit Component
    interface IBindingListView
    interface ICollection
    interface IEnumerable
    interface IList
    interface IBindingList
    interface ITypedList
    interface ICancelAddNew
    interface ISupportInitializeNotification
    interface ISupportInitialize
    interface ICurrencyManagerProvider

Public Class BindingSource
Inherits Component
Implements IBindingListView, ICancelAddNew, ICurrencyManagerProvider, IList, ISupportInitialize, ISupportInitializeNotification, ITypedList

Inheritance

Object

MarshalByRefObject

Component

BindingSource

Attributes

ComplexBindingPropertiesAttribute

Implements

ICollection IEnumerable IList IBindingList IBindingListView ICancelAddNew ISupportInitialize ISupportInitializeNotification ITypedList ICurrencyManagerProvider

Examples

The following code example demonstrates a ListBox bound to a BindingSource. The BindingSource is bound to a BindingList<T> that contains a list of fonts.

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

namespace BindingSourceExamples
{
    public class Form1 : Form
    {
        [STAThread]
        static void Main()
        {
            Application.EnableVisualStyles();
            Application.Run(new Form1());
        }

        public Form1()
        {
            this.Load += new EventHandler(Form1_Load);
        }

        private TextBox textBox1;
        private Button button1;
        private ListBox listBox1;
       
        private BindingSource binding1;
        void Form1_Load(object sender, EventArgs e)
        {
            listBox1 = new ListBox();
            textBox1 = new TextBox();
            binding1 = new BindingSource();
            button1 = new Button();
            listBox1.Location = new Point(140, 25);
            listBox1.Size = new Size(123, 160);
            textBox1.Location = new Point(23, 70);
            textBox1.Size = new Size(100, 20);
            textBox1.Text = "Wingdings";
            button1.Location = new Point(23, 25);
            button1.Size = new Size(75, 23);
            button1.Text = "Search";
            button1.Click += new EventHandler(this.button1_Click);
            this.ClientSize = new Size(292, 266);
            this.Controls.Add(this.button1);
            this.Controls.Add(this.textBox1);
            this.Controls.Add(this.listBox1);

            MyFontList fonts = new MyFontList();
            for (int i = 0; i < FontFamily.Families.Length; i++)
            {
                if (FontFamily.Families[i].IsStyleAvailable(FontStyle.Regular))
                    fonts.Add(new Font(FontFamily.Families[i], 11.0F, FontStyle.Regular));
            }
            binding1.DataSource = fonts;
            listBox1.DataSource = binding1;
            listBox1.DisplayMember = "Name";
        }

        private void button1_Click(object sender, EventArgs e)
        {
            if (!binding1.SupportsSearching)
            {
                MessageBox.Show("Cannot search the list.");
            }
            else
            {
                int foundIndex = binding1.Find("Name", textBox1.Text);
                if (foundIndex > -1)
                    listBox1.SelectedIndex = foundIndex;
                else
                    MessageBox.Show("Font was not found.");
            }
        }
    }
    
    public class MyFontList : BindingList<Font>
    {

        protected override bool SupportsSearchingCore
        {
            get { return true; }
        }
        protected override int FindCore(PropertyDescriptor prop, object key)
        {
            // Ignore the prop value and search by family name.
            for (int i = 0; i < Count; ++i)
            {
                if (Items[i].FontFamily.Name.ToLower() == ((string)key).ToLower())
                    return i;
            }
            return -1;
        }
    }
}

Imports System.Collections.Generic
Imports System.ComponentModel
Imports System.Drawing
Imports System.Text
Imports System.Windows.Forms
Public Class Form1
    Inherits Form

    <STAThread()> _
    Shared Sub Main()
        Application.EnableVisualStyles()
        Application.Run(New Form1())

    End Sub

    Public Sub New()

    End Sub

    Private textBox1 As TextBox
    Private WithEvents button1 As Button
    Private listBox1 As ListBox
    Private components As IContainer
    Private binding1 As BindingSource

    Private Sub Form1_Load(ByVal sender As Object, ByVal e As EventArgs) Handles Me.Load
        listBox1 = New ListBox()
        textBox1 = New TextBox()
        binding1 = New BindingSource()
        button1 = New Button()
        listBox1.Location = New Point(140, 25)
        listBox1.Size = New Size(123, 160)
        textBox1.Location = New Point(23, 70)
        textBox1.Size = New Size(100, 20)
        textBox1.Text = "Wingdings"
        button1.Location = New Point(23, 25)
        button1.Size = New Size(75, 23)
        button1.Text = "Search"
        Me.ClientSize = New Size(292, 266)
        Me.Controls.Add(Me.button1)
        Me.Controls.Add(Me.textBox1)
        Me.Controls.Add(Me.listBox1)

        Dim fonts As New MyFontList()
        Dim i As Integer
        For i = 0 To FontFamily.Families.Length - 1
            If FontFamily.Families(i).IsStyleAvailable(FontStyle.Regular) Then
                fonts.Add(New Font(FontFamily.Families(i), 11.0F, FontStyle.Regular))
            End If
        Next i
        binding1.DataSource = fonts
        listBox1.DataSource = binding1
        listBox1.DisplayMember = "Name"

    End Sub
    Private Sub button1_Click(ByVal sender As Object, ByVal e As EventArgs) _
        Handles button1.Click

        If binding1.SupportsSearching <> True Then
            MessageBox.Show("Cannot search the list.")
        Else
            Dim foundIndex As Integer = binding1.Find("Name", textBox1.Text)
            If foundIndex > -1 Then
                listBox1.SelectedIndex = foundIndex
            Else
                MessageBox.Show("Font was not found.")
            End If
        End If

    End Sub
End Class

Public Class MyFontList
    Inherits BindingList(Of Font)

    Protected Overrides ReadOnly Property SupportsSearchingCore() As Boolean
        Get
            Return True
        End Get
    End Property
    
    Protected Overrides Function FindCore(ByVal prop As PropertyDescriptor, _
        ByVal key As Object) As Integer
        ' Ignore the prop value and search by family name.
        Dim i As Integer
        While i < Count
            If Items(i).FontFamily.Name.ToLower() = CStr(key).ToLower() Then
                Return i
            End If
            i += 1
        End While

        Return -1
    End Function
End Class

Remarks

The BindingSource component serves many purposes. First, it simplifies binding controls on a form to data by providing currency management, change notification, and other services between Windows Forms controls and data sources. This is accomplished by attaching the BindingSource component to your data source using the DataSource property. For complex binding scenarios you can optionally set the DataMember property to a specific column or list in the data source. You then bind controls to the BindingSource. All further interaction with the data is accomplished with calls to the BindingSource component. For examples on how the BindingSource can simplify the binding process, see How to: Bind Windows Forms Controls to DBNull Database Values and How to: Handle Errors and Exceptions that Occur with Databinding. Navigation and updating of the data source is accomplished through methods such as MoveNext, MoveLast, and Remove. Operations such as sorting and filtering are handled through the Sort and Filter properties. For more information on using sorting and filtering with the BindingSource, see How to: Sort and Filter ADO.NET Data with the Windows Forms BindingSource Component.

In addition, the BindingSource component can act as a strongly typed data source. Typically the type of the underlying data source is fixed through one of the following mechanisms:

• Use the Add method to add an item to the BindingSource component.

• Set the DataSource property to a list, single object, or type.

Both of these mechanisms create a strongly-typed list. For more information on how to use the BindingSource to bind to a type, see How to: Bind a Windows Forms Control to a Type. You can also use the BindingSource to bind your controls to a factory object. For more information on how to do this, see How to: Bind a Windows Forms Control to a Factory Object.

Note

Because a BindingSource handles both simple and complex data sources, terminology is problematic. Within this class documentation, the term list refers to a data collection within the hosted data source, and item denotes a single element. When discussing functionality associated with complex data sources, the equivalent terms table and row are used.

BindingSource provides members for accessing the underlying data. The current item can be retrieved through the Current property, and the entire list can be retrieved through the List property. Editing operations are supported on the current item through Current and the RemoveCurrent, EndEdit, CancelEdit and Add and AddNew methods. Although currency management is handled automatically for all underlying data source types, this class exposes a number of events, such as CurrentItemChanged and DataSourceChanged, that allow for customization.

Data sources that are bound to a BindingSource component can also be navigated and managed with the BindingNavigator class, which provides a VCR-like user interface (UI) for navigating items within a list. Although BindingNavigator can be bound to any data source, it was designed to integrate with a BindingSource component through its BindingNavigator.BindingSource property.

The default property for the BindingSource class is DataSource. The default event is CurrentChanged.

Caution

Many of the members of the BindingSource class operate on the underlying list represented by the List property and simply refer their operation to the underlying list. Therefore, when the BindingSource is bound to a custom implementation of IList, the exact behavior of these members may differ from the behavior described in the class documentation. For example, the RemoveAt method calls IList.RemoveAt. The BindingSource documentation describes the RemoveAt method with the understanding that the RemoveAt method for the underlying IList is correctly implemented.

Constructors

BindingSource()	Initializes a new instance of the BindingSource class to the default property values.
BindingSource(IContainer)	Initializes a new instance of the BindingSource class and adds the BindingSource to the specified container.
BindingSource(Object, String)	Initializes a new instance of the BindingSource class with the specified data source and data member.

Properties

AllowEdit	Gets a value indicating whether items in the underlying list can be edited.
AllowNew	Gets or sets a value indicating whether the AddNew() method can be used to add items to the list.
AllowRemove	Gets a value indicating whether items can be removed from the underlying list.
CanRaiseEvents	Gets a value indicating whether the component can raise an event. (Inherited from Component)
Container	Gets the IContainer that contains the Component. (Inherited from Component)
Count	Gets the total number of items in the underlying list, taking the current Filter value into consideration.
CurrencyManager	Gets the currency manager associated with this BindingSource.
Current	Gets the current item in the list.
DataMember	Gets or sets the specific list in the data source to which the connector currently binds to.
DataSource	Gets or sets the data source that the connector binds to.
DesignMode	Gets a value that indicates whether the Component is currently in design mode. (Inherited from Component)
Events	Gets the list of event handlers that are attached to this Component. (Inherited from Component)
Filter	Gets or sets the expression used to filter which rows are viewed.
IsBindingSuspended	Gets a value indicating whether the list binding is suspended.
IsFixedSize	Gets a value indicating whether the underlying list has a fixed size.
IsReadOnly	Gets a value indicating whether the underlying list is read-only.
IsSorted	Gets a value indicating whether the items in the underlying list are sorted.
IsSynchronized	Gets a value indicating whether access to the collection is synchronized (thread safe).
Item[Int32]	Gets or sets the list element at the specified index.
List	Gets the list that the connector is bound to.
Position	Gets or sets the index of the current item in the underlying list.
RaiseListChangedEvents	Gets or sets a value indicating whether ListChanged events should be raised.
Site	Gets or sets the ISite of the Component. (Inherited from Component)
Sort	Gets or sets the column names used for sorting, and the sort order for viewing the rows in the data source.
SortDescriptions	Gets the collection of sort descriptions applied to the data source.
SortDirection	Gets the direction the items in the list are sorted.
SortProperty	Gets the PropertyDescriptor that is being used for sorting the list.
SupportsAdvancedSorting	Gets a value indicating whether the data source supports multi-column sorting.
SupportsChangeNotification	Gets a value indicating whether the data source supports change notification.
SupportsFiltering	Gets a value indicating whether the data source supports filtering.
SupportsSearching	Gets a value indicating whether the data source supports searching with the Find(PropertyDescriptor, Object) method.
SupportsSorting	Gets a value indicating whether the data source supports sorting.
SyncRoot	Gets an object that can be used to synchronize access to the underlying list.

Methods

Add(Object)	Adds an existing item to the internal list.
AddNew()	Adds a new item to the underlying list.
ApplySort(ListSortDescriptionCollection)	Sorts the data source with the specified sort descriptions.
ApplySort(PropertyDescriptor, ListSortDirection)	Sorts the data source using the specified property descriptor and sort direction.
CancelEdit()	Cancels the current edit operation.
Clear()	Removes all elements from the list.
Contains(Object)	Determines whether an object is an item in the list.
CopyTo(Array, Int32)	Copies the contents of the List to the specified array, starting at the specified index value.
CreateObjRef(Type)	Creates an object that contains all the relevant information required to generate a proxy used to communicate with a remote object. (Inherited from MarshalByRefObject)
Dispose()	Releases all resources used by the Component. (Inherited from Component)
Dispose(Boolean)	Releases the unmanaged resources used by the BindingSource and optionally releases the managed resources.
EndEdit()	Applies pending changes to the underlying data source.
Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
Find(PropertyDescriptor, Object)	Searches for the index of the item that has the given property descriptor.
Find(String, Object)	Returns the index of the item in the list with the specified property name and value.
GetEnumerator()	Retrieves an enumerator for the List.
GetHashCode()	Serves as the default hash function. (Inherited from Object)
GetItemProperties(PropertyDescriptor[])	Retrieves an array of PropertyDescriptor objects representing the bindable properties of the data source list type.
GetLifetimeService()	Retrieves the current lifetime service object that controls the lifetime policy for this instance. (Inherited from MarshalByRefObject)
GetListName(PropertyDescriptor[])	Gets the name of the list supplying data for the binding.
GetRelatedCurrencyManager(String)	Gets the related currency manager for the specified data member.
GetService(Type)	Returns an object that represents a service provided by the Component or by its Container. (Inherited from Component)
GetType()	Gets the Type of the current instance. (Inherited from Object)
IndexOf(Object)	Searches for the specified object and returns the index of the first occurrence within the entire list.
InitializeLifetimeService()	Obtains a lifetime service object to control the lifetime policy for this instance. (Inherited from MarshalByRefObject)
Insert(Int32, Object)	Inserts an item into the list at the specified index.
MemberwiseClone()	Creates a shallow copy of the current Object. (Inherited from Object)
MemberwiseClone(Boolean)	Creates a shallow copy of the current MarshalByRefObject object. (Inherited from MarshalByRefObject)
MoveFirst()	Moves to the first item in the list.
MoveLast()	Moves to the last item in the list.
MoveNext()	Moves to the next item in the list.
MovePrevious()	Moves to the previous item in the list.
OnAddingNew(AddingNewEventArgs)	Raises the AddingNew event.
OnBindingComplete(BindingCompleteEventArgs)	Raises the BindingComplete event.
OnCurrentChanged(EventArgs)	Raises the CurrentChanged event.
OnCurrentItemChanged(EventArgs)	Raises the CurrentItemChanged event.
OnDataError(BindingManagerDataErrorEventArgs)	Raises the DataError event.
OnDataMemberChanged(EventArgs)	Raises the DataMemberChanged event.
OnDataSourceChanged(EventArgs)	Raises the DataSourceChanged event.
OnListChanged(ListChangedEventArgs)	Raises the ListChanged event.
OnPositionChanged(EventArgs)	Raises the PositionChanged event.
Remove(Object)	Removes the specified item from the list.
RemoveAt(Int32)	Removes the item at the specified index in the list.
RemoveCurrent()	Removes the current item from the list.
RemoveFilter()	Removes the filter associated with the BindingSource.
RemoveSort()	Removes the sort associated with the BindingSource.
ResetAllowNew()	Reinitializes the AllowNew property.
ResetBindings(Boolean)	Causes a control bound to the BindingSource to reread all the items in the list and refresh their displayed values.
ResetCurrentItem()	Causes a control bound to the BindingSource to reread the currently selected item and refresh its displayed value.
ResetItem(Int32)	Causes a control bound to the BindingSource to reread the item at the specified index, and refresh its displayed value.
ResumeBinding()	Resumes data binding.
SuspendBinding()	Suspends data binding to prevent changes from updating the bound data source.
ToString()	Returns a String containing the name of the Component, if any. This method should not be overridden. (Inherited from Component)

Events

AddingNew	Occurs before an item is added to the underlying list.
BindingComplete	Occurs when all the clients have been bound to this BindingSource.
CurrentChanged	Occurs when the currently bound item changes.
CurrentItemChanged	Occurs when a property value of the Current property has changed.
DataError	Occurs when a currency-related exception is silently handled by the BindingSource.
DataMemberChanged	Occurs when the DataMember property value has changed.
DataSourceChanged	Occurs when the DataSource property value has changed.
Disposed	Occurs when the component is disposed by a call to the Dispose() method. (Inherited from Component)
ListChanged	Occurs when the underlying list changes or an item in the list changes.
PositionChanged	Occurs after the value of the Position property has changed.

Explicit Interface Implementations

IBindingList.AddIndex(PropertyDescriptor)	Adds the PropertyDescriptor to the indexes used for searching.
IBindingList.RemoveIndex(PropertyDescriptor)	Removes the PropertyDescriptor from the indexes used for searching.
ICancelAddNew.CancelNew(Int32)	Discards a pending new item from the collection.
ICancelAddNew.EndNew(Int32)	Commits a pending new item to the collection.
ISupportInitialize.BeginInit()	Signals the BindingSource that initialization is starting.
ISupportInitialize.EndInit()	Signals the BindingSource that initialization is complete.
ISupportInitializeNotification.Initialized	Occurs when the BindingSource is initialized.
ISupportInitializeNotification.IsInitialized	Gets a value indicating whether the BindingSource is initialized.

Extension Methods

See also

• BindingSource
• BindingNavigator
• DataGridView
• CurrencyManager
• IList
• IBindingList
• IEditableObject
• BindingSource Component