Adding Controls to Office Documents at Run Time

Note	Required applications
The features in this topic are available only if you have the required applications installed. For more information, see Features Available by Product Combination.	One of these development environments: VSTO 2005 -or- Visual Studio Team System Microsoft Office 2003

When you programmatically add a Windows Forms control, such as a ListBox or CheckBox to your Office solution, the control persists only while the document is open. When you close the document, the dynamically created Windows Forms controls are not persisted with the document. The next time the document is opened, the controls are recreated when the event containing the code is raised.

If you want to recreate the controls without relying on the user to raise the same event first, you can get the position of the underlying Shape or InlineShape of the control using the GetShapeForControl method or the GetInlineShapeForControl method. You can then use the position of the Shape or InlineShape to recreate the control. For more information on recreating controls programmatically, see Word Dynamic Controls Sample.

Host controls that are created at run time, such as a NamedRange, behave differently. When you close the document, any dynamically created host control disconnects its events and data binding functionality. Essentially, it becomes a native Office object. To reconnect the events and data bindings the next time the document is opened, you use the same method that you used to originally create the control, and pass in the same range and name of the original host control.

Note
If you want to recreate a Microsoft.Office.Tools.Word.Bookmark control from an existing Microsoft.Office.Interop.Word.Bookmark, use the AddBookmark method and pass in the existing Microsoft.Office.Interop.Word.Bookmark.

When you programmatically add a control to a document, the control is added to the Controls collection which can be used to iterate through all of the controls in your document, including the controls you added at design time (static controls). You can remove dynamic controls from the collection by passing either the control or the name of the control to the Remove method. You cannot remove static controls at run time. Attempts to remove a static control will throw an exception.

Microsoft Visual Studio 2005 Tools for the Microsoft Office System provides a helper method for each of the common Windows Forms controls that can be hosted on a Word document or Excel worksheet. When you add a control programmatically, you must provide the location to place the control and a name that uniquely identifies the control. Each of the helper methods is overloaded so that you can either pass a range or specific coordinates for the location of the control.

Note
When referencing or casting controls, be sure to use the correct control type. For example, if you are casting an object to a `Button` control in Excel, be sure to specify the type as Microsoft.Office.Tools.Excel.Controls.Button rather than System.Windows.Forms.Button.

You can also programmatically add controls to your Word document or Excel worksheet by using the AddControl method. However, the helper methods are provided to remove the complexity of the AddControl method which should only be used to add custom controls to your document.

Note
Windows Forms controls cannot be programmatically added to protected documents. If you programmatically unprotect the Word document or Excel worksheet in order to add a control, you must write additional code to remove the control's ActiveX wrapper when the document is closed. The control's ActiveX wrapper is not automatically deleted from protected documents.

Helper Methods for Excel

Visual Studio Tools for Office provides a number of helper methods that can be used to programmatically add Windows Forms controls to Excel documents. Each method is overloaded so that you can pass in a Range or the coordinates of a specific location. When you create a control by passing in a Range, the control automatically resizes when cells within the range are resized.

The following is an alphabetic list of helper methods that can be used to programmatically add Windows Forms controls to Excel documents.

