ControlBindingsCollection.Add Method

Reference

Definition

Namespace:: System.Windows.Forms

Assembly:: System.Windows.Forms.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Adds a Binding to the collection.

Overloads

Add(Binding)	Adds the specified Binding to the collection.
Add(String, Object, String)	Creates a Binding using the specified control property name, data source, and data member, and adds it to the collection.
Add(String, Object, String, Boolean)	Creates a binding with the specified control property name, data source, data member, and information about whether formatting is enabled, and adds the binding to the collection.
Add(String, Object, String, Boolean, DataSourceUpdateMode)	Creates a binding that binds the specified control property to the specified data member of the specified data source, optionally enabling formatting, propagating values to the data source based on the specified update setting, and adding the binding to the collection.
Add(String, Object, String, Boolean, DataSourceUpdateMode, Object)	Creates a binding that binds the specified control property to the specified data member of the specified data source, optionally enabling formatting, propagating values to the data source based on the specified update setting, setting the property to the specified value when DBNull is returned from the data source, and adding the binding to the collection.
Add(String, Object, String, Boolean, DataSourceUpdateMode, Object, String)	Creates a binding that binds the specified control property to the specified data member of the specified data source, optionally enabling formatting with the specified format string, propagating values to the data source based on the specified update setting, setting the property to the specified value when DBNull is returned from the data source, and adding the binding to the collection.
Add(String, Object, String, Boolean, DataSourceUpdateMode, Object, String, IFormatProvider)	Creates a binding that binds the specified control property to the specified data member of the specified data source, optionally enabling formatting with the specified format string, propagating values to the data source based on the specified update setting, setting the property to the specified value when DBNull is returned from the data source, setting the specified format provider, and adding the binding to the collection.

Add(Binding)

Source:: ControlBindingsCollection.cs

Source:: ControlBindingsCollection.cs

Source:: ControlBindingsCollection.cs

Adds the specified Binding to the collection.

public:
 void Add(System::Windows::Forms::Binding ^ binding);

public void Add (System.Windows.Forms.Binding binding);

override this.Add : System.Windows.Forms.Binding -> unit

Public Sub Add (binding As Binding)

Parameters

binding: Binding

The Binding to add.

Exceptions

ArgumentNullException

The binding is null.

ArgumentException

The control property is already data-bound.

-or-

The Binding does not specify a valid column of the DataSource.

Examples

The following code example creates a Binding instance, and uses the Add method to add the instance to the ControlBindingsCollection of a TextBox control.

