User Controls

Creating your own customized controls for use in Windows forms isn't hard—you just need to create a user control. A user control works much like any other Windows form—except that you can add it to other forms just like any other control. To see how this works, you can take a look at the UserControls example on the CD-ROM, which creates a user control and uses it in a Windows form.

To create the user control, you use the File|New Project menu item, opening the New Project dialog you see in Figure 24.1, and selecting the Windows Control Library item.

Figure 24.1: Creating a user control project.

When you click the OK button in the New Project dialog, the new user control is created, as you see in Figure 24.2. The user control looks like a small Windows form; you can add your own controls to it or give it a custom appearance in code. I've added a label control to the user control, as you can see in Figure 24.2.

Figure 24.2: Creating a user control.

Like any other control, user controls can support properties, methods, and events. For example, to let the user set the background color of the label in our user control, I can add a property named DisplayColor to the user control. I do that by opening the code for the user control in a code designer—note that the user control is based on the System.Windows.Forms.UserControl class (see "Using the System.Windows.Forms.UserControl Class" in this chapter):

Public Class UserControl1
    Inherits System.Windows.Forms.UserControl

' Windows Form Designer generated code...
        ⋮

I can add the DisplayColor property to this code, like this (see "Creating Properties" in Chapter 11):

Public Class UserControl1
    Inherits System.Windows.Forms.UserControl

' Windows Form Designer generated code...

    Private LabelColor As Color

    Property DisplayColor() As Color
        Get
            Return LabelColor
        End Get

        Set(ByVal Value As Color)
            LabelColor = Value
            Label1.BackColor = LabelColor
        End Set
    End Property

I can add new methods to the user control as easily (see "Creating Methods" in Chapter 11). For example, to add a SetText method to set the text displayed by the label in this user control, just add a public method to the control's code, following the implementation of the DisplayColor property above:

Public Sub SetText(ByVal NewText As String)
    Label1.Text = NewText
End Sub

And I can add an event easily as well; all I have to do is to declare that event and the parameters sent to its event handlers. For example, we could implement a TextModified event in the control that happens when the text changes in the label in the control. Event handlers for this event should be passed the new text, so here's how I declare this event (see "Creating Events" in Chapter 11):

Public Class UserControl1
    Inherits System.Windows.Forms.UserControl

' Windows Form Designer generated code...
Private LabelColor As Color
Public Event TextModified(ByVal NewText As String)
        ⋮

We can make the TextModify event happen when the SetText method is called to change the text displayed in the control. All we have to do is to use the RaiseEvent statement:

Public Sub SetText(ByVal NewText As String)
    Label1.Text = NewText
    RaiseEvent TextModified(NewText)
End Sub

And that completes the user control. To make this control available to other projects, it must be compiled into .dll (dynamic link library) form, so select the Build|Build Solution menu item now, which builds the .dll file we'll need.

To add this new user control to a Windows form, select the File|Add Project|New Project menu item to add a new Windows form project to the current solution; I've named this new project TestApplication in the UserControls example on the CD-ROM. Because you can't run user controls directly, you should make the new text application the startup project for the whole solution by selecting that project in the Solution Explorer, followed by the Project|Set as Startup Project menu item.

The next step is to add a new user control of the type we've created to the main form in the text application. To do that, we'll need a reference to the user control's project, so right-click the test application's References item in the Solution Explorer, and choose the Add Reference menu item, opening the Add Reference dialog you see in Figure 24.3. To add a reference to the UserControls project, click the Projects tab and double-click the UserControls item, adding that item to the Selected Components box at the bottom of the dialog, and click OK.

Figure 24.3: The UserControls example at work.

This adds the user control to the toolbox of the text application, as you see in Figure 24.4. You can now add a user control, UserControl11, to the test application's main form, as you would any other control. You can see this new user control in Figure 24.4, and you also can see our custom property, Display Color, in the Properties window. (In fact, because we've declared this property as type Color, Visual Basic will display a drop-down list of palette colors you can select from if you select this property in the properties window.) In this example, I've selected the color Aqua as the background color for use in our user control; you can see that color (in glorious black and white) in the user control in the test application's main form shown in Figure 24.4.

Figure 24.4: Adding a user control in the Visual Basic IDE.

Besides setting the DisplayColor property, I also can use the new control's SetText method. To do that, I've added the "Click Me" button you can see in Figure 24.4, and used that button's Click event handler to set the text "Hello!" in the user control, like this:

Private Sub Button1_Click(ByVal sender As System.Object, _
    ByVal e As System.EventArgs) Handles Button1.Click
    UserControl11.SetText("Hello!")
End Sub

When the text in the control changes, that control causes a TextModified event, and we can add code to that event's handler just as you would any other control's event (that is, by using the drop-down list boxes at the top of the code designer for the test application's main form). In this example, I'll display the new text in a text box when the TextModified event occurs:

Private Sub UserControl11_TextModified(ByVal NewText As String) _
    Handles UserControl11.TextModified
    TextBox1.Text = "New text: " & NewText
End Sub

Now I can run the test application, giving us the result you see in Figure 24.5. You can see the user control in that figure, and when I click the button, the text in the control is set to "Hello!", as it should be, the TextModified event occurs, and the text box in the example handles that event, displaying the new text.

Figure 24.5: Using a user control.

And that's all we've needed to do to create a new user control, complete with a property, method, and event.