Document Host Item
Applies to |
|---|
The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office. Document-level projects
Application-level projects
For more information, see Features Available by Application and Project Type. |
The Document host item represents a Word document that exposes events and acts as a container for host controls and Windows Forms controls. The Document host item also provides all of the same properties, methods, and events as the Document class in the primary interop assembly for Word.
In document-level projects, there is a Document host item that represents the document in your project. Starting in Visual Studio 2008 Service Pack 1 (SP1), you can also generate Document host items at run time by using application-level add-ins for Word 2007.
Understanding the Document Host Item in Document-Level Projects
To programmatically access the document in your project, use the ThisDocument class. When you create a document-level project, Visual Studio Tools for Office generates the ThisDocument class to serve as the communication link between Word and your customization code. The ThisDocument class derives from the Document host item class. Visual Studio Tools for Office automatically instantiates the ThisDocument class for you when the document is opened at run time. You should not try to instantiate the Document class directly in your code.
The ThisDocument class gives you access to members of the Document host item to perform basic tasks in your customization, such as running code when the document is opened or closed. You can also use the class to add controls and smart tags to the document. By combining different sets of controls and writing code, you can bind the controls to data, collect information from the user, and respond to user actions. For more information, see Programming Document-Level Customizations.
The ThisDocument class provides a location in which you can start writing code in your project. Because the class provides all of the same properties, methods, and events as the Document class in the primary interop assembly for Word, you can also use ThisDocument to access the object model of Word. For more information, see Word Object Model Overview.
Limitations of the Document Host Item
A document-level project can contain only one Document host item. You cannot add new Document host items to your project at design time, and you cannot programmatically create new Document host items at run time from a document-level customization.
If you create a new Word document at run time, it will be of the type Document. Because it is not a host item, it cannot contain any host controls or Windows Forms controls. For more information about creating documents at run time, see How to: Create New Documents.
Understanding Document Host Items in Application-Level Projects
Starting in SP1, you can generate a Document host item at run time for any document that is open in Word. You can use the Document host item to add controls and smart tags to the associated document.
To generate a Document host item, use the GetVstoObject method of any Document object. For more information, see Extending Word Documents and Excel Workbooks in Application-Level Add-ins at Run Time.
See Also
Concepts
Host Items and Host Controls Overview
Programmatic Limitations of Host Items and Host Controls
Extending Word Documents and Excel Workbooks in Application-Level Add-ins at Run Time
Other Resources
Change History
Date |
History |
Reason |
|---|---|---|
July 2008 |
Added information about using Document host items in application-level projects. |
SP1 feature change. |