protected:
   void BindControls()
   {
      /* Create a new Binding using the DataSet and a 
         navigation path(TableName.RelationName.ColumnName).
         Add event delegates for the Parse and Format events to 
         the 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 );
      textBox1->DataBindings->Add( b );
   }

protected void BindControls()
{
   /* Create a new Binding using the DataSet and a 
   navigation path(TableName.RelationName.ColumnName).
   Add event delegates for the Parse and Format events to 
   the 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);
   textBox1.DataBindings.Add(b);
}

Protected Sub BindControls()
    ' Create a new Binding using the DataSet and a 
    ' navigation path(TableName.RelationName.ColumnName).
    ' Add event delegates for the Parse and Format events to 
    ' the 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 New Binding("Text", ds, "customers.custToOrders.OrderAmount")
    AddHandler b.Parse, AddressOf CurrencyStringToDecimal
    AddHandler b.Format, AddressOf DecimalToCurrencyString
    textBox1.DataBindings.Add(b)
End Sub

Remarks

The DataSourceUpdateMode property of the Binding created by this overload of the Add method is set to the value of the DefaultDataSourceUpdateMode property.

The CollectionChanged event occurs when the change is complete.

Applies to

Add(String, Object, String)

Source:: ControlBindingsCollection.cs

Source:: ControlBindingsCollection.cs

Source:: ControlBindingsCollection.cs

Creates a Binding using the specified control property name, data source, and data member, and adds it to the collection.

public:
 System::Windows::Forms::Binding ^ Add(System::String ^ propertyName, System::Object ^ dataSource, System::String ^ dataMember);

public System.Windows.Forms.Binding Add (string propertyName, object dataSource, string dataMember);

public System.Windows.Forms.Binding Add (string propertyName, object dataSource, string? dataMember);

override this.Add : string * obj * string -> System.Windows.Forms.Binding

Public Function Add (propertyName As String, dataSource As Object, dataMember As String) As Binding

Parameters

propertyName: String

The name of the control property to bind.

dataSource: Object

An Object that represents the data source.

dataMember: String

The property or list to bind to.

Returns

Binding

The newly created Binding.

Exceptions

ArgumentNullException

The binding is null.

Exception

The propertyName is already data-bound.

-or-

The dataMember doesn't specify a valid member of the dataSource.

Examples

The following code example uses the Add method to add three Binding objects to the ControlBindingsCollection of a TextBox control. The ControlBindingsCollection is accessed through the DataBindings property of the Control class.

private:
   void BindTextBoxProperties()
   {
      // Clear the collection before adding new Binding objects.
      textBox1->DataBindings->Clear();

      // Create a DataTable containing Color objects.
      DataTable^ t = MakeTable();

      /* Bind the Text, BackColor, and ForeColor properties
         to columns in the DataTable. */
      textBox1->DataBindings->Add( "Text", t, "Text" );
      textBox1->DataBindings->Add( "BackColor", t, "BackColor" );
      textBox1->DataBindings->Add( "ForeColor", t, "ForeColor" );
   }

   DataTable^ MakeTable()
   {
      /* Create a DataTable with three columns.
         Two of the columns contain Color objects. */
      DataTable^ t = gcnew DataTable( "Control" );
      t->Columns->Add( "BackColor", Color::typeid );
      t->Columns->Add( "ForeColor", Color::typeid );
      t->Columns->Add( "Text" );

      // Add three rows to the table.
      DataRow^ r;
      r = t->NewRow();
      r[ "BackColor" ] = Color::Blue;
      r[ "ForeColor" ] = Color::Yellow;
      r[ "Text" ] = "Yellow on Blue";
      t->Rows->Add( r );
      r = t->NewRow();
      r[ "BackColor" ] = Color::White;
      r[ "ForeColor" ] = Color::Green;
      r[ "Text" ] = "Green on white";
      t->Rows->Add( r );
      r = t->NewRow();
      r[ "BackColor" ] = Color::Orange;
      r[ "ForeColor" ] = Color::Black;
      r[ "Text" ] = "Black on Orange";
      t->Rows->Add( r );
      return t;
   }

private void BindTextBoxProperties()
{
   // Clear the collection before adding new Binding objects.
   textBox1.DataBindings.Clear();

   // Create a DataTable containing Color objects.
   DataTable t = MakeTable();

   /* Bind the Text, BackColor, and ForeColor properties
   to columns in the DataTable. */
   textBox1.DataBindings.Add("Text", t, "Text");
   textBox1.DataBindings.Add("BackColor", t, "BackColor");
   textBox1.DataBindings.Add("ForeColor", t, "ForeColor");
}

private DataTable MakeTable()
{
   /* Create a DataTable with three columns.
   Two of the columns contain Color objects. */

   DataTable t = new DataTable("Control");
   t.Columns.Add("BackColor", typeof(Color));
   t.Columns.Add("ForeColor", typeof(Color));
   t.Columns.Add("Text");

   // Add three rows to the table.
   DataRow r;

   r = t.NewRow();
   r["BackColor"] = Color.Blue;
   r["ForeColor"] = Color.Yellow;
   r["Text"] = "Yellow on Blue";
   t.Rows.Add(r);

   r = t.NewRow();
   r["BackColor"] = Color.White;
   r["ForeColor"] = Color.Green;
   r["Text"] = "Green on white";
   t.Rows.Add(r);

   r = t.NewRow();
   r["BackColor"] = Color.Orange;
   r["ForeColor"] = Color.Black;
   r["Text"] = "Black on Orange";
   t.Rows.Add(r);

   return t;
}

