Export (0) Print
Expand All

UserControl Class

Provides an empty control that can be used to create other controls.

Namespace: System.Windows.Forms
Assembly: System.Windows.Forms (in system.windows.forms.dll)

[ComVisibleAttribute(true)] 
[ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch)] 
public class UserControl : ContainerControl
/** @attribute ComVisibleAttribute(true) */ 
/** @attribute ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch) */ 
public class UserControl extends ContainerControl
ComVisibleAttribute(true) 
ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch) 
public class UserControl extends ContainerControl
Not applicable.

By extending ContainerControl, UserControl inherits all the standard positioning and mnemonic-handling code that is necessary in a user control.

The UserControl gives you the ability to create controls that can be used in multiple places within an application or organization. You can include all the code needed for validation of common data you ask the user to input; some examples of this are e-mail addresses (see Example section), telephone numbers, and postal codes. Another efficient use of the user control is to simply preload a ComboBox or ListBox with static items you commonly use in almost every application; some examples of this are countries/regions, cities, states, and office locations. For more information about authoring custom controls, see Developing Windows Forms Controls with the .NET Framework.

NoteNote:

You might consider creating a namespace that contains several classes of user controls and compiling it into one DLL. This DLL can be referenced and distributed with the application or all applications within an organization. This gives you the ability to reference the user control in many applications and save time laying out and coding the contained elements of the user control. A user control also gives you consistency within or across applications; for example, all address information input blocks will all have the same appearance and behavior. Consistency gives your application a more polished and professional appearance.

You can host Windows Forms UserControl derived classes inside of a form, on another UserControl, inside of Internet Explorer on a Web page, or inside a WebBrowser control hosted on a form.

NoteNote:

When hosting a UserControl inside of the WebBrowser control, you cannot turn off Visual Styles using the META tag value MSThemeCompatible. For more information about Visual Styles, see Rendering Controls with Visual Styles.

Note that for Smartphone applications, this control requires Windows Mobile Version 5.0 software for Smartphones.

The following code example creates a UserControl that can be reused in multiple applications to get user information. This example adds several Label controls, TextBox controls and an ErrorProvider to the UserControl to gather the user's information. Additionally, the user's e-mail address is validated in the Validating event of the TextBox and the ErrorProvider object is used to give the user feedback if the data fails validation. The code is intended to be compiled into a DLL for reference in other applications.

using System;
using System.Windows.Forms;
using System.Drawing;
using System.ComponentModel;

namespace UserControls 
{
   public class MyCustomerInfoUserControl : System.Windows.Forms.UserControl 
   {
      // Create the controls.
      private System.Windows.Forms.ErrorProvider errorProvider1;
      private System.Windows.Forms.TextBox textName;
      private System.Windows.Forms.TextBox textAddress;
      private System.Windows.Forms.TextBox textCity;
      private System.Windows.Forms.TextBox textStateProvince;
      private System.Windows.Forms.TextBox textPostal;
      private System.Windows.Forms.TextBox textCountryRegion;
      private System.Windows.Forms.TextBox textEmail;
      private System.Windows.Forms.Label labelName;
      private System.Windows.Forms.Label labelAddress;
      private System.Windows.Forms.Label labelCityStateProvincePostal;
      private System.Windows.Forms.Label labelCountryRegion;
      private System.Windows.Forms.Label labelEmail;
      private System.ComponentModel.IContainer components;

      // Define the constructor.
      public MyCustomerInfoUserControl() 
      {
         InitializeComponent();
      }
 
