Word Object Model Overview

Applies to
The information in this topic applies only to the specified Visual Studio Tools for Office projects and versions of Microsoft Office. Project type Document-level projects Application-level projects Microsoft Office version Word 2003 Word 2007 For more information, see Features Available by Application and Project Type.

To develop Visual Studio Tools for Office solutions for Microsoft Office Word, you can interact with the Word object model. This object model consists of classes and interfaces that are provided in the primary interop assembly for Word, and are defined in the Microsoft.Office.Interop.Word namespace.

This topic describes the following aspects of using the Word object model:

• Understanding the Word object model

• Extended objects in Visual Studio Tools for Office Projects

• Using the Word Object Model Documentation

For information about using the Word object model to perform tasks in Visual Studio Tools for Office projects, see the following topics:

• Working with Documents

• Working with Text in Documents

• Working with Tables

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

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 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 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 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 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

The Bookmark object represents a contiguous area in a document, with both a starting position and an ending position. You can use bookmarks to mark a location in a document, or as a container for text in a document. A Bookmark object can consist of the insertion point, or be as large as the entire document. A Bookmark has the following characteristics that set it apart from the Range object:

• You can name the bookmark at design time.

• Bookmark objects are saved with the document, and thus are not deleted when the code stops running or your document is closed.

• Bookmarks can be hidden or made visible by setting the ShowBookmarks property of the View object to false or true.

Visual Studio Tools for Office extends the Bookmark object into a host control. The Microsoft.Office.Tools.Word.Bookmark control behaves like a native Bookmark, but has additional events and data-binding capabilities. You can bind data to a bookmark control on a document in the same way that you bind data to a text box control on a Windows Form.

For more information, see Bookmark Control.

Extended Objects in Visual Studio Tools for Office Projects

It is important to understand the differences between the native objects provided by the Word object model and the extended objects (host items and host controls) provided by Visual Studio Tools for Office. Both types of objects are available to document-level projects and application-level projects for Word 2007. For more information, see Host Items and Host Controls Overview.

The differences are in the following four areas:

• Design time. When you add any of the extended Word controls to a document-level customization at design time, they are automatically created as host controls. For example, if you add a bookmark to a document in the designer, code is automatically generated to extend the bookmark into a Microsoft.Office.Tools.Word.Bookmark control.

• Run time. Host items are not automatically created at run time. If you add documents at run time by using the Add(Object, Object, Object, Object) method, they are Document objects and do not have the additional capabilities that Microsoft.Office.Tools.Word.Document host items provide. You can programmatically add host controls to documents by using the helper methods provided by Visual Studio Tools for Office. For more information, see Programmatic Limitations of Host Items and Host Controls.

  Note

  Starting in SP1, you can create Microsoft.Office.Tools.Word.Document host items at run time by using application-level add-ins for Word 2007. For more information, see Extending Word Documents and Excel Workbooks in Application-Level Add-ins at Run Time.

• New features. Host items and host controls have features that are not available to the native objects. Host items can act as a container for managed controls, and they have additional events. Host controls can be bound to data and have additional events.

• Types. The native Word objects use the types defined in the Microsoft.Office.Interop.Word namespace of the primary interop assembly for Word, whereas host items and host controls use the types defined in the Microsoft.Office.Tools.Word namespace of the Visual Studio Tools for Office runtime.

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:

• Microsoft Office Word Primary Interop Reference

• Welcome to the Microsoft Office Word 2007 Developer Reference

• Welcome to the Microsoft Office Word 2003 VBA Language Reference

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 Document class in the primary interop assembly.

The VBA reference has the following advantages:

• It documents the object models of both Word 2007 and Word 2003.

• It provides code examples for most members.

The VBA reference has the following disadvantages:

• It provides syntax and code examples for VBA only. To use the code examples in a Visual Studio Tools for Office project, you must translate the VBA code to Visual Basic or Visual C#.

Additional Types in Primary Interop Assemblies

The primary interop assemblies contain many types that are not available to VBA. These additional types help translate objects in the COM-based object model of Word to managed code, are not intended to be used directly in your code.

For more information, see Overview of Classes and Interfaces in the Office Primary Interop Assemblies.

See Also

Concepts

Working with Documents

Working with Text in Documents

Working with Tables

Excel Object Model Overview

Host Items and Host Controls Overview

Programmatic Limitations of Host Items and Host Controls

The Variable missing and Optional Parameters in Office Solutions

Reference

Office Primary Interop Assemblies

Other Resources

Word Host Controls

Change History

Date	History	Reason
July 2008	Added information about creating Document host items in application-level add-ins.	SP1 feature change.