Private Sub BindTextBoxProperties()
    ' Clear the collection before adding new Binding objects.
    textBox1.DataBindings.Clear()
    
    ' Create a DataTable containing Color objects.
    Dim t As DataTable = MakeTable()
    
    ' Bind the Text, BackColor, and ForeColor properties
    ' to columns in the DataTable. 
    textBox1.DataBindings.Add("Text", t, "Text")
    textBox1.DataBindings.Add("BackColor", t, "BackColor")
    textBox1.DataBindings.Add("ForeColor", t, "ForeColor")
End Sub    

Private Function MakeTable() As DataTable
    ' Create a DataTable with three columns.
    ' Two of the columns contain Color objects. 
    
    Dim t As New DataTable("Control")
    t.Columns.Add("BackColor", GetType(Color))
    t.Columns.Add("ForeColor", GetType(Color))
    t.Columns.Add("Text")
    
    ' Add three rows to the table.
    Dim r As DataRow
    
    r = t.NewRow()
    r("BackColor") = Color.Blue
    r("ForeColor") = Color.Yellow
    r("Text") = "Yellow on Blue"
    t.Rows.Add(r)
    
    r = t.NewRow()
    r("BackColor") = Color.White
    r("ForeColor") = Color.Green
    r("Text") = "Green on white"
    t.Rows.Add(r)
    
    r = t.NewRow()
    r("BackColor") = Color.Orange
    r("ForeColor") = Color.Black
    r("Text") = "Black on Orange"
    t.Rows.Add(r)
    
    Return t
End Function

Remarks

The DataSourceUpdateMode property of the Binding created by this overload of the Add method is set to the value of the DefaultDataSourceUpdateMode property.

Adding a Binding causes the CollectionChanged event to occur.

Applies to

Add(String, Object, String, Boolean)

Source:: ControlBindingsCollection.cs

Source:: ControlBindingsCollection.cs

Source:: ControlBindingsCollection.cs

Creates a binding with the specified control property name, data source, data member, and information about whether formatting is enabled, and adds the binding to the collection.

public:
 System::Windows::Forms::Binding ^ Add(System::String ^ propertyName, System::Object ^ dataSource, System::String ^ dataMember, bool formattingEnabled);

public System.Windows.Forms.Binding Add (string propertyName, object dataSource, string dataMember, bool formattingEnabled);

public System.Windows.Forms.Binding Add (string propertyName, object dataSource, string? dataMember, bool formattingEnabled);

override this.Add : string * obj * string * bool -> System.Windows.Forms.Binding

Public Function Add (propertyName As String, dataSource As Object, dataMember As String, formattingEnabled As Boolean) As Binding

Parameters

propertyName: String

The name of the control property to bind.

dataSource: Object

An Object representing the data source.

dataMember: String

The property or list to bind to.

formattingEnabled: Boolean

true to format the displayed data; otherwise, false.

Returns

Binding

The newly created Binding.

Exceptions

ArgumentException

The property given by propertyName does not exist on the control.

-or-

The property given is a read-only property.

Exception

If formatting is disabled and the propertyName is neither a valid property of a control nor an empty string ("").

Applies to

Add(String, Object, String, Boolean, DataSourceUpdateMode)

Source:: ControlBindingsCollection.cs

Source:: ControlBindingsCollection.cs

Source:: ControlBindingsCollection.cs

Creates a binding that binds the specified control property to the specified data member of the specified data source, optionally enabling formatting, propagating values to the data source based on the specified update setting, and adding the binding to the collection.

public:
 System::Windows::Forms::Binding ^ Add(System::String ^ propertyName, System::Object ^ dataSource, System::String ^ dataMember, bool formattingEnabled, System::Windows::Forms::DataSourceUpdateMode updateMode);

public System.Windows.Forms.Binding Add (string propertyName, object dataSource, string dataMember, bool formattingEnabled, System.Windows.Forms.DataSourceUpdateMode updateMode);

public System.Windows.Forms.Binding Add (string propertyName, object dataSource, string? dataMember, bool formattingEnabled, System.Windows.Forms.DataSourceUpdateMode updateMode);

override this.Add : string * obj * string * bool * System.Windows.Forms.DataSourceUpdateMode -> System.Windows.Forms.Binding

