Export (0) Print
Expand All

BindingContext Class

Manages the collection of BindingManagerBase objects for any object that inherits from the Control class.

For a list of all members of this type, see BindingContext Members.

System.Object
   System.Windows.Forms.BindingContext

[Visual Basic]
Public Class BindingContext
   Implements ICollection, IEnumerable
[C#]
public class BindingContext : ICollection, IEnumerable
[C++]
public __gc class BindingContext : public ICollection, IEnumerable
[JScript]
public class BindingContext implements ICollection, IEnumerable

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Remarks

Each object that inherits from the Control class can have a single BindingContext object. That BindingContext manages the BindingManagerBase objects for that control and any contained controls. Use the BindingContext to create or return the BindingManagerBase for a data source used by the contained data-bound controls. Most commonly, you use the Form class's BindingContext to return BindingManagerBase objects for the data-bound controls on the form. If you use a container control, such as a GroupBox, Panel, or TabControl, to contain data-bound controls, you can create a BindingContext for just that container control and its controls. This allows each part of your form to be managed by its own BindingManagerBase object. See the BindingContext constructor for more details on creating multiple BindingManagerBase objects for the same data source.

To return a particular BindingManagerBase object, you must pass one of the following parameters to the Item property:

  • Just the data source, if the desired BindingManagerBase does not require a navigation path. For example, if the BindingManagerBase manages a set of Binding objects that use an ArrayList or DataTable as the DataSource, no navigation path is required. (See below for more information about creating a navigation path.)
  • The data source and navigation path. A navigation path (set to the Item property's dataMember parameter) is required when the BindingManagerBase manages a set of Binding objects for which the data source contains multiple objects. For example, a DataSet can contain several DataTable objects linked by DataRelation objects. In such a case, the navigation path is required to enable the BindingContext to return the correct BindingManagerBase.

See the Binding class for a list of possible data sources.

Because the BindingManagerBase class is abstract, the Type of the returned object is either a CurrencyManager or a PropertyManager. If the data source is an object that can return only a single property (instead of a list of objects), the Type will be a PropertyManager. For example, if you specify a TextBox as the data source, a PropertyManager will be returned. On the other hand, if the data source is an object that implements IList or IBindingList, a CurrencyManager will be returned.

If the desired BindingManagerBase manages a list, the navigation path must also end with a list. For example, the C# code below binds a TextBox control to the order date in a table of orders by adding new Binding object to the ControlBindingsCollection. The navigation path includes the TableName, the RelationName, and the ColumnName. The second line uses the BindingContext to return a BindingManagerBase-- retrieved by passing the TableName and RelationName (which resolves to a list) to the Item property.

/* Create a new Binding object and add to the ControlBindingsColllection.
The navigation path (Customers.custOrders.OrderDate) used to 
create a Binding ends with a property. */
textBox1.DataBindings.Add
("Text", dataSet1, "Customers.custToOrders.OrderDate");
/* The navigation path (Customers.custToOrders) used to 
return the BindingManagerBase ends with a list. */
BindingManagerBase bmOrders = 
this.BindingContext[dataSet1, "Customers.custToOrders"];

When returning a BindingManagerBase, you should use the same data source as the Binding and modify only the navigation path. The following C# code seems to return the same BindingManagerBase, but the results are different:

BindingManagerBase bmCustomers = this.BindingContext
[myDataSet, "Customers"];
// This returns a different BindingManagerBase:
BindingManagerBase bmOther = this.BindingContext
[myDataSet.Tables[Customers], ""];
// This line returns true.
Console.WriteLine(bmCustomers != bmOther);

For each object passed to the BindingContext, a different BindingManagerBase object is returned. In the example above, the objects passed to the Item property are different, and therefore the BindingManagerBase returned for each object is different.

Note   When using the Item property, the BindingContext will create a new BindingManagerBase if one does not already exist. This can lead to some confusion, as the returned object may not manage the list (or any list) that you intend. To prevent returning an invalid BindingManagerBase, use the Contains method to determine if the desired BindingManagerBase already exists.

Example

[Visual Basic, C#, C++] The following example creates four Binding objects to bind five controls--a DateTimePicker and four TextBox controls--to several data sources. The BindingContext is then used to get the BindingManagerBase for each data source.

[Visual Basic] 
Protected Sub BindControls()

   ' Create two Binding objects for the first two TextBox 
   '   controls. The data-bound property for both controls 
   '   is the Text property. The data source is a DataSet 
   '   (ds). The data member is the string 
   '   "TableName.ColumnName".
   text1.DataBindings.Add(New Binding _
      ("Text", ds, "customers.custName"))
   text2.DataBindings.Add(New Binding _
      ("Text", ds, "customers.custID"))
   
   ' Bind the DateTimePicker control by adding a new Binding. 
   '   The data member of the DateTimePicker is a 
   '   TableName.RelationName.ColumnName string.
   DateTimePicker1.DataBindings.Add(New Binding _
      ("Value", ds, "customers.CustToOrders.OrderDate"))

   ' Add event delegates for the Parse and Format events to a 
   '   new Binding object, and add the object to the third 
   '   TextBox control's BindingsCollection. The delegates 
   '   must be added before adding the Binding to the 
   '   collection; otherwise, no formatting occurs until 
   '   the Current object of the BindingManagerBase for 
   '   the data source changes.
   Dim b As Binding = New Binding _
      ("Text", ds, "customers.custToOrders.OrderAmount")
   AddHandler b.Parse,  New ConvertEventHandler(AddressOf CurrencyStringToDecimal)      
   AddHandler b.Format, New ConvertEventHandler(AddressOf DecimalToCurrencyString)
   text3.DataBindings.Add(b)

   ' Get the BindingManagerBase for the Customers table.
   bmCustomers = Me.BindingContext(ds, "Customers")

   ' Get the BindingManagerBase for the Orders table using the 
   '   RelationName.
   bmOrders = Me.BindingContext(ds, "customers.CustToOrders")

   ' Bind the fourth TextBox control's Text property to the
   ' third control's Text property.
   text4.DataBindings.Add("Text", text3, "Text")

End Sub


[C#] 
protected void BindControls()
{
   /* Create two Binding objects for the first two TextBox 
      controls. The data-bound property for both controls 
      is the Text property. The data source is a DataSet 
      (ds). The data member is a navigation path in the form: 
      "TableName.ColumnName". */
   text1.DataBindings.Add(new Binding
   ("Text", ds, "customers.custName"));
   text2.DataBindings.Add(new Binding
   ("Text", ds, "customers.custID"));
   
   /* Bind the DateTimePicker control by adding a new Binding. 
      The data member of the DateTimePicker is a navigation path:
      TableName.RelationName.ColumnName string. */
   DateTimePicker1.DataBindings.Add(new 
   Binding("Value", ds, "customers.CustToOrders.OrderDate"));

   /* Add event delegates for the Parse and Format events to a 
      new Binding object, and add the object to the third 
      TextBox control's BindingsCollection. The delegates 
      must be added before adding the Binding to the 
      collection; otherwise, no formatting occurs until 
      the Current object of the BindingManagerBase for 
      the data source changes. */
      Binding b = new Binding
      ("Text", ds, "customers.custToOrders.OrderAmount");
   b.Parse+=new ConvertEventHandler(CurrencyStringToDecimal);
   b.Format+=new ConvertEventHandler(DecimalToCurrencyString);
   text3.DataBindings.Add(b);

   // Get the BindingManagerBase for the Customers table. 
   bmCustomers = this.BindingContext [ds, "Customers"];

   /* Get the BindingManagerBase for the Orders table using the 
      RelationName. */ 
   bmOrders = this.BindingContext[ds, "customers.CustToOrders"];

   /* Bind the fourth TextBox control's Text property to the
   third control's Text property. */
   text4.DataBindings.Add("Text", text3, "Text");
}


[C++] 
void BindControls() {
/* Create two Binding objects for the first two TextBox 
  controls. The data-bound property for both controls 
  is the Text property. The data source is a DataSet 
  (ds). The data member is a navigation path in the form: 
  "TableName.ColumnName". */
    text1->DataBindings->Add(new Binding(S"Text", ds, S"customers.custName"));
    text2->DataBindings->Add(new Binding(S"Text", ds, S"customers.custID"));
   
   /* Bind the DateTimePicker control by adding a new Binding. 
  The data member of the DateTimePicker is a navigation path:
  TableName.RelationName.ColumnName string. */
    DateTimePicker1->DataBindings->Add(new Binding(S"Value", ds, S"customers.CustToOrders.OrderDate"));

   /* Add event delegates for the Parse and Format events to a 
  new Binding object, and add the object to the third 
  TextBox control's BindingsCollection. The delegates 
  must be added before adding the Binding to the 
  collection; otherwise, no formatting occurs until 
  the Current object of the BindingManagerBase for 
  the data source changes. */
    Binding __gc *b = new Binding (S"Text", ds, S"customers.custToOrders.OrderAmount");
    b->Parse += new ConvertEventHandler(this, &Form1::CurrencyStringToDecimal);
    b->Format += new ConvertEventHandler(this, &Form1::DecimalToCurrencyString);
    text3->DataBindings->Add(b);

   // Get the BindingManagerBase for the Customers table. 
    bmCustomers = this->BindingContext->Item[ds, S"Customers"];

   /* Get the BindingManagerBase for the Orders table using the 
  RelationName. */ 
    bmOrders = this->BindingContext->get_Item(ds, S"customers.CustToOrders");

   /* Bind the fourth TextBox control's Text property to the
   third control's Text property. */
    text4->DataBindings->Add(S"Text", text3, S"Text");
};

[JScript] No example is available for JScript. To view a Visual Basic, C#, or C++ example, click the Language Filter button Language Filter in the upper-left corner of the page.

Requirements

Namespace: System.Windows.Forms

Platforms: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 family, .NET Compact Framework

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

See Also

BindingContext Members | System.Windows.Forms Namespace | BindingManagerBase | Binding | BindingsCollection

Show:
© 2014 Microsoft