Helper Method	Definition
AddButton	Adds a Button control to the specified range.
AddButton	Adds a Button control at the exact position supplied rather than a range. The coordinates are represented in points.
AddLabel	Adds a Label control to the specified range.
AddLabel	Adds a Label control at the exact position supplied rather than a range. The coordinates are represented in points.
AddLinkLabel	Adds a LinkLabel control to the specified range.
AddLinkLabel	Adds a LinkLabel control at the exact position supplied rather than a range. The coordinates are represented in points.
AddTextBox	Adds a TextBox control to the specified range.
AddTextBox	Adds a TextBox control at the exact position supplied rather than a range. The coordinates are represented in points.
AddCheckBox	Adds a CheckBox control to the specified range.
AddCheckBox	Adds a CheckBox control at the exact position supplied rather than a range. The coordinates are represented in points.
AddRadioButton	Adds a RadioButton control to the specified range.
AddRadioButton	Adds a RadioButton control at the exact position supplied rather than a range. The coordinates are represented in points.
AddPictureBox	Adds a PictureBox control to the specified range.
AddPictureBox	Adds a PictureBox control at the exact position supplied rather than a range. The coordinates are represented in points.
AddCheckedListBox	Adds a CheckedListBox control to the specified range.
AddCheckedListBox	Adds a CheckedListBox control at the exact position supplied rather than a range. The coordinates are represented in points.
AddComboBox	Adds a ComboBox control to the specified range.
AddComboBox	Adds a ComboBox control at the exact position supplied rather than a range. The coordinates are represented in points.
AddListView	Adds a ListView control to the specified range, setting the position and size of control.
AddListView	Adds a ListView control at the exact position supplied rather than a range. The coordinates are represented in points.
AddTreeView	Adds a TreeView control to the specified range.
AddTreeView	Adds a TreeView control at the exact position supplied rather than a range. The coordinates are represented in points.
AddDateTimePicker	Adds a DateTimePicker control to the specified range.
AddDateTimePicker	Adds a DateTimePicker control at the exact position supplied rather than a range. The coordinates are represented in points.
AddMonthCalendar	Adds a MonthCalendar control to the specified range.
AddMonthCalendar	Adds a MonthCalendar control at the exact position supplied rather than a range. The coordinates are represented in points.
AddDomainUpDown	Adds a DomainUpDown control to the specified range.
AddDomainUpDown	Adds a DomainUpDown control at the exact position supplied rather than a range. The coordinates are represented in points.
AddNumericUpDown	Adds a NumericUpDown control to the specified range.
AddNumericUpDown	Adds a NumericUpDown control at the exact position supplied rather than a range. The coordinates are represented in points.
AddTrackBar	Adds a TrackBar control to the specified range.
AddTrackBar	Adds a TrackBar control at the exact position supplied rather than a range. The coordinates are represented in points.
AddRichTextBox	Adds a RichTextBox control to the specified range.
AddRichTextBox	Adds a RichTextBox control at the exact position supplied rather than a range. The coordinates are represented in points.
AddDataGridView	Adds a DataGridView control to the specified range.
AddDataGridView	Adds a DataGridView control at the exact position supplied rather than a range. The coordinates are represented in points.
AddHScrollBar	Adds a HScrollBar control to the specified range.
AddHScrollBar	Adds a HScrollBar control at the exact position supplied rather than a range. The coordinates are represented in points.
AddVScrollBar	Adds a VScrollBar control to the specified range.
AddVScrollBar	Adds a VScrollBar control at the exact position supplied rather than a range. The coordinates are represented in points.
AddPropertyGrid	Adds a PropertyGrid control to the specified range.
AddPropertyGrid	Adds a PropertyGrid control at the exact position supplied rather than a range. The coordinates are represented in points.
AddWebBrowser	Adds a WebBrowser control to the specified range.
AddWebBrowser	Adds a WebBrowser control at the exact position supplied rather than a range. The coordinates are represented in points.

Helper Methods for Word

Visual Studio Tools for Office provides a number of helper methods that can be used to programmatically add Windows Forms controls to Word documents. Each method is overloaded so that you can pass in a Range or the coordinates of a specific location. When you create a control by passing in a Range, the control is added as an InlineShape, placed at the start of the range. You cannot change the Top and Left properties of controls that are added in line with text. When you create a control by passing in coordinates, the control is added as a floating Shape, placed at the location specified.

The following is an alphabetic list of helper methods that can be used to programmatically add Windows Forms controls to Word documents.

