Testing and Using a Custom Control

When your control is complete, or at least ready for testing, you must build it by selecting the Build Solution command from the Build menu.

Assuming no syntax errors are found, the project is built, with the output a file named xxxx.dll, where xxxx is the project name. This DLL file will contain all the custom controls in your Windows Control Library project. The file will be located in the bin folder off the project folder.

To test your control, you need to create a Windows Application project. You can have this new project loaded into Visual Studio at the same time as your Windows Control Library project, which makes the process of testing and modifying the control easy.

To add this new project, follow these steps:

1. Select Add Project from the File menu, then select New Project to display the Add New Project dialog box.
2. In the dialog box, select the Windows Application icon, and enter a name for the new project (for example, TestControl).
3. Click OK.

Before you can use your custom control in the test project, you must add a reference to the control library, and then add the control to the toolbox. Here are the steps to add the reference:

• In the Solution Explorer, right-click the name of the test project.
• Select Add Reference from the pop-up menu to display the Add Reference dialog box.
• In the dialog box, select the Projects tab. This tab lists all other open projects — in this case, your control library project.
• Double-click the project name to add it to the Selected Components list.
• Click OK.

Next, you must add your new control to the toolbox:

• Right-click the toolbox.
• Select Add/Remove Items from the popup menu to display the Customize Toolbox dialog box.
• In the dialog box, select the .NET Framework Components tab.
• Click the browse button, and navigate to the DLL file that was created when you built your custom control project (in the bin folder off the project folder). Select the DLL file, then click the Open button.
• The name of your control will appear in the list of .Net Framework Components. Make sure a checkmark is present in the adjacent box.
• Close the dialog box by clicking OK.

At this point, your custom control will appear in the toolbox, and you are ready to use it in your test project like any other control.

Setting the Startup Project: When you have two or more projects open in Visual Studio, one must be the startup project — the one that is executed when you press F5 or select Start from the Debug menu. In this case, your test project must be the startup project; a control project cannot be executed by itself. To set the startup project, right-click the desired project in the Solution Explorer and select Set as Startup Project from the popup menu.

Once you have thoroughly tested your custom control, you can use it in Windows Application projects without having the control library project loaded into Visual Studio. If you have added the control to the toolbox, it remains there for future projects. You can remove a control from the toolbox by right-clicking it and selected Delete from the popup menu.

You can later add a reference to the control to other projects, and add the control to the toolbox, using essentially the same techniques that were described previously. The only difference is when adding the reference; since the control project will not be loaded, it will not appear in the list on the Project tab in the Add Reference dialog box. You'll have to browse for the DLL file just like when adding the control to the toolbox.

A Demonstration

I will end by walking you through all the steps involved in creating a custom control that subclasses a .Net framework control. The goal is to create a "number box" control that overcomes some of the shortcomings of the TextBox control for entry of numbers. Specifically, the control permits entry of the integers 0-9 only; and the control has a Value property that returns the contents of the control as a numeric value (rather than as a string, as the Text property does).

The first steps are to create a new Windows Control Library and create the fundamental class definition:

1. Create a new Windows Control Library project. Assign the name NumberBox to the project.
2. Open the code window for the default UserCOntrol that the project contains.
3. Edit the code to change the class name to NumberBox, and change the Inherits statement so the new class inherits from the TextBox class. The resulting code is shown here.

Public Class NumberBox
    Inherits System.Windows.Forms.TextBox
End Class

The next step is to add the code that will prevent the user from entering anything other than the digits 0-9 into the control. This is done using the KeyPress() event to "catch" keystrokes when they are made. Permitted keys are passed through to the control, whereas forbidden keys are cancelled. The code goes in the OnKeyPress() method, overriding the base TextBox class's method of the same name.

Protected Overrides Sub OnKeyPress(ByVal e As KeyPressEventArgs)
    Select Case e.KeyChar

        Case "0" To "9"
            ' Permitted character - do nothing.
        Case Else

            ' Not a permitted character - cancel it by telling the
            ' base class event that the KeyPress has been handled.
            e.Handled = True
    End Select
    MyBase.OnKeyPress(e)
End Sub

The final step is to add the Value property. The problem is that the base class, TextBox, stores data as a type String, and the new control should permit the value of the data to be retrieved as a numeric value (specifically, type Long). Thus, code in the property procedure has to convert from typeString to type Long when the data is retrieved, and from type Long to type String when the property is set. These tasks are accomplished with VB.Net's type conversion functions, CStr() and CLng().

Public Property Value() As Long
    Get
        Value = CLng(MyBase.Text)
    End Get
    Set(ByVal newValue As Long)
        Me.Text = CStr(newValue)
    End Set
End Property

The new control is ready to build and test, using the procedures that were explained earlier. When you use it on a form, you will see that it has all the properties of the base TextBox control, plus the Value property that was added. When running, the control accepts only numbers, and you can retrieve its Value property as needed.

In a real-world situation, you might want to fine-tune this custom control some more. For example, as written the control still permits access to its Text property in code, so nothing prevents the host program from putting some non-numeric text in the control. Also, the control's Value property returns zero if the control contains "0" and also if the control is empty; you might want to permit the control to differentiate between these two states.