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)

'Declaration
<ComVisibleAttribute(True)> _
<ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch)> _
Public Class UserControl
	Inherits ContainerControl
'Usage
Dim instance As UserControl

/** @attribute ComVisibleAttribute(true) */ 
/** @attribute ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch) */ 
public class UserControl extends ContainerControl
ComVisibleAttribute(true) 
ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch) 
public class UserControl extends ContainerControl

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

Imports System
Imports System.Windows.Forms
Imports System.Drawing
Imports System.ComponentModel
Imports Microsoft.VisualBasic

Namespace UserControls

   Public Class MyCustomerInfoUserControl
      Inherits System.Windows.Forms.UserControl

      ' Create the controls.
      Private errorProvider1 As System.Windows.Forms.ErrorProvider
      Private textName As System.Windows.Forms.TextBox
      Private textAddress As System.Windows.Forms.TextBox
      Private textCity As System.Windows.Forms.TextBox
      Private textStateProvince As System.Windows.Forms.TextBox
      Private textPostal As System.Windows.Forms.TextBox
      Private textCountryRegion As System.Windows.Forms.TextBox
      Private WithEvents textEmail As System.Windows.Forms.TextBox
      Private labelName As System.Windows.Forms.Label
      Private labelAddress As System.Windows.Forms.Label
      Private labelCityStateProvincePostal As System.Windows.Forms.Label
      Private labelCountryRegion As System.Windows.Forms.Label
      Private labelEmail As System.Windows.Forms.Label
      Private components As System.ComponentModel.IContainer        
        
      ' Define the constructor.
      Public Sub New()
         InitializeComponent()
      End Sub        
        
      ' Initialize the control elements.
      Public Sub 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 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)
      End Sub        

      Private Sub MyValidatingCode()
         ' Confirm there is text in the control.
         If textEmail.Text.Length = 0 Then
            Throw New Exception("Email address is a required field")
         Else
            ' Confirm that there is a "." and an "@" in the e-mail address.
            If textEmail.Text.IndexOf(".") = - 1 Or textEmail.Text.IndexOf("@") = - 1 Then
               Throw New Exception("Email address must be valid e-mail address format." + _
                 Microsoft.VisualBasic.ControlChars.Cr + "For example 'someone@example.com'")
            End If
         End If
      End Sub 

      ' Validate the data input by the user into textEmail.
      Private Sub textEmail_Validating(sender As Object, _
                                       e As System.ComponentModel.CancelEventArgs) Handles textEmail.Validating
         Try
            MyValidatingCode()
   
         Catch ex As Exception
            ' 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. 
            Me.errorProvider1.SetError(textEmail, ex.Message)
         End Try
      End Sub 


      Private Sub textEmail_Validated(sender As Object, _
                                      e As System.EventArgs) Handles textEmail.Validated
         ' If all conditions have been met, clear the error provider of errors.
         errorProvider1.SetError(textEmail, "")
      End Sub        

   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 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 .NET Framework does not support all versions of every platform. For a list of the supported versions, see System Requirements.

.NET Framework

Supported in: 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 2.0

Community Additions

ADD
Show:
© 2014 Microsoft