Creating a Windows Forms Control (C++)

Windows Forms controls are components that can be added to Windows Forms applications (GUI applications that target the common language runtime). Windows Forms applications in Visual C++ use .NET Framework classes and other .NET features with the new Visual C++ syntax.

In this procedure, you create a Windows Forms control that displays a number. This number increments each time that a user clicks the label in an application. You will also create a Windows Forms application project to test the control.

This walkthrough covers the following:

• Creating a New Project.

• Designing the Control.

• Adding a Custom Property to the Control.

• Adding a Project to Test the Control.

• Placing the Control in an Application.

• Running the Application.

Prerequisites

This topic assumes that you understand the fundamentals of the C++ language.

For a video version of this topic, see Video How to: Creating a Windows Forms Control (C++).

Create a New Project

The Windows Forms Control project template that you use in this section creates a user control, which is a composite control that contains other controls.

Alternatively, you can create a Windows Forms control by deriving a class directly from the Control class (your code is responsible for drawing the control) or the Component class (a control that has no UI).

To create a new Windows Forms control project

1. From the File menu, click New, and then click Project….

2. On the Project Types pane, select CLR in the Visual C++ node, and then select Windows Forms Control Library in the Visual Studio installed templates pane.

   Type a name for the project, such as clickcounter.

   Type a different name for the solution, such as controlandtestapp.

   You can accept the default location, type a location that you want, or browse to a directory where you want to save the project.

3. The Windows Forms Designer opens and shows an area where you add the controls that you want to position on the control design surface.

Design the Control

In this step, you add a Label control to the control design surface. You then set some properties on the control itself and on the Label control it contains.

To set the properties of a user control

1. If you cannot see the Properties window, from the View menu, click Properties Window.

   In the Windows Forms Designer, click on the control to select it and set its properties as follows:

   • Set the Size property to 100, 100.

   • Set the BorderStyle to Fixed3D

     The label boundaries will be visible after you position the control in an application.

2. If the Toolbox window is not visible, select Toolbox from the View menu.

   Drag a Label control from the Toolbox to the design surface and position it near the middle of the control.

   Set these properties for the label:

   • Set the BorderStyle to FixedSingle.

   • Set the Text to the digit 0 (zero).

   • Set the Autosize to False.

   • Set the Size to 30, 20.

   • Set the TextAlign to MiddleCenter.

   Leave the Name property (how you refer to it in code) unchanged as label1. The control should resemble the following:

   

3. Add an event handler for the label Click event (the default event for a label) by double-clicking the label.

4. The clickcounter.hfile is displayed in the editing area with an empty event handler method.

   Note

   If you need more room, close the Toolbox or Properties window by clicking the appropriate Close box or by unpinning the window so that it auto-hides.

5. Move the cursor to after the opening brace of the label1_Click method, press Enter, and type:

   int temp = System::Int32::Parse(label1->Text);
   temp++;
   label1->Text = temp.ToString();
   

   IntelliSense displays a list of valid choices after you type a scope resolution operator (::), dot operator (.) or arrow operator (->). You can highlight an item and press Tab or Enter or double-click an item to insert that item into your code.

   Also, when you type an opening parenthesis for a method, Visual Studio displays valid argument types for each overload of the method.

Add a Custom Property to the Control

In this step, you define a custom property that determines whether the number that is displayed on the control increments when a user clicks the label or when a user clicks any location on the control.

To add a custom property to a control

1. Place the cursor after the colon of the first public scope indicator, public:, at the top of the clickcounterControl.h file, press Enter, and then type the following:

   property bool ClickAnywhere {
       bool get() {
           return (label1->Dock == DockStyle::Fill);
       }
       void set(bool val) {
           if (val) 
               label1->Dock = DockStyle::Fill;
           else 
               label1->Dock = DockStyle::None;
       }
   }
   

   When you set the ClickAnywhere property of the control to true, the Dock property of the label is set to DockStyle::Fill, and the label fills the whole control surface. A click anywhere on the control surface will then cause a label Click event, which increments the number on the label.

   When the ClickAnywhere property is false (the default), the Dock property of the label is set to DockStyle::None. The label does not fill the control, and a click on the control must be inside the label boundaries to cause a label Click event, which increments the number.

2. Build the user control. On the Build menu, select Build Solution.

   If there are no errors, a Windows Forms control is generated with a file name of clickcounter.dll. You can locate this file in your project directory structure.

Add a Project to Test the Control

In this step, you create a Windows Forms application project in which you will position instances of the clickcounter control on a form.

To create a Windows Forms application project

• From the File menu, select New, and then click Project….

You can also add a project to the solution byright-clicking the controlandtestapp solutionin Solution Explorer, pointing to Add, andthen clicking New Project….

1. In the Project Types pane, select CLR in the Visual C++ node, and then select Windows Forms Application in the Visual Studio installed templates pane.

   Type a name for the project, such as testapp.

   Be sure to select Add to Solution instead of accepting the default Create New Solution setting in the Solution drop-down list, and then click OK.

2. The Windows Forms Designer for the new project opens, and shows a new form named Form1 as in this figure:

   

To add a control to the Toolbox

1. Add a reference to the control. Right-click the testapp project in Solution Explorer and click References.

   Click the Add New Reference button, click the Projects tab (you are adding a reference to another project in this solution), and then select the clickcounter project. Click OK two times.

2. If you cannot see the Toolbox window, select Toolbox from the View menu.

3. If you cannot find the clickCounter control in the Toolbox with a "gear" icon, then right-click the Toolbox and click Choose Items.

   Click the Browse button and locate the clickcounter.dll file in your solution directory structure. Select it and click Open.

   The clickcounter control is shown in the**.NET Framework Components** list with a check mark. Click OK.

   The control appears in the Toolbox with the default "gear" icon.

Place the Control in an Application

In this step, you put two instances of the control on an application form and set their properties.

To put instances of a control on a form

1. Drag two instances of the clickcounter control from the Toolbox. Place them on the form so that they do not overlap.

   If you want to make the form wider, click the form to select it and drag one of the selection handles outward.

2. If you cannot see the Properties window, select Properties from the View menu.

   The ClickAnywhere property is in the Misc. section of the Property Window (if properties are organized by category).

3. Click one instance of the clickcounter control on the form to select it, and then set its ClickAnywhere property to true.

4. Leave the ClickAnywhere property of the other instance of the clickcounter control set to false (the default).

5. Right-click the testapp project in Solution Explorer and select Set As StartUp Project.

6. From the Build menu, select Rebuild Solution.

   You should see that the two projects built without errors.

Run the Application

In this step, you run the application, and click the controls to test them.

To test the application

1. From the Debug menu, select Start Debugging.

   The form appears with the two instances of the control visible.

2. Run the application and click both clickcounter controls:

   • Click the control with ClickAnywhere set to true.

     The number on the labelincrements when you click anywhere on the control.

   • Click the control with ClickAnywhere set to false.

     The number on the label increments only when you click within the visible boundary of the label. The following screenshot shows how the application might look after clicking on it a few times:

1. Close the test application by clicking its Close box in the upper-right corner of the Form1 window.

Next Steps

Previous: Creating a Windows Forms Application By Using the .NET Framework (C++) | Next: Resources for Creating a Game Using DirectX (C++)

See Also

Tasks

Visual C++ Guided Tour

Reference

Windows API

System.Windows.Forms

Concepts

Introducing the Visual Studio IDE (C++)

Other Resources

Creating Windows-Based Applications

Windows Forms Controls

Change History