Binding to Data Source in Code

• Jul 02, 2024
• 5 minutes to read

The Data Layout Control can be bound to a data source in code with the DataLayoutControl.DataSource property. The following code demonstrates binding to a custom Address business object using the BindingSource component.

C#

BindingSource addressBindingSource = new BindingSource();
addressBindingSource.DataSource = typeof(Address);
addressBindingSource.AddNew();

dataLayoutControl1.DataSource = addressBindingSource;
dataLayoutControl1.RetrieveFields();

public class Address {
    public string City { get; set; }
    public string Country { get; set; }
    public string Phone { get; set; }
    public string Fax { get; set; }
    public string Email { get; set; }
}

VB.NET

Dim addressBindingSource As New BindingSource()
addressBindingSource.DataSource = GetType(Address)
addressBindingSource.AddNew()

dataLayoutControl1.DataSource = addressBindingSource
dataLayoutControl1.RetrieveFields()

Public Class Address
    Public Property City As String
    Public Property Country As String
    Public Property Phone As String
    Public Property Fax As String
    Public Property Email As String
End Class

Note the DataLayoutControl.RetrieveFields method called after setting the DataLayoutControl.DataSource property. This method obtains information on available public properties in the bound data source and creates a layout item with an editor for each property.

Instead of manually calling the RetrieveFields method, you can enable the DataLayoutControl.AutoRetrieveFields property (which is disabled by default). With this property set to true, a layout is automatically re-built when a new data source is assigned to the DataLayoutControl.DataSource property.

C#

BindingSource addressBindingSource = new BindingSource();
addressBindingSource.DataSource = typeof(Address);
addressBindingSource.AddNew();

dataLayoutControl1.AutoRetrieveFields = true;
dataLayoutControl1.DataSource = addressBindingSource;

VB.NET

Dim addressBindingSource As New BindingSource()
addressBindingSource.DataSource = GetType(Address)
addressBindingSource.AddNew()

dataLayoutControl1.AutoRetrieveFields = True
dataLayoutControl1.DataSource = addressBindingSource

By default, the Data Layout Control generates a linear vertical layout. Auto-generated editors embedded in layout items are bound to corresponding fields in the data source. The following sections show how to customize binding settings, editor types, layout items and editor options, and modify the layout.

Customize General Binding Settings and Layout Column Count

You can use a DataLayoutControl.RetrieveFields method overload to customize binding settings for all auto-generated editors and specify the layout column count.

C#

void RetrieveFields(RetrieveFieldsParameters parameters)

The RetrieveFieldsParameters object provides the following parameters:

RetrieveFieldsParameters.DataSourceUpdateMode	Gets or sets the default value used to initialize the Binding.DataSourceUpdateMode property for all auto-generated editors. https://docs.microsoft.com/en-us/dotnet/api/system.windows.forms.binding.datasourceupdatemode This property indicates when changes to the bound editor property are propagated to the data source.
RetrieveFieldsParameters.DataSourceNullValue	Gets or sets the default value used to initialize the Binding.DataSourceNullValue property for all auto-generated editors. This property identifies the value to be stored in the data source if the editor’s value is null or empty.
RetrieveFieldsParameters.ColumnCount	Gets or sets the number of columns in the layout that will be generated.

To customize binding settings for individual layout items/editors, use the approach demonstrated in the following section.

Customize Individual Binding Settings, Editor Type and Visibility

When retrieving information on available public fields from the bound data source, the Data Layout Control fires the DataLayoutControl.FieldRetrieving event for each of these fields. This event fires before a layout item with an embedded editor is generated and thus it occurs prior to the editor’s data binding. It allows you to customize the type of editor to be generated, modify editor binding settings and to hide certain editors (hidden layout items will be accessible at runtime from the Customization Form).

Customize Layout Item and Editor Settings

After a layout is created, the DataLayoutControl.FieldRetrieved event fires for each generated layout item. This event allows you to customize the settings of individual layout items and editors and to rearrange layout items.

Customize Layout Using Data Annotation Attributes

When binding to a business object, you can apply certain Data Annotation Attributes to the object’s properties to give display names to layout items, specify the order of layout items, arrange items into groups and tabbed groups, specify the control’s readonly status, assign masks to editors, etc.

The following example demonstrates how to hide specific data fields:

C#

using System.Windows.Forms;
using System.ComponentModel.DataAnnotations;

//...
private void Form1_Load(object sender, EventArgs e) {
    BindingSource addressBindingSource = new BindingSource();
    addressBindingSource.DataSource = typeof(Address);
    addressBindingSource.AddNew();

    dataLayoutControl1.DataSource = addressBindingSource;
    dataLayoutControl1.RetrieveFields();
}

public class Address {
    // Hides the ID data field from the layout.
    [Display(AutoGenerateField = false)]
    public int ID { get; set; }
    public string City { get; set; }
    public string Country { get; set; }
}

VB.NET

Imports System.Windows.Forms
Imports System.ComponentModel.DataAnnotations

'...
Private Sub Form1_Load(ByVal sender As Object, ByVal e As EventArgs)
    Dim addressBindingSource As New BindingSource()
    addressBindingSource.DataSource = GetType(Address)
    addressBindingSource.AddNew()

    dataLayoutControl1.DataSource = addressBindingSource
    dataLayoutControl1.RetrieveFields()
End Sub

Public Class Address
    ' Hides the ID data field from the layout.
    <Display(AutoGenerateField := False)>
    Public Property ID() As Integer
    Public Property City() As String
    Public Property Country() As String
End Class

Read the following topic for more information: Data Annotation Attributes - Building Layout from Business Object.

Manage Data Records

Use the DataLayoutControl‘s following properties and methods to manage data records in code:

• RecordCount — Returns the number of records in the bound data source.
• CurrentRecord — Gets an object that specifies the current data record.
• CurrentRecordPosition — Gets or sets the index of the data record to be displayed in the control.
• GetCurrentRecordFieldValue(String) — Returns the current record’s cell value in the specified data field.
• SetCurrentRecordFieldValue(String, Object) — Assigns the specified value to the current record’s specified field.

Note

Handle data source events (for example, BindingList<T>.ListChanged, DataTable.ColumnChanged) to track changes in bound objects.