Helper Method	Definition
AddButton	Adds a Button control at the start of the specified range.
AddButton	Adds a Button control at the exact position supplied rather than a range. The coordinates are represented in points.
AddLabel	Adds a Label control at the start of the specified range.
AddLabel	Adds a Label control at the exact position supplied rather than a range. The coordinates are represented in points.
AddLinkLabel	Adds a LinkLabel control at the start of the specified range.
AddLinkLabel	Adds a LinkLabel control at the exact position supplied rather than a range. The coordinates are represented in points.
AddTextBox	Adds a TextBox control at the start of the specified range.
AddTextBox	Adds a TextBox control at the exact position supplied rather than a range. The coordinates are represented in points.
AddCheckBox	Adds a CheckBox control at the start of the specified range.
AddCheckBox	Adds a CheckBox control at the exact position supplied rather than a range. The coordinates are represented in points.
AddRadioButton	Adds a RadioButton control at the start of the specified range.
AddRadioButton	Adds a RadioButton control at the exact position supplied rather than a range. The coordinates are represented in points.
AddPictureBox	Adds a PictureBox control at the start of the specified range.
AddPictureBox	Adds a PictureBox control at the exact position supplied rather than a range. The coordinates are represented in points.
AddCheckedListBox	Adds a CheckedListBox control at the start of the specified range.
AddCheckedListBox	Adds a CheckedListBox control at the exact position supplied rather than a range. The coordinates are represented in points.
AddComboBox	Adds a ComboBox control at the start of the specified range.
AddComboBox	Adds a ComboBox control at the exact position supplied rather than a range. The coordinates are represented in points.
AddListView	Adds a ListView control to the specified range, setting the position and size of control.
AddListView	Adds a ListView control at the exact position supplied rather than a range. The coordinates are represented in points.
AddTreeView	Adds a TreeView control at the start of the specified range.
AddTreeView	Adds a TreeView control at the exact position supplied rather than a range. The coordinates are represented in points.
AddDateTimePicker	Adds a DateTimePicker control at the start of the specified range.
AddDateTimePicker	Adds a DateTimePicker control at the exact position supplied rather than a range. The coordinates are represented in points.
AddMonthCalendar	Adds a MonthCalendar control at the start of the specified range.
AddMonthCalendar	Adds a MonthCalendar control at the exact position supplied rather than a range. The coordinates are represented in points.
AddDomainUpDown	Adds a DomainUpDown control at the start of the specified range.
AddDomainUpDown	Adds a DomainUpDown control at the exact position supplied rather than a range. The coordinates are represented in points.
AddNumericUpDown	Adds a NumericUpDown control at the start of the specified range.
AddNumericUpDown	Adds a NumericUpDown control at the exact position supplied rather than a range. The coordinates are represented in points.
AddTrackBar	Adds a TrackBar control at the start of the specified range.
AddTrackBar	Adds a TrackBar control at the exact position supplied rather than a range. The coordinates are represented in points.
AddRichTextBox	Adds a RichTextBox control at the start of the specified range.
AddRichTextBox	Adds a RichTextBox control at the exact position supplied rather than a range. The coordinates are represented in points.
AddDataGridView	Adds a DataGridView control at the start of the specified range.
AddDataGridView	Adds a DataGridView control at the exact position supplied rather than a range. The coordinates are represented in points.
AddHScrollBar	Adds a HScrollBar control at the start of the specified range.
AddHScrollBar	Adds a HScrollBar control at the exact position supplied rather than a range. The coordinates are represented in points.
AddVScrollBar	Adds a VScrollBar control at the start of the specified range.
AddVScrollBar	Adds a VScrollBar control at the exact position supplied rather than a range. The coordinates are represented in points.
AddPropertyGrid	Adds a PropertyGrid control at the start of the specified range.
AddPropertyGrid	Adds a PropertyGrid control at the exact position supplied rather than a range. The coordinates are represented in points.
AddWebBrowser	Adds a WebBrowser control at the start of the specified range.
AddWebBrowser	Adds a WebBrowser control at the exact position supplied rather than a range. The coordinates are represented in points.

Custom Controls

If you want to add a control that is not supported by the helper methods, you can use the generic AddControl method to programmatically add the control to the document. You pass the control, a location for the control and a name that uniquely identifies it to the AddControl method. The AddControl method returns an OLEObject in Excel and an OLEControl in Word. For example, the following code demonstrates how to dynamically add a custom user control to range1 of the worksheet.

Visual Basic

Dim customControl As New UserControl1()

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

C#

UserControl1 customControl = new UserControl1();

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

Because you now have two control references, one for the custom user control, and one for the OLEObject, many properties and methods are shared between each control. It is important that you access these methods and properties through the appropriate control.

Properties and methods are members of both controls	Properties and methods are members of the custom control only
Access the methods and properties through the OLEObject or OLEControl.	Access the methods and properties through the custom control.

If you access a shared method or property from the custom control, it will fail without warning or notification. For example, the Top property is a member of the OLEObject as well as the user control. Therefore, you must set the property on the OLEObject control and not on the user control:

Visual Basic

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

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

C#

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

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

Setting the Top property on the user control will not produce valid results. A best practice is to always reference the OLEObject or OLEControl unless the method or property needed is not available; only then should you reference the custom control. The helper methods for adding the most common Windows Forms controls are provided to take care of this complexity for you.

Host controls can also be added and removed at runtime. Visual Studio Tools for Office provides a helper method for each of the common host controls that can be hosted on a Word document or Excel worksheet. When you add a control programmatically, you must provide the location to place the control and a name that uniquely identifies the control.

Helper Methods for Excel

The following is an alphabetic list of helper methods that can be used to programmatically add host controls to Office Excel documents.

Helper Method	Definition
AddChart	Adds a Chart control to the specified range.
AddChart	Adds a Chart control at the exact position supplied rather than a range. The coordinates are represented in points.
AddListObject	Adds a ListObject control to the specified range.
AddNamedRange	Adds a NamedRange control to the specified range.

Helper Methods for Word

The following is the helper method that can be used to programmatically add host controls to Office Word documents.

Helper Method	Definition
AddBookmark	Adds a Bookmark control at the specified range.

Adding Controls to Office Documents at Run Time

Persisting Controls in the Document

Controls Collection

Windows Forms Controls

Helper Methods for Excel

Helper Methods for Word

Custom Controls

Host Controls

Helper Methods for Excel

Helper Methods for Word

See Also

Tasks

Reference

Concepts

Other Resources