      // Initialize the control elements.
      public void InitializeComponent() 
      {
         // Initialize the controls.
         components = new System.ComponentModel.Container();
         errorProvider1 = new System.Windows.Forms.ErrorProvider();
         textName = new System.Windows.Forms.TextBox();
         textAddress = new System.Windows.Forms.TextBox();
         textCity = new System.Windows.Forms.TextBox();
         textStateProvince = new System.Windows.Forms.TextBox();
         textPostal = new System.Windows.Forms.TextBox();
         textCountryRegion = new System.Windows.Forms.TextBox();
         textEmail = new System.Windows.Forms.TextBox();
         labelName = new System.Windows.Forms.Label();
         labelAddress = new System.Windows.Forms.Label();
         labelCityStateProvincePostal = new System.Windows.Forms.Label();
         labelCountryRegion = new System.Windows.Forms.Label();
         labelEmail = new System.Windows.Forms.Label();

         // Set the tab order, text alignment, size, and location of the controls.
         textName.Location = new System.Drawing.Point(120, 8);
         textName.Size = new System.Drawing.Size(232, 20);
         textName.TabIndex = 0;

         textAddress.Location = new System.Drawing.Point(120, 32);
         textAddress.Size = new System.Drawing.Size(232, 20);
         textAddress.TabIndex = 1;

         textCity.Location = new System.Drawing.Point(120, 56);
         textCity.Size = new System.Drawing.Size(96, 20);
         textCity.TabIndex = 2;

         textStateProvince.Location = new System.Drawing.Point(216, 56);
         textStateProvince.Size = new System.Drawing.Size(56, 20);
         textStateProvince.TabIndex = 3;

         textPostal.Location = new System.Drawing.Point(272, 56);
         textPostal.Size = new System.Drawing.Size(80, 20);
         textPostal.TabIndex = 4;

         textCountryRegion.Location = new System.Drawing.Point(120, 80);
         textCountryRegion.Size = new System.Drawing.Size(232, 20);
         textCountryRegion.TabIndex = 5;

         textEmail.Location = new System.Drawing.Point(120, 104);
         textEmail.Size = new System.Drawing.Size(232, 20);
         textEmail.TabIndex = 6;

         labelName.Location = new System.Drawing.Point(8, 8);
         labelName.Size = new System.Drawing.Size(112, 23);
         labelName.Text = "Name:";
         labelName.TextAlign = System.Drawing.ContentAlignment.MiddleRight;

         labelAddress.Location = new System.Drawing.Point(8, 32);
         labelAddress.Size = new System.Drawing.Size(112, 23);
         labelAddress.Text = "Address:";
         labelAddress.TextAlign = System.Drawing.ContentAlignment.MiddleRight;

         labelCityStateProvincePostal.Location = new System.Drawing.Point(8, 56);
         labelCityStateProvincePostal.Size = new System.Drawing.Size(112, 23);
         labelCityStateProvincePostal.Text = "City, St/Prov. Postal:";
         labelCityStateProvincePostal.TextAlign = System.Drawing.ContentAlignment.MiddleRight;

         labelCountryRegion.Location = new System.Drawing.Point(8, 80);
         labelCountryRegion.Size = new System.Drawing.Size(112, 23);
         labelCountryRegion.Text = "Country/Region:";
         labelCountryRegion.TextAlign = System.Drawing.ContentAlignment.MiddleRight;

         labelEmail.Location = new System.Drawing.Point(8, 104);
         labelEmail.Size = new System.Drawing.Size(112, 23);
         labelEmail.Text = "email:";
         labelEmail.TextAlign = System.Drawing.ContentAlignment.MiddleRight;

         // Add the Validating and Validated handlers for textEmail.
         textEmail.Validating += new System.ComponentModel.CancelEventHandler(textEmail_Validating);
         textEmail.Validated += new System.EventHandler(textEmail_Validated);

         // Add the controls to the user control.
         Controls.AddRange(new System.Windows.Forms.Control[] 
         {
            labelName,
            labelAddress,
            labelCityStateProvincePostal,
            labelCountryRegion,
            labelEmail,
            textName,
            textAddress,
            textCity,
            textStateProvince,
            textPostal,
            textCountryRegion,
            textEmail
         });  

         // Size the user control.
         Size = new System.Drawing.Size(375, 150);
      }   


      private void MyValidatingCode()
      {
         // Confirm there is text in the control.
         if (textEmail.Text.Length == 0)
         {
            throw new Exception("Email address is a required field.");
         }
         // Confirm that there is a "." and an "@" in the e-mail address.
         else if(textEmail.Text.IndexOf(".") == -1 || textEmail.Text.IndexOf("@") == -1)
         {
            throw new Exception("Email address must be valid e-mail address format." +
             "\nFor example: 'someone@example.com'");
         }
      }


