Adding Code to Your User Control

In this lesson, you will learn how to add code to your user control to display the full name and to expose new properties.

Like standard controls, user controls have properties, methods, and events. As the developer, you will write code to handle your control's events, and you will decide which properties are exposed to the user of your control.

Handling Events in a User Control

In order to make your user control useful, you will need to write some code to handle the control's events. Writing an event-handling procedure for a user control is no different than it is for a form or a control.

In this example, you will write an event procedure that will update the FullName label with the contents of the FirstName, MiddleName, and LastName boxes as you type, using the TextChanged event handler.

Try It!

To add code to a user control

1. 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, Understanding the User Control Designer, and complete the procedures in that lesson.

2. In the Solution Explorer, select NamesControl.vb, and then on the View menu choose Code.

3. In the Code Editor, add the following code for the FirstName_TextChanged event handler.

   Private Sub FirstName_TextChanged(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles FirstName.TextChanged, MiddleName.TextChanged, LastName.TextChanged
       ' Display the contents of the three text boxes in the label.
       FullName.Text = FirstName.Text & " " & MiddleName.Text & " " & LastName.Text
   End Sub
   

4. Press F5 to run the program. The UserControl TestContainer opens and displays your user control.

5. Enter your first, middle and last names in the three text boxes—as you type, your name is displayed in the FullName label.

If you look at the code that you entered above, you will notice that the Handles clause in the declaration handles the TextChanged event for all three TextBox controls. No matter which text box you type in first, the FullName label is always updated as you type.

Exposing Properties in a User Control

Properties of standard controls allow you to set and retrieve values for a control at design time and at run time. You will also want to make certain properties of your user control available so that you can set them in the Properties window at design time and reference them in your code.

Exposing properties in a user control is very similar to exposing properties in a class, the main difference being that you can also expose the properties of the controls contained in your user control. As with classes, you declare a Property and add code to the Get and Set procedures. If you are exposing a property of a contained control, you do not need to declare a private variable to store the value—the control's property stores it for you.

As it stands now, there is no way to retrieve the text that is entered into the FirstName, MiddleName, and LastName controls or the value of the FullName label. You need to expose their values as properties to make the control useful. Since you do not want the value of the FullName label to be changed outside of your own code, you will want to expose it as a read-only property.

Try It!

To add properties

1. In the Code Editor, add the following code to expose the FirstName, MiddleName, and LastName values as properties.

   Property FirstNameText() As String
       Get
           Return FirstName.Text
       End Get
       Set(ByVal value As String)
           FirstName.Text = value
       End Set
   End Property
   Property MiddleNameText() As String
       Get
           Return MiddleName.Text
       End Get
       Set(ByVal value As String)
           MiddleName.Text = value
       End Set
   End Property
   Property LastNameText() As String
       Get
           Return LastName.Text
       End Get
       Set(ByVal value As String)
           LastName.Text = value
       End Set
   End Property 
   

2. Add the following code to expose the value of the FullName label as a read-only property.

   ReadOnly Property FullNameText() As String
       Get
           Return FullName.Text
       End Get
   End Property
   

3. Press F5 to run the program.

4. In the UserControl TestContainer, scroll to the bottom of the Properties grid and select the FirstNameText property. Enter your name, and then select the FullNameText property—the FirstName text box should display your name, and the FullNameText property should match.

   Try changing some of the other properties in both the Properties grid and the control itself to see how they are related. This is what a user of your control will experience at design time.

5. On the File menu, choose Save All to save your work.

Next Steps

In this lesson, you learned how to handle events in your user control and how to expose some of its properties. You can learn more about properties in Closer Look: Adding Properties with Named Values, or you can go on to the next lesson and learn how to use the control that you created.

Next Lesson: Testing Your User Control.

See Also

Tasks

Adding Controls to Your User Control

Other Resources

Visible Objects: Creating Your First User Control

Programming with Objects: Using Classes

Visual Basic Guided Tour