Walkthrough: Creating a Windows Forms User Control that Supports Lookup Databinding

  • Article

When displaying data on Windows Forms, you can choose existing controls from the Toolbox, or you can author custom controls if your application requires functionality not available in the standard controls. This walkthrough shows how to create a control that implements the LookupBindingPropertiesAttribute. Controls that implement the LookupBindingPropertiesAttribute can contain three properties that can be bound to data. Such controls are similar to a ComboBox.

For more information on control authoring, see Developing Windows Forms Controls at Design Time.

When authoring controls for use in databinding scenarios you need to implement one of the following databinding attributes:

Databinding Attribute Usage

Implement the DefaultBindingPropertyAttribute on simple controls, like a TextBox, that display a single column (or property) of data. For more information, see Walkthrough: Creating a Windows Forms User Control that Supports Simple Data Binding.

Implement the ComplexBindingPropertiesAttribute on controls, like a DataGridView, that display lists (or tables) of data. For more information, see Walkthrough: Creating a Windows Forms User Control that Supports Complex Data Binding.

Implement the LookupBindingPropertiesAttribute on controls, like a ComboBox, that display lists (or tables) of data, but also need to present a single column or property. (This process is described in this walkthrough page.)

This walkthrough creates a lookup control that binds to data from two tables. This example uses the Customers and Orders tables from the Northwind sample database. The lookup control will be bound to the CustomerID field from the Orders table. It will use this value to look up the CompanyName from the Customers table.

During this walkthrough, you will learn how to:

  • Create a new Windows Forms Application.

  • Add a new User Control to your project.

  • Visually design the user control.

  • Implement the LookupBindingProperty attribute.

  • Create a dataset with the Data Source Configuration Wizard.

  • Set the CustomerID column on the Orders table in the Data Sources window to use the new control.

  • Create a form to display data in the new control.

Prerequisites

In order to complete this walkthrough, you will need:

Creating a Windows Application

The first step is to create a Windows Application.

To create the new Windows project

  1. In Visual Studio, from the File menu, create a new Project.

  2. Name the project LookupControlWalkthrough.

  3. Select Windows Application and click OK. For more information, see Creating Windows-Based Applications.

    The LookupControlWalkthrough project is created and added to Solution Explorer.

Adding a User Control to the Project

This walkthrough creates a lookup control from a User Control, so add a User Control item to the LookupControlWalkthrough project.

To add a user control to the project

  1. From the Project menu, select Add User Control.

  2. Type LookupBox in the Name area, and then click Add.

    The LookupBox control is added to Solution Explorer and opens in the designer.

Designing the LookupBox Control

To design the LookupBox control

  • Drag a ComboBox from the Toolbox onto the user control's design surface.

Adding the Required Data-binding Attribute

For lookup controls that support data binding, you can implement the LookupBindingPropertiesAttribute.

To implement the LookupBindingProperties attribute

  1. Switch the LookupBox control to code view. (On the View menu, choose Code.)

  2. Replace the code in the LookupBox with the following:

    Imports System.Windows.Forms

Namespace CS
    <System.ComponentModel.LookupBindingProperties("DataSource", "DisplayMember", "ValueMember", "LookupMember")> _
    Partial Public Class LookupBox
        Inherits UserControl
        Public Property DataSource() As Object
            Get
                Return comboBox1.DataSource
            End Get
            Set(value As Object)
                comboBox1.DataSource = value
            End Set
        End Property

        Public Property DisplayMember() As String
            Get
                Return comboBox1.DisplayMember
            End Get
            Set(value As String)
                comboBox1.DisplayMember = value
            End Set
        End Property

        Public Property ValueMember() As String
            Get
                Return comboBox1.ValueMember
            End Get
            Set(value As String)
                If (value IsNot Nothing) AndAlso (value <> "") Then
                    comboBox1.ValueMember = value
                End If
            End Set
        End Property

        Public Property LookupMember() As String
            Get
                If comboBox1.SelectedValue IsNot Nothing Then
                    Return comboBox1.SelectedValue.ToString()
                Else
                    Return ""
                End If
            End Get
            Set(value As String)
                If (value IsNot Nothing) AndAlso (value <> "") Then
                    comboBox1.SelectedValue = value
                End If
            End Set
        End Property



        Public Sub New()
            InitializeComponent()
        End Sub
    End Class
End Namespace

    using System.Windows.Forms;