Public Function Add (propertyName As String, dataSource As Object, dataMember As String, formattingEnabled As Boolean, updateMode As DataSourceUpdateMode) As Binding

Parameters

propertyName: String

The name of the control property to bind.

dataSource: Object

An Object representing the data source.

dataMember: String

The property or list to bind to.

formattingEnabled: Boolean

true to format the displayed data; otherwise, false.

updateMode: DataSourceUpdateMode

One of the DataSourceUpdateMode values.

Returns

Binding

The newly created Binding.

Exceptions

ArgumentException

The property given by propertyName does not exist on the control or is read-only.

-or-

The specified data member does not exist on the data source.

-or-

The data source, data member, or control property specified are associated with another binding in the collection.

Remarks

Calling the Add method raises the CollectionChanged event.

Applies to

Add(String, Object, String, Boolean, DataSourceUpdateMode, Object)

Source:: ControlBindingsCollection.cs

Source:: ControlBindingsCollection.cs

Source:: ControlBindingsCollection.cs

public:
 System::Windows::Forms::Binding ^ Add(System::String ^ propertyName, System::Object ^ dataSource, System::String ^ dataMember, bool formattingEnabled, System::Windows::Forms::DataSourceUpdateMode updateMode, System::Object ^ nullValue);

public System.Windows.Forms.Binding Add (string propertyName, object dataSource, string dataMember, bool formattingEnabled, System.Windows.Forms.DataSourceUpdateMode updateMode, object nullValue);

public System.Windows.Forms.Binding Add (string propertyName, object dataSource, string? dataMember, bool formattingEnabled, System.Windows.Forms.DataSourceUpdateMode updateMode, object? nullValue);

override this.Add : string * obj * string * bool * System.Windows.Forms.DataSourceUpdateMode * obj -> System.Windows.Forms.Binding

Public Function Add (propertyName As String, dataSource As Object, dataMember As String, formattingEnabled As Boolean, updateMode As DataSourceUpdateMode, nullValue As Object) As Binding

Parameters

propertyName: String

The name of the control property to bind.

dataSource: Object

An Object representing the data source.

dataMember: String

The property or list to bind to.

formattingEnabled: Boolean

true to format the displayed data; otherwise, false.

updateMode: DataSourceUpdateMode

One of the DataSourceUpdateMode values.

nullValue: Object

When the data source has this value, the bound property is set to DBNull.

Returns

Binding

The newly created Binding.

Exceptions

ArgumentException

The property given by propertyName does not exist on the control or is read-only.

-or-

The specified data member does not exist on the data source.

-or-

The data source, data member, or control property specified are associated with another binding in the collection.

Remarks

Calling the Add method raises the CollectionChanged event.

Applies to

Add(String, Object, String, Boolean, DataSourceUpdateMode, Object, String)

Source:: ControlBindingsCollection.cs

Source:: ControlBindingsCollection.cs

Source:: ControlBindingsCollection.cs

Creates a binding that binds the specified control property to the specified data member of the specified data source, optionally enabling formatting with the specified format string, propagating values to the data source based on the specified update setting, setting the property to the specified value when DBNull is returned from the data source, and adding the binding to the collection.

public:
 System::Windows::Forms::Binding ^ Add(System::String ^ propertyName, System::Object ^ dataSource, System::String ^ dataMember, bool formattingEnabled, System::Windows::Forms::DataSourceUpdateMode updateMode, System::Object ^ nullValue, System::String ^ formatString);

public System.Windows.Forms.Binding Add (string propertyName, object dataSource, string dataMember, bool formattingEnabled, System.Windows.Forms.DataSourceUpdateMode updateMode, object nullValue, string formatString);

public System.Windows.Forms.Binding Add (string propertyName, object dataSource, string? dataMember, bool formattingEnabled, System.Windows.Forms.DataSourceUpdateMode updateMode, object? nullValue, string formatString);

override this.Add : string * obj * string * bool * System.Windows.Forms.DataSourceUpdateMode * obj * string -> System.Windows.Forms.Binding

Public Function Add (propertyName As String, dataSource As Object, dataMember As String, formattingEnabled As Boolean, updateMode As DataSourceUpdateMode, nullValue As Object, formatString As String) As Binding

Parameters

propertyName: String

The name of the control property to bind.

dataSource: Object

An Object representing the data source.

dataMember: String

The property or list to bind to.

formattingEnabled: Boolean

true to format the displayed data; otherwise, false.

updateMode: DataSourceUpdateMode

One of the DataSourceUpdateMode values.

nullValue: Object

When the data source has this value, the bound property is set to DBNull.

formatString: String

One or more format specifier characters that indicate how a value is to be displayed.

Returns

Binding

The newly created Binding.

Exceptions

ArgumentException

The property given by propertyName does not exist on the control or is read-only.

-or-

The specified data member does not exist on the data source.

-or-

The data source, data member, or control property specified are associated with another binding in the collection.

Remarks

Calling the Add method raises the CollectionChanged event.

Applies to

Add(String, Object, String, Boolean, DataSourceUpdateMode, Object, String, IFormatProvider)

Source:: ControlBindingsCollection.cs

Source:: ControlBindingsCollection.cs

Source:: ControlBindingsCollection.cs

public:
 System::Windows::Forms::Binding ^ Add(System::String ^ propertyName, System::Object ^ dataSource, System::String ^ dataMember, bool formattingEnabled, System::Windows::Forms::DataSourceUpdateMode updateMode, System::Object ^ nullValue, System::String ^ formatString, IFormatProvider ^ formatInfo);

public System.Windows.Forms.Binding Add (string propertyName, object dataSource, string dataMember, bool formattingEnabled, System.Windows.Forms.DataSourceUpdateMode updateMode, object nullValue, string formatString, IFormatProvider formatInfo);

public System.Windows.Forms.Binding Add (string propertyName, object dataSource, string? dataMember, bool formattingEnabled, System.Windows.Forms.DataSourceUpdateMode updateMode, object? nullValue, string formatString, IFormatProvider? formatInfo);

override this.Add : string * obj * string * bool * System.Windows.Forms.DataSourceUpdateMode * obj * string * IFormatProvider -> System.Windows.Forms.Binding

Public Function Add (propertyName As String, dataSource As Object, dataMember As String, formattingEnabled As Boolean, updateMode As DataSourceUpdateMode, nullValue As Object, formatString As String, formatInfo As IFormatProvider) As Binding

Parameters

propertyName: String

The name of the control property to bind.

dataSource: Object

An Object representing the data source.

dataMember: String

The property or list to bind to.

formattingEnabled: Boolean

true to format the displayed data; otherwise, false.

updateMode: DataSourceUpdateMode

One of the DataSourceUpdateMode values.

nullValue: Object

When the data source has this value, the bound property is set to DBNull.

formatString: String

One or more format specifier characters that indicate how a value is to be displayed.

formatInfo: IFormatProvider

An implementation of IFormatProvider to override default formatting behavior.

Returns

Binding

The newly created Binding.

Exceptions

ArgumentException

The property given by propertyName does not exist on the control or is read-only.

-or-

The specified data member does not exist on the data source.

-or-

The data source, data member, or control property specified are associated with another binding in the collection.

Remarks

Calling the Add method raises the CollectionChanged event.

Applies to

Share via

ControlBindingsCollection.Add Method

Definition

Overloads

Add(Binding)

Parameters

Exceptions

Examples

Remarks

Applies to

Add(String, Object, String)

Parameters

Returns

Exceptions

Examples

Remarks

Applies to

Add(String, Object, String, Boolean)

Parameters

Returns

Exceptions

Applies to

Add(String, Object, String, Boolean, DataSourceUpdateMode)

Parameters

Returns

Exceptions

Remarks

Applies to

Add(String, Object, String, Boolean, DataSourceUpdateMode, Object)

Parameters

Returns

Exceptions

Remarks

Applies to

Add(String, Object, String, Boolean, DataSourceUpdateMode, Object, String)

Parameters

Returns

Exceptions

Remarks

Applies to

Add(String, Object, String, Boolean, DataSourceUpdateMode, Object, String, IFormatProvider)

Parameters

Returns

Exceptions

Remarks

Applies to

Additional resources