Export (0) Print
Expand All

Walkthrough: Creating a User Control that Supports Simple Data Binding 

When displaying data on forms in Windows applications, you can choose existing controls from the Toolbox, or you can author custom controls if your application requires functionality that is not available in the standard controls. This walkthrough shows how to create a control that implements the DefaultBindingPropertyAttribute. Controls that implement the DefaultBindingPropertyAttribute can contain one property that can be bound to data. Such controls are similar to a TextBox or CheckBox.

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

When authoring controls for use in data-binding scenarios, you need to implement one of the following data-binding attributes:

Databinding Attribute Usage

Implement the DefaultBindingPropertyAttribute on simple controls, like a TextBox, that display a single column (or property) of data. (This process is described in this walkthrough page.)

Implement the ComplexBindingPropertiesAttribute on controls, like a DataGridView, that display lists (or tables) of data. For more information, see Walkthrough: Creating a 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. For more information, see Walkthrough: Creating a User Control that Supports Lookup Databinding.

This walkthrough creates a simple control that displays data from a single column in a table. This example uses the Phone column of the Customers table from the Northwind sample database. The simple user control will display customer's phone numbers in a standard phone-number format by using a MaskedTextBox and setting the mask to a phone number.

During this walkthrough, you will learn how to:

  • Create a new Windows Application.

  • Add a new User Control to your project.

  • Visually design the user control.

  • Implement the DefaultBindingProperty attribute.

  • Create a dataset with the Data Source Configuration Wizard.

  • Set the Phone column in the Data Sources window to use the new control.

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

In order to complete this walkthrough, you will need:

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 SimpleControlWalkthrough.

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

    The SimpleControlWalkthrough project is created and added to Solution Explorer.

This walkthrough creates a simple data-bindable control from a User Control, so add a User Control item to the SimpleControlWalkthrough project.

To add a user control to the project

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

  2. Type PhoneNumberBox in the Name area, and click Add.

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

This walkthrough expands upon the existing MaskedTextBox to create the PhoneNumberBox control.

To design the PhoneNumberBox control

  1. Drag a MaskedTextBox from the Toolbox onto the user control's design surface.

  2. Select the smart tag on the MaskedTextBox you just dragged and choose Set Mask.

  3. Select Phone number in the Input Mask dialog box and click OK to set the mask.

For simple controls that support databinding, implement the DefaultBindingPropertyAttribute.

To implement the DefaultBindingProperty attribute

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

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

    using System.Windows.Forms;
    
    namespace CS
    {
        [System.ComponentModel.DefaultBindingProperty("PhoneNumber")]
        public partial class PhoneNumberBox : UserControl
        {
            public string PhoneNumber
            {
                get{ return maskedTextBox1.Text; }
                set{ maskedTextBox1.Text = value; }
            }
    
            public PhoneNumberBox()
            {
                InitializeComponent();
            }
        }
    }
    
    
    package JSL;
    
    /**@attribute System.ComponentModel.DefaultBindingProperty("Text")
     */
    public class PhoneNumberBox extends System.Windows.Forms.UserControl
    {
        /**@property
          */
        public String get_Text()
        {
            return maskedTextBox1.get_Text();
        }
    
        /**@property
         */
        public void set_Text(String value)
        {
            this.maskedTextBox1.set_Text(value);
        }
    
        public PhoneNumberBox()
        {
            InitializeComponent();
        }
    
        private System.Windows.Forms.MaskedTextBox maskedTextBox1;
        private System.ComponentModel.IContainer components;
    
        #region Component Designer generated code
        protected void Dispose(boolean disposing)
        {
            if (disposing)
            {
                if (components != null)
                {
                    components.Dispose();
                }
            }
            super.Dispose(disposing);
        }
    
        private void InitializeComponent()
        {
            this.maskedTextBox1 = new System.Windows.Forms.MaskedTextBox();
            this.SuspendLayout();
            // 
            // maskedTextBox1
            // 
            this.maskedTextBox1.set_CutCopyMaskFormat(System.Windows.Forms.MaskFormat.IncludeLiterals);
            this.maskedTextBox1.set_HidePromptOnLeave(false);
            this.maskedTextBox1.set_Location(new System.Drawing.Point(26, 25));
            this.maskedTextBox1.set_Mask("(999) 000-0000");
            this.maskedTextBox1.set_Name("maskedTextBox1");
            this.maskedTextBox1.set_Size(new System.Drawing.Size(100, 20));
            this.maskedTextBox1.set_TabIndex(0);
            this.maskedTextBox1.set_TextMaskFormat(System.Windows.Forms.MaskFormat.IncludeLiterals);
            // 
            // PhoneNumberBox
            // 
            this.set_AutoScaleDimensions(new System.Drawing.SizeF(6F, 13F));
            this.set_AutoScaleMode(System.Windows.Forms.AutoScaleMode.Font);
            this.get_Controls().Add(this.maskedTextBox1);
            this.set_Name("PhoneNumberBox");
            this.ResumeLayout(false);
            this.PerformLayout();
    
        }
        #endregion
    }
    
    
  3. From the Build menu, choose Build Solution.

This step uses the Data Source Configuration Wizard to create a data source based on the Customers table 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 table, and then click Finish.

    The NorthwindDataSet is added to your project and the Customers table appears in the Data Sources window.

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

To set the phone column to bind to the PhoneNumberBox control

  1. Open Form1 in the designer.

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

  3. Click the drop-down arrow on the Customers node and choose Details from the control list.

  4. Click the drop-down arrow on the Phone column and choose Customize.

  5. Select the PhoneNumberBox from the list of Associated Controls in the Data UI Customization Options dialog box.

  6. Click the drop-down arrow on the Phone column and choose PhoneNumberBox.

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

To create data-bound controls on the form

  • Drag the main Customers node from the Data Sources window onto the form and verify that the PhoneNumberBox control is used to display the data in the Phone column.

    Data-bound controls with descriptive labels appear on the form, along with a tool strip (BindingNavigator) for navigating records. A NorthwindDataSet, CustomersTableAdapter, BindingSource, and BindingNavigator appear in the component tray.

To run the application

  • Press F5 to run the application.

Depending on your application requirements, there are several steps you may want to perform after creating a control that supports data binding. Some typical next steps include:

Community Additions

ADD
Show:
© 2014 Microsoft