      // Validate the data input by the user into textEmail.
      private void textEmail_Validating(object sender, System.ComponentModel.CancelEventArgs e)
      { 
         try
         {
            MyValidatingCode();
         }

         catch(Exception ex)
         {
            // Cancel the event and select the text to be corrected by the user.
            e.Cancel = true;
            textEmail.Select(0, textEmail.Text.Length);

            // Set the ErrorProvider error with the text to display. 
            this.errorProvider1.SetError(textEmail,ex.Message);
          }
      }   


      private void textEmail_Validated(Object sender, System.EventArgs e)
      {
         //If all conditions have been met, clear the error provider of errors.
         errorProvider1.SetError(textEmail, "");
      }

   } // End Class   
} // End Namespace


package UserControls; 

import System.*;
import System.Windows.Forms.*;
import System.Drawing.*;
import System.ComponentModel.*;

public class MyCustomerInfoUserControl extends System.Windows.Forms.UserControl
{
    // Create the controls.
    private System.Windows.Forms.ErrorProvider errorProvider1;
    private System.Windows.Forms.TextBox textName;
    private System.Windows.Forms.TextBox textAddress;
    private System.Windows.Forms.TextBox textCity;
    private System.Windows.Forms.TextBox textStateProvince;
    private System.Windows.Forms.TextBox textPostal;
    private System.Windows.Forms.TextBox textCountryRegion;
    private System.Windows.Forms.TextBox textEmail;
    private System.Windows.Forms.Label labelName;
    private System.Windows.Forms.Label labelAddress;
    private System.Windows.Forms.Label labelCityStateProvincePostal;
    private System.Windows.Forms.Label labelCountryRegion;
    private System.Windows.Forms.Label labelEmail;
    private System.ComponentModel.IContainer components;

    // Define the constructor.
    public MyCustomerInfoUserControl()
    {
        InitializeComponent();
    } //MyCustomerInfoUserControl

