Adding a Control to the Toolbox

If you define your control in a separate class library project, you can use the ToolsCustomize Toolbox menu item to add the controls in that class library to the Toolbox. (You can also create a merge module project that will automate the process for you and ease sharing your control among other developers. We'll look at the manual process for now.)

Continuing with our RegexTextBox control, we have tested the control and found it to work to our satisfaction. We can add a class library project (select FileAdd ProjectNew Project) from the Add New Project dialog. Let's name the class library project CustomControls as shown in Figure 9.2. To complete the process of building the class library, we delete the basic class1.vb file added by the template; drag and drop the RegexTextBox.vb source file from the Windows Forms demo program to the CustomControls.vbproj file (using the Solution Explorer); and build the class library project. When following along with this example, you may need to make some adjustments to the class library project and control source code. For example, I needed to add the System.Windows.Forms.dll assembly to the CustomControls.vbproj references list and the complete namespace System.Windows.Forms to the Inherits statement in the RegexTextBox source code file (see Listing 9.3).

Figure 9.2. Adding a class library project from the Add New Project dialog.

To add the RegexTextBox control to the Toolbox, add a tab named My Controls by selecting Add Tab from the Toolbox's context menu. With the My Controls tab selected, select Customize Toolbox from the context menu, pick the .NET Framework Components tab of the Customize Toolbox menu, and click the Browse button. Browse to the CustomControls.dll assembly and click Open . You will see the name RegexTextBox appear in the name column of the Customize Toolbox dialog. Click OK to complete the operation. The new custom control is shown in the Toolbox in Figure 9.3.

Figure 9.3. The RegexTextBox control shown on the My Controls tab of the Toolbox.

You can now drag and drop the control from the Toolbox onto a form as you would any other control. The Form Designer will add a reference to the CustomControls.dll assembly and add the control to the form. You can test the control again to make sure it is working correctly with no undesirable side effects. For example, you can add a regular expression to the Pattern property (shown in Figure 9.4) and make sure the pattern validation works as planned.

Figure 9.4. The RegexTextBox Pattern property shown in the Properties window.

Associating a Bitmap with Your Control

Borland's VCL source code and the high quality of that framework helped to enhance a cottage industry of component makers . Perhaps one of the best-known component creators is Ray Knopka. Ray implemented Raize Tools and perhaps helped set an expected standard for components in the industry. In addition to the components solving the purported problem, Ray created clever design tools, and the components integrated in such a way as to appear to belong to the VCL. Visual Studio .NET offers tremendous support for third parties to build integrated, professional, custom components and controls. An expected level of support is the ability to use a custom bitmap with your control. I describe here this first taste of custom control fit and finish.

NOTE

I use component and control interchangeably in this section. After all, in the .NET Framework all controls do inherit from Component at some level, and in that regard a control is a component.

It makes sense to think of a component's bitmap as extra information or metadata. For this reason you use attributes specifically , the ToolboxBitmapAttribute to associate a bitmap with a custom component. If you apply the ToolboxBitmapAttribute to the component class, initializing the attribute with the path to a bitmap, that bitmap will be displayed in conjunction with the control in the Toolbox. A nice feature of .NET (if you are artistically inclined) is that you can actually draw the bitmap in the IDE and make it part of your project. Follow the numbered steps on the next page to create a bitmap and associate it with your custom control.

TIP

You can reuse an existing bitmap by passing the Type of the component that has the bitmap you want to reuse. For example, pass GetType(System.Windows.Forms.TextBox) to the ToolboxBitmapAttribute to use the TextBox 's bitmap with our custom RegexTextBox .

1. Select the custom control project from the Solution Explorer.

2. Click FileAdd New Item.

3. In the Add New Item dialog, pick the Bitmap File template, provide a good name for the bitmap, and click OK.

4. Open the bitmap file in the IDE by double-clicking on it (if it is not already open), and open the Properties window. Change the Height and Width values to 16 each.

5. Draw your bitmap.

6. Use the bright green color as your transparency color (see Figure 9.5).

   Figure 9.5. Use the bright green color (shown here as the medium gray bands near the top and bottom edges of the figure) as your transparency color.

   

7. You have a couple of options for associating the bitmap with the control.

   1. Name the bitmap file identically to the class name except for the extension, and change the bitmap's Build Action to Embedded Resource (see Figure 9.6).

      Figure 9.6. Change the bitmap file's Build Action to an Embedded Resource.

      

   2. Name the .bmp file anything you want, and then pass the filename to the ToolboxBitmapAttribute . (You can drag and drop the bitmap file from the Solution Explorer into the Code Editor, adding quotes after you drop the file.)

8. (If you chose option 7a, skip ahead to step 11.) If you chose option 7b, add a reference to System.Drawing.dll in the custom control's References list. (The System.Drawing.dll namespace contains the ToolboxBitmapAttribute .)

9. Add an Imports System.Drawing statement to the control's source file.

10. Apply the ToolboxBitmapAttribute , passing the complete path to the external file.

11. Build the control class library and select Customize Toolbox from the Toolbox's context menu, browse to the DLL containing the custom control, and click Open.

When you are finished you should see the custom control with the associated bitmap next to it. If you see the default cog symbol, something went wrong. Double-check to make sure you correctly followed the steps in the numbered list and try again.

There are several articles on associating a bitmap with a custom control. I tend to experiment to see what is true and what I can get away with. I was able to change the bitmap to 48 x 48 pixels and 256 colors even though the recommended specifications are 16 x 16 pixels and 16 colors. Using more pixels and colors provided me with a finer degree of control over creating the bitmap image, but creating cool icon- sized bitmaps requires more artistic talent than I have. If you do choose to deviate from the recommended specifications for Toolbox bitmapsor any general recommendationskeep in mind that you may be causing a subtle bug in your programs. Document what you did carefully , permitting someone else to fall back to recommended practices.

Adding Documentation to the Toolbox

The Properties window displays a description at the bottom of the window for each property. You can provide a description of your custom control's properties with the DescriptionAttribute . Defined in the System.ComponentModel namespace , this attribute can be applied as demonstrated in Listing 9.5. (The result of the DescriptionAttribute from Listing 9.5 is shown in Figure 9.7.)

Listing 9.5 An Excerpt from RegexTextBox Demonstrating Use of DescriptionAttribute

 <Description( _ "A regular expression used to validate the input text.")> _   Public Property Pattern() As String   Get     Return FPattern   End Get   Set(ByVal Value As String)     FPattern = Value   End Set End Property 

Figure 9.7. The DescriptionAttribute affects the display of a description of the Pattern property in the Properties window.

All the examples in this section can be found in RegexTextBox.sln , which contains CustomControls.vbproj and RegexTextBox.vbproj . We'll come back to more enhanced custom control capabilities after a brief detour . Let's look at creating custom user controls.