ControlCollection.AddControl Method (Control, Range, String)

 

Adds the specified Control to the ControlCollection at the specified range.

Namespace:   Microsoft.Office.Tools.Excel
Assembly:  Microsoft.Office.Tools.Excel (in Microsoft.Office.Tools.Excel.dll)

ControlSite AddControl(
	Control control,
	Range range,
	string name
)

Parameters

control
Type: System.Windows.Forms.Control

The control to be added to the ControlCollection instance.

range
Type: Microsoft.Office.Interop.Excel.Range

A Range that provides the bounds for the control.

name
Type: System.String

The name of the control that can be used to index the control in the ControlCollection instance.

Return Value

Type: Microsoft.Office.Tools.Excel.ControlSite

An object that represents the control that contains the specified control on the worksheet.

Exception Condition
ArgumentNullException

The control, name or range argument is null, or the name argument has zero length.

ControlNameAlreadyExistsException

A control with the same name is already in the ControlCollection instance.

InvalidRangeException

The range that was specified is not valid. Multi-area ranges cannot be used. The range should be on the same worksheet as the ControlCollection instance.

This method can be used to add any control to the ControlCollection at run time. For more information, see Adding Controls to Office Documents at Run Time.

The following code example adds two custom user controls to the worksheet using the AddControl method. The first control is added to a range of cells. The second control is added to a specific location. The code changes the Top property of the first custom user control, which only moves the control relative to the ControlSite that contains the control on the worksheet. The code then sets the Top property of the ControlSite returned by the second user control to illustrate the correct way to set the Top property of the control.

private void ExcelRangeAddControl()
{

    UserControl1 customUserControl = new UserControl1();
    UserControl2 customUserControl2 = new UserControl2();

    Microsoft.Office.Tools.Excel.ControlSite dynamicControl =
        this.Controls.AddControl(customUserControl,
        0, 0, 150, 150, "dynamicControl");

    Microsoft.Office.Tools.Excel.ControlSite dynamicControl2 =
        this.Controls.AddControl(customUserControl2, 200, 0,
        150, 150, "dynamicControl2");

    customUserControl.BackColor = Color.Blue;
    customUserControl2.BackColor = Color.Green;

    customUserControl.Top = 100;
    dynamicControl2.Top = 100;
}
Return to top
Show: