System.Windows.Forms.Binding Class

Represents the simple binding between the property value of an object and the property value of a control.

See Also: Binding Members


public class Binding


Use the System.Windows.Forms.Binding class to create and maintain a simple binding between the property of a control and either the property of an object, or the property of the current object in a list of objects.

As an example of the first case, you can bind the Control.Text property of a System.Windows.Forms.TextBox control to the FirstName property of a Customer object. As an example of the second case, you can bind the Control.Text property of a System.Windows.Forms.TextBox control to the FirstName property of a System.Data.DataTable that contains customers.

The System.Windows.Forms.Binding class also enables you to format values for display through the Binding.Format event and to retrieve formatted values through the Binding.Parse event.

When constructing a System.Windows.Forms.Binding instance with Binding.#ctor(string, object, string, bool) constructor, you must specify three items:

First, you must specify name of the control property you want to bind the data to. For example, to display data in a System.Windows.Forms.TextBox control, specify the TextBoxBase.Text property.

Second, you can specify an instance of any one of the classes in the following table as the data source.

Any class that implements System.ComponentModel.IBindingList or System.ComponentModel.ITypedList. These include the following: System.Data.DataSet, System.Data.DataTable, System.Data.DataView, or System.Data.DataViewManager.


DataSet ds = new DataSet("myDataSet");
Any class that implements IList to create an indexed collection of objects. The collection must be created and filled before creating the System.Windows.Forms.Binding. The objects in the list must all be of the same type; otherwise, an exception will be thrown.


ArrayList ar1 = new ArrayList;

Customer1 cust1 = new Customer("Louis");

A strongly typed IList of strongly typed objects


Customer [] custList = new Customer[3];

Third, you must specify the navigation path, which can be an empty string (""), a single property name, or a period-delimited hierarchy of names. If you set the navigation path to an empty string, the object.ToString method will be called on the underlying data source object.

If the data source is a System.Data.DataTable, which can contain multiple System.Data.DataColumn objects, the navigation path must be used to resolve to a specific column.


When the data source is a System.Data.DataSet, System.Data.DataViewManager, or System.Data.DataTable, you are actually binding to a System.Data.DataView. Consequently, the bound rows are actually System.Data.DataRowView objects.

A period-delimited navigation path is required when the data source is set to an object that contains multiple System.Data.DataTable objects (such as a System.Data.DataSet or System.Data.DataViewManager). You can also use a period-delimited navigation path when you bind to an object whose properties return references to other objects (such as a class with properties that return other class objects). For example, the following navigation paths all describe valid data fields:

Each member of the path can return either a property that resolves to a single value (such as an integer), or a list of values (such as an array of strings). Although each member in the path can be a list or property, the final member must resolve to a property. Each member builds on the previous member: "Size.Height" resolves to the System.Drawing.Size.Height property for the current System.Drawing.Size; "Regions.regionsToCustomers.CustomerFirstName" resolves to the first name for the current customer, where the customer is one of the customers for the current region.

A System.Data.DataRelation returns a list of values by linking one System.Data.DataTable to a second System.Data.DataTable in a System.Data.DataSet. If the System.Data.DataSet contains System.Data.DataRelation objects, you can specify the data member as a System.Data.DataTable.TableName followed by a System.Data.DataRelation.RelationName, and then a System.Data.DataColumn.ColumnName. For example, if the System.Data.DataTable named "Suppliers" contains a System.Data.DataRelation named "suppliers2products", the data member could be "Suppliers.suppliers2products.ProductName".

The data source can consist of a set of related classes. For example, imagine a set of classes that catalogs solar systems. The class named System contains a property named Stars that returns a collection of Star objects. Each Star object has Name and Mass properties, as well as a Planets property that returns a collection of Planet objects. In this system, each planet also has Mass and Name properties. Each Planet object further has a Moons property that returns a collection of Moon objects, each of which also has Name and Mass properties. If you specify a System object as the data source, you can specify any of the following as the data member:

Controls that can be simple-bound feature a collection of System.Windows.Forms.Binding objects in a System.Windows.Forms.ControlBindingsCollection, which you can access through the control's Control.DataBindings property. You add a System.Windows.Forms.Binding to the collection by calling the ControlBindingsCollection.Add(Binding) method, thereby binding a property of the control to a property of an object (or to a property of the current object in a list).

You can simple-bind to any object that derives from the System.Windows.Forms.Control class, for example, the following Windows controls:


Only the ListControl.SelectedValue property of the System.Windows.Forms.ComboBox, System.Windows.Forms.CheckedListBox, and System.Windows.Forms.ListBox control is simple bound.

The System.Windows.Forms.BindingManagerBase class is an abstract class that manages all the System.Windows.Forms.Binding objects for a particular data source and data member. Classes that derive from System.Windows.Forms.BindingManagerBase are the System.Windows.Forms.CurrencyManager and the System.Windows.Forms.PropertyManager classes. How a System.Windows.Forms.Binding is managed depends on whether the System.Windows.Forms.Binding is a list binding or a property binding. For example, if it is a list binding, you can use the System.Windows.Forms.BindingManagerBase to specify a BindingManagerBase.Position in the list; the BindingManagerBase.Position, therefore, determines which item (out of all items in the list) is actually bound to a control. To return the appropriate System.Windows.Forms.BindingManagerBase, use the System.Windows.Forms.BindingContext.

To add a new row to a set of controls bound to the same Binding.DataSource, use the BindingManagerBase.AddNew method of the System.Windows.Forms.BindingManagerBase class. Use the BindingContext.Item(object) property of the System.Windows.Forms.BindingContext class to return the appropriate System.Windows.Forms.CurrencyManager. To escape the addition of the new row, use the CurrencyManager.CancelCurrentEdit method.


Namespace: System.Windows.Forms
Assembly: System.Windows.Forms (in System.Windows.Forms.dll)
Assembly Versions: 1.0.5000.0,