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

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

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 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98, Windows CE, Windows Mobile for Smartphone, Windows Mobile for Pocket PC

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5, 3.0, 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 3.5, 2.0

Community Additions

ADD
Show:
© 2014 Microsoft