Closer Look: Customizing Your User Control

Article
07/25/2011

In this lesson, you will learn how to customize your user control to make it more useful.

Adding Labels

In the last lesson, you tested the NamesControl user control and found that it works like it should. You may have also noticed some ways it could be improved. For example, it isn't obvious which name should be entered in which text box, and there is no way to make sure that a user enters all three names.

In order to make the user control more useful, you can add labels to identify each text box. You could set the text for the labels to read "First Name", "Middle Name", and "Last Name", but what if you later decided that you wanted a "Middle Initial" instead? It is better to create properties for the label text so that you can change the text at design time and provide a default value for each property.

Try It!

To customize your user control

Open the NamesUserControl project that you created in the previous lesson. If you did not save it, you will first need to go back to the previous lesson, Testing Your User Control, and complete the procedures in that lesson.
In Solution Explorer, select NamesControl.vb, and then on the View menu, choose Designer.
From the Toolbox, drag three Label controls onto the designer, and place one above each TextBox.
In Solution Explorer, select NamesControl.vb, and then on the View menu, choose Code.

In the Code Editor, add the following code to create properties for the label text.

Private text1 As String = "First Name"
Property Label1Text() As String
    Get
        Return text1
    End Get
    Set(ByVal value As String)
        text1 = value
        Label1.Text = text1
    End Set
End Property
Private text2 As String = "Middle Name"
Property Label2Text() As String
    Get
        Return text2
    End Get
    Set(ByVal value As String)
        text2 = value
        Label2.Text = text2
    End Set
End Property
Private text3 As String = "Last Name"
Property Label3Text() As String
    Get
        Return text3
    End Get
    Set(ByVal value As String)
        text3 = value
        Label3.Text = text3
    End Set
End Property

Notice that the code declares three Private variables for the label text, and that the declarations include the default value to be displayed.

In the Code Editor, select (NamesControl Events) from the left drop-down box, and then select the Load event from the right drop-down box.

Add the following code to the NamesControl_Load event handler.

' Initialize the three labels
Me.Label1.Text = Label1Text
Me.Label2.Text = Label2Text
Me.Label3.Text = Label3Text

On the Build menu, choose Build Solution.
In Solution Explorer, select Form1.vb, and then on the View menu, choose Designer.

Verify that labels have the default text. Try changing the Label1Text property in the Properties window, and verify that it changes in the control as well.
On the File menu, choose Close to close the form designer.

Adding Validation

Another useful customization would be to add code to validate what gets entered to make sure it is correct. Instead of validating each of the TextBox controls on their own, you can write validation code for the entire user control.

Most controls have a Validating event that is raised when the focus moves away from the control; this is where you will enter the validation code. In this case, you will want to write code to make sure that each text box contains a name.

If one or more of the text boxes is empty, you will want to display a message box to remind the user to enter his or her name. You can expose a property that contains a default message; that way, the user of your control can change the message to say what they want.

It is also possible that the user of your control may not require a middle name, so you will also want to add a Boolean property to turn off validation for the MiddleName text box.

Try It!

To add validation

In the Code Editor, add code for two properties related to validation—one to specify if the middle name is required, and another to specify a message to be displayed if validation fails.

Private required As Boolean = True
Property MiddleNameRequired() As Boolean
    Get
        Return required
    End Get
    Set(ByVal value As Boolean)
        required = value
    End Set
End Property
Private errormessage As String = "Please enter your name."
Property ValidationErrorMessage() As String
    Get
        Return errormessage
    End Get
    Set(ByVal value As String)
        errormessage = value
    End Set
End Property

In the Code Editor, select (NamesControl Events) from the left drop-down box, and then select the Validating event from the right drop-down box.

Add the following code to the NamesControl_Validating event handler.

If MiddleNameRequired = True Then
    If FirstName.Text = "" Or MiddleName.Text = "" Or _
LastName.Text = "" Then
        MsgBox(ValidationErrorMessage)
    End If
Else
    ' Middle name isn't required.
    If FirstName.Text = "" Or LastName.Text = "" Then
        MsgBox(ValidationErrorMessage)
    End If
End If

On the Build menu, choose Build Solution.
In Solution Explorer, select Form1.vb, and then on the View menu, choose Designer.

Select the user control on the form, and verify that the two new properties appear in the Properties window.
From the Toolbox, drag a Button control to the form.
Press F5 to run the program.

Enter your first and last name, but do not enter your middle name. Click the button, and a message box containing the ValidationErrorMessage should be displayed.
On the File menu, choose Save All to save your work.

Next Steps

In this lesson, you learned how to customize your user control to make it more useful. In the next lesson, you will learn how to use graphics to draw pictures and text.

Next Lesson: Drawing Pictures: Using Graphics

Closer Look: Customizing Your User Control

Adding Labels

Try It!

To customize your user control

Adding Validation

Try It!

To add validation

Next Steps

See Also

Tasks

Other Resources

Additional resources