Understanding the Word Object Model
Word provides hundreds of objects with which you can interact. These objects are organized in a hierarchy that closely follows the user interface. At the top of the hierarchy is the Application object. This object represents the current instance of Word. The Application object contains the Document, Selection, Bookmark, and Range objects. Each of these objects has many methods and properties that you can access to manipulate and interact with it.
The following illustration shows one view of these objects in the hierarchy of the Word object model.
Word Object Model Abstract
.gif)
At first glance, there appears to be a lot of overlap. For example, the Document and Selection objects are both members of the Application object, but the Document object is also a member of the Selection object. Both the Document and Selection objects contain Bookmark and Range objects. The overlap exists because there are multiple ways you can access the same type of object. For example, you apply formatting to a Range object; but you may want to access the range of the current selection, of a particular paragraph, of a section, or of the entire document.
The following sections briefly describe the top-level objects and how they interact with each other. These objects include the following five:
Application object
Document object
Selection object
Range object
Bookmark object
Visual Studio Tools for Office also extends many of these objects into host items and host controls. These extended objects can be used in document-level projects, or, starting in Visual Studio 2008 Service Pack 1 (SP1), in application-level projects for Word 2007. Host items and host controls have additional functionality such as data-binding capabilities and events. For more information about host controls, see Extended Objects in Visual Studio Tools for Office Projects.
Application Object
The Application object represents the Word application, and is the parent of all of the other objects. Its members usually apply to Word as a whole. You can use its properties and methods to control the Word environment.
In application-level add-in projects, you can access the Application object by using the Application field of the ThisAddIn class. For more information, see Programming Application-Level Add-Ins.
In document-level projects, you can access the Application object by using the Application property of the ThisDocument class.
Document Object
The Microsoft.Office.Interop.Word..::.Document object is central to programming Word. It represents a document and all of its contents. When you open a document or create a new document, you create a new Microsoft.Office.Interop.Word..::.Document object, which is added to the Documents collection of the Application object. The document that has the focus is called the active document. It is represented by the ActiveDocument property of the Application object.
Visual Studio Tools for Office extends the Microsoft.Office.Interop.Word..::.Document object by providing the Microsoft.Office.Tools.Word..::.Document class. This class is a host item that gives you access to all members of the native Microsoft.Office.Interop.Word..::.Document class, and adds additional events and the ability to add managed controls and smart tags. For more information, see Host Items and Host Controls Overview.
When you create a document-level project, Visual Studio Tools for Office generates a class named ThisDocument, which derives from the Microsoft.Office.Tools.Word..::.Document class. You can access members of the Microsoft.Office.Tools.Word..::.Document class by using the Me or this keywords from code in the ThisDocument class, or by using Globals.ThisDocument from code outside the ThisDocument class. For example, to select the first paragraph in the document, use the following code.
Me.Paragraphs(1).Range.Select()
this.Paragraphs[1].Range.Select();
Starting in SP1, you can generate Microsoft.Office.Tools.Word..::.Document host items at run time by using application-level add-ins for Word 2007. You can use the generated host item to add controls and smart tags to the associated document. For more information, see Extending Word Documents and Excel Workbooks in Application-Level Add-ins at Run Time.
Selection Object
The Selection object represents the area that is currently selected. When you perform an operation in the Word user interface, such as bolding text, you select, or highlight, the text and then apply the formatting. The Selection object is always present in a document. If nothing is selected, then it represents the insertion point. In addition, a selection can encompass multiple blocks of text that are not contiguous.
Range Object
The Range object represents a contiguous area in a document, and is defined by a starting character position and an ending character position. You are not limited to a single Range object. You can define multiple Range objects in the same document. A Range object has the following characteristics:
It can consist of the insertion point alone, a range of text, or the entire document.
It includes non-printing characters such as spaces, tab characters, and paragraph marks.
It can be the area represented by the current selection, or it can represent an area different from the current selection.
It is not visible in a document, unlike a selection, which is always visible.
It is not saved with a document and exists only while the code is running.
When you insert text at the end of a range, Word automatically expands the range to include the inserted text.
Content Control Objects
A Microsoft.Office.Interop.Word.ContentControl provides a way for you to control the input and presentation of text and other types of content in Word 2007 documents. A Microsoft.Office.Interop.Word.ContentControl can display several different types of UI that are optimized for use in Word documents, such as a rich text control, a date picker, or a combo box. You can also use a Microsoft.Office.Interop.Word.ContentControl to prevent users from editing sections of the document or template.
Visual Studio Tools for Office extends the Microsoft.Office.Interop.Word.ContentControl object into several different host controls. Whereas the Microsoft.Office.Interop.Word.ContentControl object can display any of the different types of UI that are available for content controls, Visual Studio Tools for Office provides a different class for each type of UI. For example, you can use a RichTextContentControl to create a rich text control, or you can use a DatePickerContentControl to create a date picker. These host controls behave like the native Microsoft.Office.Interop.Word.ContentControl, but they have additional events and data-binding capabilities.
For more information, see Content Controls.
Bookmark Object
Using the Word Object Model Documentation
For information about the classes you can use in the Word object model, see the following sets of documentation:
The first link provides information about the classes and interfaces in the primary interop assembly for Word. The other links provide information about the Word object model as it is exposed to Visual Basic for Applications (VBA) code. Each set of documentation has advantages and disadvantages for developers who are using Visual Studio Tools for Office.
Primary Interop Assembly Reference
This documentation describes all of the types in the Word primary interop assembly that you can use in Visual Studio Tools for Office projects. However, this documentation has the following disadvantages:
It describes only the types in the primary interop assembly for Word 2003. For descriptions of new types and members in the primary interop assembly for Word 2007, you must refer to the VBA reference for Word 2007.
It does not provide any code examples at this time.
VBA Reference
All of the objects and members in the VBA reference correspond to classes and members in the primary interop assembly that you use in Visual Studio Tools for Office projects. For example, the Document object in the Word VBA documentation corresponds to the Microsoft.Office.Interop.Word..::.Document class in the primary interop assembly.
The VBA reference has the following advantages:
The VBA reference has the following disadvantages:
Additional Types in Primary Interop Assemblies