The Microsoft.Office.Tools.Excel..::.ControlCollection and Microsoft.Office.Tools.Word..::.ControlCollection classes include helper methods you can use to add host controls and common Windows Forms controls to documents and worksheets. Each method name has the format Add<control class>, where control class is the class name of the control that you want to add. For example, to add a NamedRange control to your document, use the AddNamedRange method. For a complete list of helper methods, see Helper Methods for Host Controls and Helper Methods for Windows Forms Controls.

The following code example adds a NamedRange to Sheet1 in a document-level project for Excel.

Dim range1 As Excel.Range = Globals.Sheet1.Range("A1", "D5")
Dim namedRange1 As Microsoft.Office.Tools.Excel.NamedRange = _
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource")

Excel.Range range1 = Globals.Sheet1.Range["A1", "D5"];
Microsoft.Office.Tools.Excel.NamedRange namedRange1 =
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource");

You can use the Controls property of a Microsoft.Office.Tools.Excel..::.Worksheet or Microsoft.Office.Tools.Word..::.Document to iterate through all the controls in your document, including the controls you added at design time. Controls that you add at design time are also called static controls.

You can remove dynamic controls by calling the Delete method of the control, or by calling the Remove method of each Controls collection. The following code example uses the Remove method to remove a NamedRange from Sheet1 in a document-level project for Excel.

Globals.Sheet1.Controls.Remove("ChartSource")

Globals.Sheet1.Controls.Remove("ChartSource");

You cannot remove static controls at run time. If you try to use the Delete or Remove method to remove a static control, a CannotRemoveControlException will be thrown.

Note:

Do not programmatically remove controls in the Shutdown event handler of the document. The UI elements of the document are no longer available when the Shutdown event is raised. If you want to remove controls before the document closes, add your code to the event handler for another event, such as Document..::.BeforeClose or Document..::.BeforeSave for Word, or Workbook..::.BeforeClose, or Workbook..::.BeforeSave for Excel.

If you want to add a System.Windows.Forms..::.Control that is not supported by the available helper methods (for example, a custom user control), use the following methods:

• For Excel, use one of the AddControl()()() methods of the Microsoft.Office.Tools.Excel..::.ControlCollection class.

• For Word, use one of the AddControl()()() methods of the Microsoft.Office.Tools.Word..::.ControlCollection class.

To add the control, pass the System.Windows.Forms..::.Control, a location for the control, and a name that uniquely identifies the control to the AddControl method. For Excel, this method returns an OLEObject. For Word, this method returns an OLEControl. These objects define how the control interacts with the worksheet or document.

The following code example demonstrates how to use the AddControl(Control, Range, String) method to dynamically add a custom user control to a worksheet. In this example, the user control is named UserControl1, and the Range is named range1. This example assumes that it is being run from one of the Sheetn classes in a document-level project for Excel.

Dim customControl As New UserControl1()

Dim dynamicControl As Microsoft.Office.Tools.Excel.OLEObject = _
    Me.Controls.AddControl(customControl, range1, "dynamic")

UserControl1 customControl = new UserControl1();

Microsoft.Office.Tools.Excel.OLEObject dynamicControl =
    this.Controls.AddControl(customControl, range1, "dynamic");

After using one of the AddControl methods to add a control to a worksheet or document, you now have two different control objects:

• The System.Windows.Forms..::.Control that represents the custom control.

• The OLEObject or OLEControl that represents the control after it was added to the worksheet or document.

Many properties and methods are shared between these controls. It is important that you access these methods and properties through the appropriate control:

• To access properties and methods that belong only to the custom control, use the System.Windows.Forms..::.Control.

• To access properties and methods that are shared by the controls, use the OLEObject or OLEControl.

If you access a shared method or property from the System.Windows.Forms..::.Control, it might fail without warning or notification, or it can produce invalid results. Always use methods or properties of the OLEObject or OLEControl unless the method or property needed is not available; only then should you reference the System.Windows.Forms..::.Control.

For example, both the OLEObject class and the System.Windows.Forms..::.Control class have a Top property. To get or set the distance between the top of the control and the top of the document, use the Top property of the OLEObject, not the Top property of the System.Windows.Forms..::.Control.

' Property is set in relation to the document.
dynamicControl.Top = 100

' Property is set in relation to the container control.
customControl.Top = 100

// Property is set in relation to the document.
dynamicControl.Top = 100;

// Property is set in relation to the container control.
customControl.Top = 100;