Binding Class

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

System::Object
  System.Windows.Forms::Binding

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

[TypeConverterAttribute(typeof(ListBindingConverter))]
public ref class Binding

The Binding type exposes the following members.

  NameDescription
Public methodBinding(String, Object, String)Initializes a new instance of the Binding class that simple-binds the indicated control property to the specified data member of the data source.
Public methodBinding(String, Object, String, Boolean)Initializes a new instance of the Binding class that binds the indicated control property to the specified data member of the data source, and optionally enables formatting to be applied.
Public methodBinding(String, Object, String, Boolean, DataSourceUpdateMode)Initializes a new instance of the Binding class that binds the specified control property to the specified data member of the specified data source. Optionally enables formatting and propagates values to the data source based on the specified update setting.
Public methodBinding(String, Object, String, Boolean, DataSourceUpdateMode, Object)Initializes a new instance of the Binding class that binds the indicated control property to the specified data member of the specified data source. Optionally enables formatting, propagates values to the data source based on the specified update setting, and sets the property to the specified value when a DBNull is returned from the data source.
Public methodBinding(String, Object, String, Boolean, DataSourceUpdateMode, Object, String)Initializes a new instance of the Binding class that binds the specified control property to the specified data member of the specified data source. Optionally enables formatting with the specified format string; propagates values to the data source based on the specified update setting; and sets the property to the specified value when a DBNull is returned from the data source.
Public methodBinding(String, Object, String, Boolean, DataSourceUpdateMode, Object, String, IFormatProvider)Initializes a new instance of the Binding class with the specified control property to the specified data member of the specified data source. Optionally enables formatting with the specified format string; propagates values to the data source based on the specified update setting; enables formatting with the specified format string; sets the property to the specified value when a DBNull is returned from the data source; and sets the specified format provider.
Top

  NameDescription
Public propertyBindableComponentGets the control the Binding is associated with.
Public propertyBindingManagerBaseGets the BindingManagerBase for this Binding.
Public propertyBindingMemberInfoGets an object that contains information about this binding based on the dataMember parameter in the Binding constructor.
Public propertyControlGets the control that the binding belongs to.
Public propertyControlUpdateModeGets or sets when changes to the data source are propagated to the bound control property.
Public propertyDataSourceGets the data source for this binding.
Public propertyDataSourceNullValueGets or sets the value to be stored in the data source if the control value is nullptr or empty.
Public propertyDataSourceUpdateModeGets or sets a value that indicates when changes to the bound control property are propagated to the data source.
Public propertyFormatInfoGets or sets the IFormatProvider that provides custom formatting behavior.
Public propertyFormatStringGets or sets the format specifier characters that indicate how a value is to be displayed.
Public propertyFormattingEnabledGets or sets a value indicating whether type conversion and formatting is applied to the control property data.
Public propertyIsBindingGets a value indicating whether the binding is active.
Public propertyNullValueGets or sets the Object to be set as the control property when the data source contains a DBNull value.
Public propertyPropertyNameGets or sets the name of the control's data-bound property.
Top

  NameDescription
