Walkthrough: Creating a Windows Forms Toolbox Control

Article
01/30/2013

The Windows Forms Toolbox Control template that is included in the Visual Studio 2010 SDK lets you create a control that is automatically added to the Toolbox when the extension is installed. This walkthrough shows how to use the template to create a counter control that you can distribute to other users.

Prerequisites

To complete this walkthrough, you must install the Visual Studio 2010 SDK.

Note

For more information about the Visual Studio SDK, see Visual Studio Integration SDK. To find out how to download the Visual Studio SDK, see Visual Studio Extensibility Developer Center on the MSDN website.

Finding the Windows Forms Toolbox Control Template in Visual Studio

The Windows Forms Toolbox Control template is available in the New Project dialog box, under Installed Templates, in these locations:

Visual Basic, Extensibility. The language of the project is Visual Basic.
Visual C#, Extensibility. The language of the project is C#.

Creating a Windows Forms Toolbox Control Project

The Windows Forms Toolbox Control template creates an undefined user control and provides all of the functionality that is required to add the control to the Toolbox.

To create the project

On the File menu, click New, and then click Project.
In the New Project dialog box, under Installed Templates, expand the node for your preferred programming language and then select Extensibility. In the list of project types, select Windows Forms Toolbox Control.
In the Name box, type the name you want to use for the project. (This walkthrough uses the name Counter.) Click OK.

This creates a solution that contains a user control, an attribute to place the control in the Toolbox, and a VSIX manifest for deployment. The Name box sets the name of the solution and the name of the namespace, but it does not set the name of the control as it appears in the Toolbox. You will set that later in the walkthrough.

Building a User Interface for the Control

The Counter control requires two child controls: a Label to display the current count, and a Button to reset the count to 0. No other child controls are required because callers will increment the counter programmatically.

To build the user interface

In Solution Explorer, double-click ToolboxControl.cs to open it in the designer.
From the Toolbox, drag a Label control to the design surface.
Resize the user control to 150 x 50 pixels, and resize the button to 50 x 20 pixels.
In the Properties window, set the following values for the controls on the design surface.

Control

Property

Value

Label1

Text

""

Button1

Name

btnReset

Button1

Text

Reset

Control	Property	Value
Label1	Text	""
Button1	Name	btnReset
Button1	Text	Reset

Coding the User Control

The Counter control will expose a method to increment the counter, an event to be raised whenever the counter is incremented, a Reset button, and three properties to store the current count, the display text, and whether to show or hide the Reset button. The ProvideTolboxControl attribute determines where in the Toolbox the Counter control will appear.

To code the user control

Double-click the form to open its load event handler in the code window.
Above the event handler, create an integer to store the counter value and a string to store the display text, as shown in the following example.
```
int currentValue;
string displayText;
```
Create the following public property declarations.
```
public int Value {
    get { return currentValue; } 
    }

public string Message {
    get { return displayText; }
    set { displayText = value; }
}

public bool ShowReset {
    get { return btnReset.Visible; }
    set { btnReset.Visible = value; }
}
```
Callers can access these properties to get and set the display text of the counter, and to show or hide the Reset button. Callers can obtain the current value of the read-only Value property, but they cannot set the value directly.
Put the following code in the Load event for the control.
```
private void ToolboxControl_Load(object sender, EventArgs e)
{
    currentValue = 0;
    label1.Text = Message + Value;
}
```
Setting the label text in the Load event enables the target properties to load before their values are applied. Setting the label text in the constructor would result in an empty label.

Create the following public method to increment the counter.

public void Increment()
{
    currentValue++;
    label1.Text = displayText + Value;
    Incremented(this, EventArgs.Empty);
}

Add a declaration for the Incremented event.
```
public event EventHandler Incremented;
```
Callers can add handlers to this event to respond to changes in the value of the counter.
Return to design view and double-click the Reset button to generate the btnReset_Click event handler, and then fill it in as shown in the following example.
```
private void btnReset_Click(object sender, EventArgs e)
{
    currentValue = 0;
    label1.Text = displayText + Value;
}
```
At the class definition, right-click the class name, click Refactor, click Rename, and then change the name of the class to Counter. This is the name that will be displayed in the Toolbox.

Immediately above the class definition, in the ProvideToolboxControl attribute declaration, change the value of the first parameter from "Counter" to "General". This sets the name of the item group that will host the control in the Toolbox.

The following example shows the ProvideToolboxControl attribute and the adjusted class definition.

[ProvideToolboxControl("General", false)]
public partial class Counter : UserControl

The following example shows the code for the completed user control.

using System;
using System.Windows.Forms;

namespace Counter
{
    [ProvideToolboxControl("General", false)]
    public partial class Counter : UserControl
    {
        public Counter()
        {
            InitializeComponent();
        }

        private void btnReset_Click(object sender, EventArgs e)
        {
            currentValue = 0;
            label1.Text = displayText + Value;
        }

        int currentValue;
        string displayText;

        public int Value {
            get { return currentValue; } 
            }

        public string Message {
            get { return displayText; }
            set { displayText = value; }
        }

        public bool ShowReset {
            get { return btnReset.Visible; }
            set { btnReset.Visible = value; }
        }

        private void ToolboxControl_Load(object sender, EventArgs e)
        {
            currentValue = 0;
            label1.Text = Message + Value;
        }

        public void Increment()
        {
            currentValue++;
            label1.Text = displayText + Value;
            Incremented(this, EventArgs.Empty);
        }

        public event EventHandler Incremented;
    }
}

Testing the Control

To test a Toolbox control, first test it in the development environment and then test it in a compiled application.

To test the control

Press F5.

This builds the project and opens a second instance of Visual Studio that has the control installed.
In the new instance of Visual Studio, create a Windows Forms project.
In Solution Explorer, double-click Form1.cs to open it in the designer.
In the Toolbox, the Counter control should be displayed in the General section.
Drag a Counter control to your form, and then select it. The Value, Message, and ShowReset properties will be displayed in the Properties window, together with the properties that are inherited from UserControl.
Set the Message property to Count:.
Drag a Button control to the form, and then set the name and text properties of the button to Test.
Double-click the button to open Form1.cs in code view and create a click handler.
In the click handler, call counter1.Increment().
In the constructor function, after the call to InitializeComponent, type Counter1.Incremented += and then press TAB twice.

Visual Studio generates a form-level handler for the Counter1.Incremented event.
Highlight the Throw statement in the event handler, type mbox, and then press TAB twice to generate a message box from the mbox code snippet.
On the next line, add the following if/else block to set the visibility of the Reset button.
```
if (counter1.Value < 5) counter1.ShowReset = false;
else counter1.ShowReset = true;
```
Press F5.

The form opens. The Counter control displays the following text.

Count: 0
Click Test.

The counter increments and Visual Studio displays a message box.
Close the message box.

The Reset button disappears.
Click Test until the counter reaches 5, and then close the message box.

The Reset button re-appears.
Click Reset.

The counter resets to 0.

Next Steps

When you build a Toolbox control, Visual Studio creates a file named ProjectName.vsix in the \bin\debug\ folder of your project. You can deploy the control by uploading the .vsix file to a network or to a Web site. When a user opens the .vsix file, the control is installed and added to the Visual Studio Toolbox on the user's computer. Alternatively, you can upload the .vsix file to the Visual Studio Gallery Web site so that users can find it by browsing in Extension Manager.