Deborah's Developer MindScape






         Tips and Techniques for Web and .NET developers.

October 13, 2009

WinForms User Controls 101

Filed under: C#,VB.NET,WinForms @ 11:43 am

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!

6 Comments

  1.   jacquihair — October 13, 2009 @ 5:31 pm    Reply

    cooling open variation notes new levels page possible

  2.   Joacim Andersson — October 14, 2009 @ 4:37 am    Reply

    You forgot to mention Extender controls, a control that extends another by providing new properties and behavior. The classic example is the ToolTip control which, as soon as you’ve put on on a form, will extend all other controls with a ToolTip property.

  3.   pramod.pathak@quantumaeon.co.in — June 27, 2011 @ 3:18 am    Reply

    Please send this.

  4.   Mike Newman — December 24, 2011 @ 3:02 am    Reply

    Can you please give us some assistance on how to create a control similar to a combobox but replacing the listbox part of it with a multiline textbox?

    I have done this using the User Control which works but uses a lot of form real estate when the multiline textbox is closed which covers other controls on the form.

    Any guidance will be appreciated.

    Mike Newman

  5.   Arvind Kumar — March 11, 2012 @ 6:05 am    Reply

    WinForms User Controls 101 Good Article. Do read it

  6.   Robert Smith — November 17, 2012 @ 3:54 am    Reply

    This makes it all very simple (as hundreds of related pages do, no offense). But just make sure you test fully because in the world there are some gotchas. For instance, if you make a usercontrol that inherits from textbox then try to set the backcolor… what happens? Try it. Now compare the result to either creating a composite control that contains a textbox and exposes the backcolor property or just tossing a textbox control on a form and changing the backcolor (using a button press or other external event). An inherited does not just simply and magically mirror a textbox … a standaard textbox or textbox in a composite container will let you change the color and that color will “stick” as you enter and leave focus, click in an out, but when you inherit from textbox then your usercontrol wil only show the custom color when the control has focus. Why? I honestly have never found a reason, logically it should not do this but it does. Same oddness occurs if you need to code some action to occur on the TextChanged event … an inherited textbox control does not activate OnTextChanged on every actual change but a real textbox and thus a textbox contained in a usercontrol does. This may be due to the differences in OSes in that under XP the functionality was fine – as I recall – but under 7 the same inheritance code is not reliable no matter which framework version you target 2-4.

    Just thought I’d mention it, I’ve made and released hundreds of controls over the years and while inheriting is my most favorite path, I’ve learned that there are times when full testing has forced me to add the complexity of a VB5-era composite control for even a simple single-base alteration. It’s not really as simple as these short tips pages make it out.

RSS feed for comments on this post. TrackBack URI

Leave a comment

© 2019 Deborah's Developer MindScape   Provided by WPMU DEV -The WordPress Experts   Hosted by Microsoft MVPs