Public methodEquals(Object)Determines whether the specified object is equal to the current object. (Inherited from Object.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodGetHashCodeServes as the default hash function. (Inherited from Object.)
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Protected methodOnBindingCompleteRaises the BindingComplete event.
Protected methodOnFormatRaises the Format event.
Protected methodOnParseRaises the Parse event.
Public methodReadValueSets the control property to the value read from the data source.
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Public methodWriteValueReads the current value from the control property and writes it to the data source.
Top

  NameDescription
Public eventBindingCompleteOccurs when the FormattingEnabled property is set to true and a binding operation is complete, such as when data is pushed from the control to the data source or vice versa
Public eventFormatOccurs when the property of a control is bound to a data value.
Public eventParseOccurs when the value of a data-bound control changes.
Top

Use the 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 Text property of a TextBox control to the FirstName property of a Customer object. As an example of the second case, you can bind the Text property of a TextBox control to the FirstName property of a DataTable that contains customers.

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

When constructing a Binding instance with Binding constructor, you must specify three items:

  • The name of the control property to bind to.

  • The data source.

  • The navigation path that resolves to a list or property in the data source. The navigation path is also used to create the object's BindingMemberInfo property.

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

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

Description

C# example

Any class that implements IBindingList or ITypedList. These include the following: DataSet, DataTable, DataView, or 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 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");

ar1.Add(cust1);

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 ToString method will be called on the underlying data source object.

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

NoteNote

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

A period-delimited navigation path is required when the data source is set to an object that contains multiple DataTable objects (such as a DataSet or 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:

  • "Size.Height"

  • "Suppliers.CompanyName"

  • "Regions.regionsToCustomers.CustomerFirstName"

  • "Regions.regionsToCustomers.customersToOrders.ordersToDetails.Quantity"

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 Height property for the current 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 DataRelation returns a list of values by linking one DataTable to a second DataTable in a DataSet. If the DataSet contains DataRelation objects, you can specify the data member as a TableName followed by a RelationName, and then a ColumnName. For example, if the DataTable named "Suppliers" contains a 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:

  • "Stars.Name"

  • "Stars.Mass"

  • "Stars.Planets.Name"

  • "Stars.Planets.Mass"

  • "Stars.Planets.Moons.Name"

  • "Stars.Planets.Moons.Mass"

Controls that can be simple-bound feature a collection of Binding objects in a ControlBindingsCollection, which you can access through the control's DataBindings property. You add a Binding to the collection by calling the Add 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:

NoteNote

Only the SelectedValue property of the ComboBox, CheckedListBox, and ListBox control is simple bound.

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

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

The following code example creates a Windows Form with several controls that demonstrate simple data binding. The example creates a DataSet with two tables named Customers and Orders, and a DataRelation named custToOrders. Four controls (a DateTimePicker and three TextBox controls) are data bound to columns in the tables. For each control, the example creates and adds a Binding to the control through the DataBindings property. The example returns a BindingManagerBase for each table through the form's BindingContext. Four Button controls increment or decrement the Position property on the BindingManagerBase objects.

#using <system.dll>
#using <system.data.dll>
#using <system.drawing.dll>
#using <system.windows.forms.dll>
#using <system.xml.dll>

using namespace System;
using namespace System::Data;
using namespace System::Drawing;
using namespace System::Globalization;
using namespace System::Windows::Forms;

#define null 0L
public ref class Form1: public Form
{
private:
   System::ComponentModel::Container^ components;
   Button^ button1;
   Button^ button2;
   Button^ button3;
   Button^ button4;
   TextBox^ text1;
   TextBox^ text2;
   TextBox^ text3;
   BindingManagerBase^ bmCustomers;
   BindingManagerBase^ bmOrders;
   DataSet^ ds;
   DateTimePicker^ DateTimePicker1;

public:
   Form1()
   {
      // Required for Windows Form Designer support.
      InitializeComponent();

      // Call SetUp to bind the controls.
      SetUp();
   }

private:
   void InitializeComponent()
   {
      // Create the form and its controls. 
      this->components = gcnew System::ComponentModel::Container;
      this->button1 = gcnew Button;
      this->button2 = gcnew Button;
      this->button3 = gcnew Button;
      this->button4 = gcnew Button;
      this->text1 = gcnew TextBox;
      this->text2 = gcnew TextBox;
      this->text3 = gcnew TextBox;
      this->DateTimePicker1 = gcnew DateTimePicker;
      this->Text =  "Binding Sample";
      this->ClientSize = System::Drawing::Size( 450, 200 );
      button1->Location = System::Drawing::Point( 24, 16 );
      button1->Size = System::Drawing::Size( 64, 24 );
      button1->Text =  "<";
      button1->Click += gcnew System::EventHandler( this, &Form1::button1_Click );
      button2->Location = System::Drawing::Point( 90, 16 );
      button2->Size = System::Drawing::Size( 64, 24 );
      button2->Text =  ">";
      button2->Click += gcnew System::EventHandler( this, &Form1::button2_Click );
      button3->Location = System::Drawing::Point( 90, 100 );
      button3->Size = System::Drawing::Size( 64, 24 );
      button3->Text =  "<";
      button3->Click += gcnew System::EventHandler( this, &Form1::button3_Click );
      button4->Location = System::Drawing::Point( 150, 100 );
      button4->Size = System::Drawing::Size( 64, 24 );
      button4->Text =  ">";
      button4->Click += gcnew System::EventHandler( this, &Form1::button4_Click );
      text1->Location = System::Drawing::Point( 24, 50 );
      text1->Size = System::Drawing::Size( 150, 24 );
      text2->Location = System::Drawing::Point( 190, 50 );
      text2->Size = System::Drawing::Size( 150, 24 );
      text3->Location = System::Drawing::Point( 290, 150 );
      text3->Size = System::Drawing::Size( 150, 24 );
      DateTimePicker1->Location = System::Drawing::Point( 90, 150 );
      DateTimePicker1->Size = System::Drawing::Size( 200, 800 );
      this->Controls->Add( button1 );
      this->Controls->Add( button2 );
      this->Controls->Add( button3 );
      this->Controls->Add( button4 );
      this->Controls->Add( text1 );
      this->Controls->Add( text2 );
      this->Controls->Add( text3 );
      this->Controls->Add( DateTimePicker1 );
   }

public:
   ~Form1()
   {
      if ( components != nullptr )
      {
         delete components;
      }
   }

private:
   void SetUp()
   {
      // Create a DataSet with two tables and one relation.
      MakeDataSet();
      BindControls();
   }

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 the 
              "TableName.ColumnName" string. */
      text1->DataBindings->Add( gcnew Binding( "Text",ds,"customers.custName" ) );
      text2->DataBindings->Add( gcnew 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( gcnew 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 = gcnew Binding( "Text",ds,"customers.custToOrders.OrderAmount" );
      b->Parse += gcnew ConvertEventHandler( this, &Form1::CurrencyStringToDecimal );
      b->Format += gcnew ConvertEventHandler( this, &Form1::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" ];
   }

private:
   void DecimalToCurrencyString( Object^ /*sender*/, ConvertEventArgs^ cevent )
   {
      /* This method is the Format event handler. Whenever the 
              control displays a new value, the value is converted from 
              its native Decimal type to a string. The ToString method 
              then formats the value as a Currency, by using the 
              formatting character "c". */ 
      // The application can only convert to string type.  
      if ( cevent->DesiredType != String::typeid )
            return;

      cevent->Value = (dynamic_cast<Decimal^>(cevent->Value))->ToString( "c" );
   }

   void CurrencyStringToDecimal( Object^ /*sender*/, ConvertEventArgs^ cevent )
   {
      /* This method is the Parse event handler. The Parse event 
              occurs whenever the displayed value changes. The static 
              ToDecimal method of the Convert class converts the 
              value back to its native Decimal type. */ 
      // Can only convert to Decimal type. 
      if ( cevent->DesiredType != Decimal::typeid )
            return;

      cevent->Value = Decimal::Parse( cevent->Value->ToString(), NumberStyles::Currency, nullptr );

      /* To see that no precision is lost, print the unformatted 
              value. For example, changing a value to "10.0001" 
              causes the control to display "10.00", but the 
              unformatted value remains "10.0001". */
      Console::WriteLine( cevent->Value );
   }

private:
   void button1_Click( Object^ /*sender*/, System::EventArgs^ /*e*/ )
   {
      // Go to the previous item in the Customer list.
      bmCustomers->Position -= 1;
   }

   void button2_Click( Object^ /*sender*/, System::EventArgs^ /*e*/ )
   {
      // Go to the next item in the Customer list.
      bmCustomers->Position += 1;
   }

   void button3_Click( Object^ /*sender*/, System::EventArgs^ /*e*/ )
   {

      // Go to the previous item in the Orders list.
      bmOrders->Position = bmOrders->Position - 1;
   }

   void button4_Click( Object^ /*sender*/, System::EventArgs^ /*e*/ )
   {

      // Go to the next item in the Orders list.
      bmOrders->Position = bmOrders->Position + 1;
   }

private:

   // Create a DataSet with two tables and populate it. 
   void MakeDataSet()
   {
      // Create a DataSet.
      ds = gcnew DataSet( "myDataSet" );

      // Create two DataTables.
      DataTable^ tCust = gcnew DataTable( "Customers" );
      DataTable^ tOrders = gcnew DataTable( "Orders" );

      // Create two columns, and add them to the first table.
      DataColumn^ cCustID = gcnew DataColumn( "CustID",Int32::typeid );
      DataColumn^ cCustName = gcnew DataColumn( "CustName" );
      tCust->Columns->Add( cCustID );
      tCust->Columns->Add( cCustName );

      // Create three columns, and add them to the second table.
      DataColumn^ cID = gcnew DataColumn( "CustID",Int32::typeid );
      DataColumn^ cOrderDate = gcnew DataColumn( "orderDate",DateTime::typeid );
      DataColumn^ cOrderAmount = gcnew DataColumn( "OrderAmount",Decimal::typeid );
      tOrders->Columns->Add( cOrderAmount );
      tOrders->Columns->Add( cID );
      tOrders->Columns->Add( cOrderDate );

      // Add the tables to the DataSet.
      ds->Tables->Add( tCust );
      ds->Tables->Add( tOrders );

      // Create a DataRelation, and add it to the DataSet.
      DataRelation^ dr = gcnew DataRelation( "custToOrders",cCustID,cID );
      ds->Relations->Add( dr );

      /* Populate the tables. For each customer and order, 
              create two DataRow variables. */
      DataRow^ newRow1; // = new DataRow();

      DataRow^ newRow2; // = new DataRow(); 

      // Create three customers in the Customers Table. 
      for ( int i = 1; i < 4; i++ )
      {
         newRow1 = tCust->NewRow();
         newRow1[ "custID" ] = i;

         // Add the row to the Customers table.
         tCust->Rows->Add( newRow1 );

      }
      tCust->Rows[ 0 ][ "custName" ] = "Alpha";
      tCust->Rows[ 1 ][ "custName" ] = "Beta";
      tCust->Rows[ 2 ][ "custName" ] = "Omega";

      // For each customer, create five rows in the Orders table. 
      for ( int i = 1; i < 4; i++ )
      {
         for ( int j = 1; j < 6; j++ )
         {
            newRow2 = tOrders->NewRow();
            newRow2[ "CustID" ] = i;
            newRow2[ "orderDate" ] = System::DateTime( 2001, i, j * 2 );
            newRow2[ "OrderAmount" ] = i * 10 + j * .1;

            // Add the row to the Orders table.
            tOrders->Rows->Add( newRow2 );
         }
      }
   }
};

int main()
{
   Application::Run( gcnew Form1 );
}

.NET Framework

Supported in: 4.6, 4.5, 4, 3.5, 3.0, 2.0, 1.1, 1.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

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.
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft