Word Object Model Overview

Article
11/06/2012

When you develop Word solutions in Visual Studio, you 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.

Applies to: The information in this topic applies to document-level projects and application-level projects for Word 2013 and Word 2010. For more information, see Features Available by Office Application and Project Type.

This topic provides a brief overview of the Word object model. For resources where you can learn more about the entire Word object model, see Using the Word Object Model Documentation.

For information about using the Word object model to perform specific tasks, see the following topics:

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 the object.

The following illustration shows one view of these objects in the hierarchy of the Word object model.

Word Object Model Abstract

Word Object Model graphic

At first glance, objects appear to 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

In addition to the Word object model, Office projects in Visual Studio provide host items and host controls that extend some objects in the Word object model. Host items and host controls behave like the Word objects they extend, but they also have additional functionality such as data-binding capabilities and extra events. For more information, see Automating Word by Using Extended Objects and Host Items and Host Controls Overview.

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.

The Office development tools in Visual Studio extend the Microsoft.Office.Interop.Word.Document object by providing the Microsoft.Office.Tools.Word.Document type. This type is a host item that gives you access to all features of a Microsoft.Office.Interop.Word.Document object, and adds additional events and the ability to add managed controls.

When you create a document-level project, you can access Microsoft.Office.Tools.Word.Document members by using the generated ThisDocument class in your project. You can access members of the Microsoft.Office.Tools.Word.Document host item 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 more information, see Programming Document-Level Customizations. For example, to select the first paragraph in the document, use the following code.

Me.Paragraphs(1).Range.Select()

this.Paragraphs[1].Range.Select();

In application-level projects, you can generate Microsoft.Office.Tools.Word.Document host items at run time. You can use the generated host item to add controls 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 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 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 provides a different type for each content control. For example, you can use a Microsoft.Office.Tools.Word.RichTextContentControl to create a rich text control, or you can use a Microsoft.Office.Tools.Word.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 Microsoft.Office.Interop.Word.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 Microsoft.Office.Interop.Word.Bookmark object can consist of the insertion point, or be as large as the entire document. A Microsoft.Office.Interop.Word.Bookmark has the following characteristics that set it apart from the Range object:

You can name the bookmark at design time.
Microsoft.Office.Interop.Word.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 extends the Microsoft.Office.Interop.Word.Bookmark object by providing the Microsoft.Office.Tools.Word.Bookmark host control. The Microsoft.Office.Tools.Word.Bookmark host control behaves like a native Microsoft.Office.Interop.Word.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.

Using the Word Object Model Documentation

For complete information about the Word object model, you can refer to the Word primary interop assembly (PIA) reference and the Visual Basic for Applications (VBA) object model reference.

Primary Interop Assembly Reference

The Word PIA reference documentation describes the types in the primary interop assembly for Word. This documentation is available from the following location: Word 2010 Primary Interop Assembly Reference.

For more information about the design of the Word PIA, such as the differences between classes and interfaces in the PIA and how events in the PIA are implemented, see Overview of Classes and Interfaces in the Office Primary Interop Assemblies.

VBA Object Model Reference

The VBA object model reference documents the Word object model as it is exposed to VBA code. For more information, see Word 2010 Object Model Reference.

All of the objects and members in the VBA object model reference correspond to types and members in the Word PIA. For example, the Document object in the VBA object model reference corresponds to the Microsoft.Office.Interop.Word.Document object in the Word PIA. Although the VBA object model reference provides code examples for most properties, methods, and events, you must translate the VBA code in this reference to Visual Basic or Visual C# if you want to use them in a Word project that you create by using Visual Studio.