namespace CS
{
    [System.ComponentModel.LookupBindingProperties("DataSource", "DisplayMember", "ValueMember", "LookupMember")]
    public partial class LookupBox : UserControl
    {
        public object DataSource
        {
            get{ return comboBox1.DataSource; }
            set{ comboBox1.DataSource = value; }
        }

        public string DisplayMember
        {
            get{ return comboBox1.DisplayMember; }
            set{ comboBox1.DisplayMember = value; }
        }

        public string ValueMember
        {
            get { return comboBox1.ValueMember; }
            set
            {
                if ((value != null) && (value != ""))
                    comboBox1.ValueMember = value;
            }
        }

        public string LookupMember
        {
            get
            {
                if (comboBox1.SelectedValue != null)
                    return comboBox1.SelectedValue.ToString();
                else
                    return "";
            }
            set
            {
                if ((value != null) && (value != ""))
                    comboBox1.SelectedValue = value;
            }
        }



        public LookupBox()
        {
            InitializeComponent();
        }
    }
}

    Important

    If you are using Visual C#, update the namespace to match the namespace of your application. If you followed the naming conventions in this procedure, that namespace is LookupControlWalkthrough.

  3. From the Build menu, choose Build Solution.

Creating a Data Source from Your Database

This step creates a data source using the Data Source Configuration Wizard based on the Customers and Orders tables in the Northwind sample database. You must have access to the Northwind sample database to create the connection. For information on setting up the Northwind sample database, see How to: Install Sample Databases.

To create the Data Source

  1. On the Data menu, click Show Data Sources.

  2. In the Data Sources window, select Add New Data Source to start the Data Source Configuration Wizard.

  3. Select Database on the Choose a Data Source Type page, and then click Next.

  4. On the Choose your Data Connection page do one of the following:

    • If a data connection to the Northwind sample database is available in the drop-down list, select it.

      -or-

    • Select New Connection to launch the Add/Modify Connection dialog box. For more information, see Add/Modify Connection Dialog Box (General).

  5. If your database requires a password, select the option to include sensitive data, and then click Next.

  6. Click Next on the Save connection string to the Application Configuration file page.

  7. Expand the Tables node on the Choose your Database Objects page.

  8. Select the Customers and Orders tables, and then click Finish.

    The NorthwindDataSet is added to your project and the Customers and Orders tables appear in the Data Sources window.

Setting the CustomerID Column of the Orders Table To Use the LookupBox Control

Within the Data Sources window you can set the control to be created prior to dragging items onto your form.

To set the CustomerID column to bind to the LookupBox control

  1. Open Form1 in the designer.

  2. Expand the Customers node in the Data Sources window.

  3. Expand the Orders node (the one in the Customers node below the Fax column).

  4. Click the drop-down arrow on the Orders node and choose Details from the control list.

  5. Click the drop-down arrow on the CustomerID column (in the Orders node) and choose Customize.

  6. Select the LookupBox from the list of Associated Controls in the Data UI Customization Options dialog box.

  7. Click OK.

  8. Click the drop-down arrow on the CustomerID column and choose LookupBox.

Adding Controls to the Form

You can create the data-bound controls by dragging items from the Data Sources window onto Form1.

To create data-bound controls on the Windows Form

  • Drag the Orders node from the Data Sources window onto the Windows Form and verify that the LookupBox control is used to display the data in the CustomerID column.

Binding the Control to Look up the CompanyName from the Customers Table

To setup the lookup bindings

  • Select the main Customers node in the Data Sources window and drag it onto the combo box in the CustomerIDLookupBox on Form1.

    This sets up the data binding to display the CompanyName from the Customers table while maintaining the CustomerID value from the Orders table. For more information, see How to: Create Lookup Tables in Windows Forms Applications.

Running the Application

To run the application

  • Press F5 to run the application.

  • Navigate through some records and verify that the CompanyName appears in the LookupBox control.

See Also

Tasks

How to: Set the Control to be Created when Dragging from the Data Sources Window

Concepts

What's New in Data Application Development

Binding Windows Forms Controls to Data in Visual Studio

Preparing Your Application to Receive Data

Fetching Data into Your Application

Binding Controls to Data in Visual Studio

Editing Data in Your Application

Validating Data

Saving Data

Other Resources

Connecting to Data in Visual Studio

Change History

Date

History

Reason

May 2011

Corrected sample code.

Customer feedback.