Programmatic Limitations of Host Items and Host Controls
The features in this topic are available only if you have the required applications installed.
For more information, see.
For each host item and host control provided in Microsoft Visual Studio 2005 Tools for the Microsoft Office System, there is an underlying native Microsoft Office Word or Microsoft Office Excel object. Many of the methods and properties of Office objects (host items, host controls, and native Office objects) get or set a value in the type of the underlying Office object, rather than the host item or host control. You can access the underlying object by using the
InnerObject property of the host item or host control. However, there is no way to cast a native Office object to its corresponding host item or host control.
Programmatically Creating Host Items and Host Controls
Host items are not created automatically when you programmatically create a new document or worksheet at run time. For example, if you add a Word document at run time, it will be of the typerather than . Similarly, when you add a worksheet programmatically at run time using the method, you get a worksheet of the type not . Host controls can be created programmatically, but they can only be added to host items. If you programmatically create a document or worksheet, the item is not a host item, and you will not be able to add host controls to the programmatically created document or worksheet. You can create host items only at design time.
You can programmatically add host controls to a host item by using one of the Add<Control> methods. For example, to add acontrol to your document, use the method. Only the following host controls can be created programmatically:
You cannot add managed controls to a native Word Microsoft.Office.Interop.Word.Document or Excel Microsoft.Office.Interop.Excel.Worksheet. Host controls and Windows Forms controls can be added only to a host item. For more information about programmatically adding controls to documents, see.
Most methods and properties of host items return the underlying native Office object upon which the host item is based. For example, the
Parent property of a host control in Excel returns a Microsoft.Office.Interop.Excel.Worksheet object rather than a Microsoft.Office.Tools.Excel.Worksheet host item, and the
Parent property of a host control in Word returns a Microsoft.Office.Interop.Word.Document object rather than a Microsoft.Office.Tools.Word.Document host item. An is thrown when you try to cast a native Office object into a host item or host control.
Visual Studio Tools for Office does not provide individual collections for each type of host control. For example, it is not possible to enumerate each Microsoft.Office.Tools.Word.Bookmark control in the document using thecollection. All of the bookmarks in the document are included; the enumeration does not distinguish between a Microsoft.Office.Tools.Word.Bookmark control and a .
You can use theto iterate through all controls (both host controls and Windows Forms controls) on the document, and then look for items that match the type of the host control you are interested in. The following example determines if a control is of the type Microsoft.Office.Tools.Word.Bookmark:
Passing Host Controls to Methods and Properties
In Word, you cannot pass a host control to a method or property that requires a native Word object as a parameter. You must use the
InnerObject property of the host control to return the underlying native Word object. For example, you can pass a Microsoft.Office.Interop.Word.Bookmark object to a method by passing the property of the Microsoft.Office.Tools.Word.Bookmark host control to the method.
In Excel, there are two cases in which you must use the
InnerObject property of the host control:
When the method or property expects the underlying Excel object.
When theattribute is set to false and the method or property expects an instead of the underlying Excel object. For more information, see .
The following example creates a Microsoft.Office.Tools.Excel.NamedRange control and passes it to themethod. The code uses the property of the named range to return the underlying Office that is required by the AutoFill method.
this.Range["A1", missing].Value2 = "Monday"; this.Range["A2", missing].Value2 = "Tuesday"; Microsoft.Office.Tools.Excel.NamedRange dayRange = this.Controls.AddNamedRange(this.Range["A1", "A7"], "dayRange"); this.Range["A1", "A2"].AutoFill(dayRange.InnerObject, Excel.XlAutoFillType.xlFillDays);