Deborah's Developer MindScape

The same several questions often come up in the forums regarding the basics of building a user control with VB.NET or C#. The goal of this post is to answer those questions.

There are three basic types of WinForms user controls that you can create:

• Extended control
• Composite control
• Custom control

Each of these are discussed below.

Extended Control

Use an extended control whenever you want to extend the behavior of one particular control. Say for example that you want to build your own TextBox that only allows alphabetic characters. Or you want to build your own Button that has specific behaviors.

The best thing about extended controls is that you automatically get all of the intrinsic behavior of the original control. All you need to do is add any extended functionality that you want for the control.

To create this type of user control, follow these steps.

In C#:

1. Right-click on the project and select Add | User Control.
2. Name the user control and click Add.
3. Do NOT put anything on the design surface of the user control.
4. Open the code behind file (UserControl1.cs).
5. Modify the code to inherit from the control you are extending.

public partial class UserControl1 : TextBox

This example extends a TextBox control. Replace TextBox above with whatever WinForm control you want to extend.

NOTE: After changing the Inherits statement, you may get an error on a line that begins with this.AutoScaleMode. If so, just delete that line. It is no longer needed now that you are inheriting from a control other than UserControl.

In VB:

1. Right-click on the project and select Add | User Control.
2. Name the user control and click Add.
3. Do NOT put anything on the design surface of the user control.
4. Select the project in the Solution Explorer and click the Show All Files button in the Solution Explorer toolbar.
5. Click on the plus sign to the left of the user control in Solution Explorer to view the nodes below it.
6. Double-click on the designer file to open it. (UserControl1.Designer.vb)
7. Modify the code to inherit from the control you are extending.

Partial Class UserControl1
    Inherits TextBox

This example extends a TextBox control. Replace TextBox above with whatever WinForm control you want to extend.

NOTE: After changing the Inherits statement, you may get an error on a line that begins with Me.AutoScaleMode. If so, just delete that line. It is no longer needed now that you are inheriting from a control other than UserControl.

Then add any additional behavior or functionality that you want in the extended control.

The MSDN documentation provides an example of building an extended control using VB.NET here and C# here.

Composite Control

A composite controls is so named because it is composed of multiple controls. Use this type of user control any time you want to build a control that combines a set of other controls. For example, you want to build a search control that contains a Textbox for entry of the text to search, Button to click to perform the search, and ListBox for the results of the search.

The best thing about composite controls is that you can easily add any controls to the composite control using the design surface.

However, because it is a composite control that inherits from UserControl, no properties, methods, or events from any of the underlying controls are exposed. This means that when you use the user control, you cannot set the Text property of the TextBox or respond to Button click events without writing some code.

You basically have to write code to expose any property, method, or event that you need.

To create this type of user control, follow these steps:

1. Right-click on the project and select Add | User Control.
2. Name the user control and click Add.
3. Put the controls you want onto the design surface.
4. Expose any properties, methods, or events that you need.

An example of generating events from a user control is provided in this post.

The MSDN documentation provides an example of building a composite control using VB.NET here and C# here.

Custom Control

A custom control is a control you create from the ground up including all control drawing and any unique behavior.

To build a custom control, inherit from Control to get the basic behavior of a WinForms control. Then use the OnPaint event to render your custom user interface.

The MSDN documentation provides an example of building a simple custom control here.

Enjoy!