    // Initialize the control elements.
    public void InitializeComponent()
    {
        // Initialize the controls.
        components = new System.ComponentModel.Container();
        errorProvider1 = new System.Windows.Forms.ErrorProvider();
        textName = new System.Windows.Forms.TextBox();
        textAddress = new System.Windows.Forms.TextBox();
        textCity = new System.Windows.Forms.TextBox();
        textStateProvince = new System.Windows.Forms.TextBox();
        textPostal = new System.Windows.Forms.TextBox();
        textCountryRegion = new System.Windows.Forms.TextBox();
        textEmail = new System.Windows.Forms.TextBox();
        labelName = new System.Windows.Forms.Label();
        labelAddress = new System.Windows.Forms.Label();
        labelCityStateProvincePostal = new System.Windows.Forms.Label();
        labelCountryRegion = new System.Windows.Forms.Label();
        labelEmail = new System.Windows.Forms.Label();

        // Set the tab order, text alignment, 
        // size, and location of the controls.
        textName.set_Location(new System.Drawing.Point(120, 8));
        textName.set_Size(new System.Drawing.Size(232, 20));
        textName.set_TabIndex(0);

        textAddress.set_Location(new System.Drawing.Point(120, 32));
        textAddress.set_Size(new System.Drawing.Size(232, 20));
        textAddress.set_TabIndex(1);

        textCity.set_Location(new System.Drawing.Point(120, 56));
        textCity.set_Size(new System.Drawing.Size(96, 20));
        textCity.set_TabIndex(2);

        textStateProvince.set_Location(new System.Drawing.Point(216, 56));
        textStateProvince.set_Size(new System.Drawing.Size(56, 20));
        textStateProvince.set_TabIndex(3);

        textPostal.set_Location(new System.Drawing.Point(272, 56));
        textPostal.set_Size(new System.Drawing.Size(80, 20));
        textPostal.set_TabIndex(4);

        textCountryRegion.set_Location(new System.Drawing.Point(120, 80));
        textCountryRegion.set_Size(new System.Drawing.Size(232, 20));
        textCountryRegion.set_TabIndex(5);

        textEmail.set_Location(new System.Drawing.Point(120, 104));
        textEmail.set_Size(new System.Drawing.Size(232, 20));
        textEmail.set_TabIndex(6);

        labelName.set_Location(new System.Drawing.Point(8, 8));
        labelName.set_Size(new System.Drawing.Size(112, 23));
        labelName.set_Text("Name:");
        labelName.set_TextAlign(System.Drawing.ContentAlignment.MiddleRight);

		labelAddress.set_Location(new System.Drawing.Point(8, 32));
        labelAddress.set_Size(new System.Drawing.Size(112, 23));
        labelAddress.set_Text("Address:");
        labelAddress.set_TextAlign(System.Drawing.ContentAlignment.MiddleRight);

        labelCityStateProvincePostal.set_Location(
            new System.Drawing.Point(8, 56));
        labelCityStateProvincePostal.set_Size(new System.Drawing.Size(112, 23));
        labelCityStateProvincePostal.set_Text("City, St/Prov. Postal:");
        labelCityStateProvincePostal.set_TextAlign(
            System.Drawing.ContentAlignment.MiddleRight);

        labelCountryRegion.set_Location(new System.Drawing.Point(8, 80));
        labelCountryRegion.set_Size(new System.Drawing.Size(112, 23));
        labelCountryRegion.set_Text("Country/Region:");
        labelCountryRegion.set_TextAlign(
            System.Drawing.ContentAlignment.MiddleRight);

        labelEmail.set_Location(new System.Drawing.Point(8, 104));
        labelEmail.set_Size(new System.Drawing.Size(112, 23));
        labelEmail.set_Text("email:");
        labelEmail.set_TextAlign(System.Drawing.ContentAlignment.MiddleRight);

        // Add the Validating and Validated handlers for textEmail.
        textEmail.add_Validating(new System.ComponentModel.CancelEventHandler(
            textEmail_Validating));
        textEmail.add_Validated(new System.EventHandler(textEmail_Validated));

        // Add the controls to the user control.
        get_Controls().AddRange(new System.Windows.Forms.Control[] { 
            labelName,labelAddress, labelCityStateProvincePostal, 
            labelCountryRegion,labelEmail, textName, textAddress, textCity,
            textStateProvince, textPostal, textCountryRegion, textEmail });

        // Size the user control.
        set_Size(new System.Drawing.Size(375, 150));
    } //InitializeComponent

    private void MyValidatingCode() throws Exception
    {
        // Confirm there is text in the control.
        if (textEmail.get_Text().length() == 0) {
            throw new Exception("Email address is a required field.");
        }
        // Confirm that there is a "." and an "@" in the e-mail address.
        else {
            if (textEmail.get_Text().IndexOf(".") == -1 ||
                    textEmail.get_Text().IndexOf("@") == -1) {
                throw new Exception("Email address must be valid e-mail"
                + "address format." + "\nFor example: 'someone@example.com'");
            }
        }
    } //MyValidatingCode

    // Validate the data input by the user into textEmail.
    private void textEmail_Validating(Object sender,
        System.ComponentModel.CancelEventArgs e)
    {
        try {
            MyValidatingCode();
        }
        catch (Exception ex) {
            // Cancel the event and select the text to be corrected by the user.
            e.set_Cancel(true);
            textEmail.Select(0, textEmail.get_Text().length());

            // Set the ErrorProvider error with the text to display. 
            this.errorProvider1.SetError(textEmail, ex.get_Message());
        }
    } //textEmail_Validating

    private void textEmail_Validated(Object sender, System.EventArgs e)
    {
        //If all conditions have been met, clear the error provider of errors.
        errorProvider1.SetError(textEmail, "");
    } //textEmail_Validated
} //End Class MyCustomerInfoUserControl 

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 98, Windows Server 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0, 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 2.0

Community Additions

ADD
Show:
© 2014 Microsoft