Building Word 2007 Document Templates Using Content Controls

Office 2007

Erika Ehrli, Lisa Wollin, Brian Jones, Microsoft Corporation Applies to: 2007 Microsoft Office System, Microsoft Office Word 2007

Content controls are bounded and potentially labeled regions in a document that serve as containers for specific types of content. Individual content controls can contain content such as dates, lists, or paragraphs of formatted text. They enable you to create rich, structured blocks of content. Content controls enable you to create templates that insert well-defined blocks into your documents. Content controls also build on the custom XML support introduced in Microsoft Office Word 2003. Whether you want to add or delete content controls or access and manipulate existing content controls, you can do it with code. Adding a Content Control Use the Add method of the ContentControls collection to add a content control to a document. The following example adds a date picker to the active document and sets the date value to the current date. VB Copy

Sub AddDatePicker() Dim objCC As ContentControl Dim objDate As Date Set objCC = ActiveDocument.ContentControls _ .Add(wdContentControlDate) objDate = Date objCC.Range.Text = objDate End Sub
You can use the same basic construction to add any of the different types of content controls to a document. Adding a Title to a Content Control Use the Title property to add a title to a content control. This is text that users see, and it can help them to know what type of data to enter into the content control. The following example adds a new plain-text content control to the active document and sets the title, or display text, for the control. VB Copy

Sub SetTitleForContentControl() Dim objCC As ContentControl Set objCC = ActiveDocument.ContentControls _ .Add(wdContentControlText) objCC.Title = "Please enter your name" End Sub
Modifying Placeholder Text for a Content Control Placeholder text is temporary text. It can be a simple one-word or two-word description (similar to the title) or it can be a more thorough description (such as numbered steps). The way that you modify placeholder text is the same regardless of the type of content control or the expected contents of the content control. The following example adds a drop-down list to the active document, sets the placeholder text for the control, and then fills the list with the names of several animals. VB Copy

Sub SetPlaceholderText() Dim objCC As ContentControl Set objCC = Selection.ContentControls _ .Add(wdContentControlComboBo x) objCC.Title = "Favorite Animal" objCC.SetPlaceholderText _ Text:="Please select your favorite animal" 'List entries objCC.DropdownListEntries.Add "Cat" objCC.DropdownListEntries.Add "Dog" objCC.DropdownListEntries.Add "Horse" objCC.DropdownListEntries.Add "Monkey" objCC.DropdownListEntries.Add "Snake" objCC.DropdownListEntries.Add "Other" End Sub

Content controls enable you to create templates that insert well-defined blocks into your documents. Content controls enable you to:

Specify structured regions in a template. Each structured region has its own unique ID so that you can read from and write to it. Examples of types of structured regions (or content controls) are combo boxes, pictures, text blocks, and calendars.

Determine the behavior of content controls. Each content control takes up a portion of a document and, as the template author, you can specify what each region does. For example, if you want a region

of your template to be a calendar, you insert a calendar content control in that area of the document, which automatically determines what that block of content does. Similarly, if you want a section of a template to display an image, create a picture content control in that area. In this way, you can build a template with predefined block types.

Restrict the content of content controls. You can restrict the content of each content control, so that it cannot be deleted or edited. This is useful if, for example, you have copyright information in a template that the user should be able to read but not edit. You can also lock a template's content so that a user does not accidentally delete portions of it. This makes templates more robust than in previous versions.

Map the contents of a content control to data in a custom XML part that is stored with the document. For example, if you insert a document parts content control that contains a table of stock prices, you can map the table cells to nodes in an XML file that contain the current stock prices. When the prices change, an add-in can programmatically update the attached XML file, which is bound to each cell, and the new, updated prices automatically appear in the table.

The easiest way to create a content control is through the user interface (UI) (although you can also create them programmatically). To create a content control through the UI, select the text that you want to turn into a content control and then choose the content control type you want from the content controls section of the Developer ribbon. This creates a content control around the selected text. Types of Content Controls There are seven different types of content controls that you can add to a document, each of which is represented in a new enumeration called WdContentControlType.

Table 1. Content controls in WdContentControlType

ControlDefinition CalendarA date-time picker. Building BlockEnables the user to choose from specified building blocks. Drop-Down ListA drop-down list. Combo BoxA combo box. PictureA picture. Rich TextA block of rich text. Plain TextA block of plain text.

Building Blocks Part I

by

Word Team

on November 21 A cool new feature we have added in Word 2007 is the ability to reuse content easily in order to help you put together great looking documents. We call this feature building blocks. Building blocks are essentially parts of a document that can be reused. For example, a company logo with a textual slogan can be stored as a reusable cover page. Word 2007 provides a collection of common building blocks presented in visual galleries out of the box. All building block galleries use a rich thumbnail image to preview content before inserting it, like many other features in Office. But each gallery is also a feature in its own right, for example, cover pages will insert at the beginning of the document as expected, while headers go in the document header area and textboxes are inserted in the page the cursor is in. Here is a screenshot of the Cover Page gallery:

Different Types of Building Blocks Insert Tab:

Cover pages Headers Footers Page numbers Text boxes (pull quotes and sidebars) Quick parts (custom user blocks)

Equations

Reference Tab:

Table of Contents Bibliography

Page Layout Tab:

Watermark

Header and Footer Contextual Tab:

Repeats the header, footer, page number, and quick parts galleries for convenience

There are also a number of hidden galleries not shown by default, which can be used by template authors and solutions developers creating a custom user interface. I will cover that in more detail in a later post. Tomorrow, I will talk about inserting and swapping out building blocks in a document. Let me know if you have any specific questions or comments that you would like me to address here or in future posts on building blocks.

Zeyad Rajabi

Content Controls
Visual Studio 2010 Other Versions

Content controls provide a way for you to design documents and templates that have these features:

A user interface (UI) that has controlled input like a form. Restrictions that prevent users from editing protected sections of the document or template. For more information, see Protecting Parts of Documents by Using Content Controls. Data binding to a data source. For more information, see Binding Data to Content Controls.

Applies to: The information in this topic applies to document-level projects and application-level projects for Word 2007 and Word 2010. For more information, see Features Available by Office Application and Project Type. For a related video demonstration, see Binding Data to Word 2007 Content Controls Using Visual Studio Tools for the Office System (3.0).

Overview of Content Controls

Content controls provide a UI that is optimized for both user input and print. When you add a content control to a document, the control is identified by a border, a title, and temporary text that can provide instructions to the user. The border and the title of the control do not appear in printed versions of the document. For example, if you want the user to enter a date in a section of your document, you can add a date picker content control to the document. When users click the control, the standard date picker UI appears. You can also set properties of the control to set the regional calendar that is displayed and to specify the date format. After the user chooses a date, the UI of the control is hidden, and only the date appears if the user prints the document. Content controls also help you do the following:

Prevent users from editing or deleting parts of a document. This is useful if you have information in a document or template that users should be able to read but not edit, or if you want users to be able to edit content controls but not delete them. Bind parts of a document or template to data. You can bind content controls to database fields, managed objects in the .NET Framework, XML elements that are stored in the document, and other data sources.

In document-level projects, you can add content controls to your document at design time or at run time. In application-level projects, you can add content controls to any open document at run time. For more information, see How to: Add Content Controls to Word Documents.

Note
You can use content controls only in documents that are saved in the Open XML Format. You cannot use content controls in documents that are saved in the Word 97-2003 document (.doc) format.

Types of Content Controls

There are nine different types of content controls that you can add to documents. Most of the content controls have a corresponding type in the Microsoft.Office.Tools.Word namespace. You can also use a generic ContentControl, which can represent any of the available content controls. For a walkthrough that demonstrates how to use each of the available content controls, see Walkthrough: Creating a Template By Using Content Controls.

Building Block Gallery

A building block gallery enables users to select from a list of document building blocks to insert into a document. A document building block is a piece of content that has been created to be used multiple times, such as a common cover page, a formatted table, or a header. For more information, see the BuildingBlockGalleryContentControl type. For more information about building blocks, see What's New for Developers in Word 2007.

Check Box
A check box provides a UI that represents a binary state: selected or cleared. This type of content control is available only in Word 2010. Unlike the other types of content controls, the Visual Studio Tools for Office runtime does not provide a specific type that represents a check box content control. In other words, there is no CheckBoxContentControl type. However, you can still create a check box content control by adding a generic ContentControl to a document programmatically. For more information, see Check Box Content Controls in Word 2010 Projects.

Combo Box
A combo box displays a list of items that users can select. Unlike a drop-down list, the combo box enables users to add their own items. For more information, see the ComboBoxContentControl type.

Date Picker
A date picker provides a calendar UI for selecting a date. The calendar appears when the end user clicks the drop-down arrow in the control. You can use regional calendars and different date formats. For more information, see the DatePickerContentControl type.

Drop-Down List

A drop-down list displays a list of items that users can select. Unlike a combo box, the drop-down list does not let users add or edit items. For more information, see the DropDownListContentControl type.

Group
A group control defines a protected region of a document that users cannot edit or delete. A group control can contain any document items, such as text, tables, graphics, and other content controls. For more information, see the GroupContentControl type.

Picture
A picture control displays an image. You can specify the image at design time or run time, or users can click this control to select an image to insert in the document. For more information, see the PictureContentControl type.

Rich Text
A rich text control contains text or other items, such as tables, pictures, or other content controls. For more information, see the RichTextContentControl type.

Plain Text
A plain text control contains text. A plain text control cannot contain other items, such as tables, pictures, or other content controls. In addition, all of the text in a plain text control has the same formatting. For example, if you italicize one word of a sentence that is in a plain text control, all the text inside the control is italicized. For more information, see the PlainTextContentControl type.

Generic Content Control

A generic content control is a ContentControl object that can represent any of the available types of content controls. You can change a ContentControl object to behave like a different type of content control by using the Type property. For example, if you create a ContentControl object that represents a plain text control, you can change it at run time so that it behaves like a combo box. You can create ContentControl objects only at run time, not at design time. For more information, see How to: Add Content Controls to Word Documents.

Common Features of Content Controls

Most content controls share a set of members that you can use to perform common tasks. The following table describes some of the tasks that you can perform by using these members.

For this task:

Get or set the text that is displayed in the control.

Do this:
Use the Text property. Note The PictureContentControl and

ContentControl types do not have this property.

Get or set the temporary text that is displayed in the control until a user edits the control, the control is populated with data from a data source, or the control's contents are deleted.

Use the PlaceholderText property. Note The PictureContentControl type does not have this property.

Get or set the title that is displayed in the border of the content control when the user clicks it.

Use the Title property.

Remove the control from the document automatically after the user Use the Temporary property. edits the control. (The text in the control remains in the document.)

Run code when the user clicks in the content control, or when the cursor is moved into the content control programmatically.

Handle the Entering event of the control.

Run code when the user clicks outside the content control, or when the cursor is moved outside the content control programmatically.

Handle the Exiting event of the control.

Run code after the content control is added to the document as a result of a redo or undo operation.

Handle the Added event of the control.

Run code just before the content control is deleted from the document.

Handle the Deleting event of the control.

Protecting Parts of Documents By Using Content Controls

When you protect a part of a document, you prevent users from changing or deleting the content in that part of the document. There are several ways you can protect parts of a document by using content controls. If the area you want to protect is inside a content control, you can use properties of the content control to prevent users from editing or deleting the control:

The LockContents property prevents users from editing the contents. The LockContentControl property prevents users from deleting the control.

If the area you want to protect is not inside a content control, or if you want to protect an area that contains content controls and other types of content, you can put the whole area in a GroupContentControl. Unlike other content controls, a GroupContentControl provides no UI that is visible to the user. Its only purpose is to define a region that users cannot edit.

Note
If you create a GroupContentControl that contains embedded content controls, the embedded content controls are not automatically protected. You must use the LockContents property of each embedded control to prevent users from editing their contents.

For more information about how to use content controls to protect parts of documents, see How to: Protect Parts of Documents by Using Content Controls.

Binding Data to Content Controls

You can display data in documents by binding a content control to a data source. When the data source is updated, the content control reflects the changes. You can also save changes back to the data source. Content controls provide the following data binding options:

You can bind content controls to database fields or managed objects by using the same data binding model as Windows Forms. You can bind content controls to elements in pieces of XML (also named custom XML parts) that are embedded in the document.

For an overview of binding host controls in Office solutions to data, see Binding Data to Controls in Office Solutions.

Using the Windows Forms Data Binding Model

Most content controls support the simple data binding model that Windows Forms uses. Simple data binding means that a control is bound to a single data element, such as a value in a column of a data table. For more information, see Data Binding and Windows Forms. In document-level projects, you can bind data to content controls by using the Data Sources window in Visual Studio. For more information about how to add data-bound content controls to documents, see How to: Populate Documents with Data from a Database and How to: Populate Documents with Data from Objects. The following table lists the content controls that you can bind to each data type in the Data Sources window.

Data type Default content control Other content controls that can be bound to this data type
Boolean Byte PlainTextContentControl BuildingBlockGalleryContentControl ComboBoxContentControl

Char Double Enum Guid Int16 Int32 Int64 SByte Single String TimeSpan UInt16 UInt32 UInt64

DatePickerContentControl RichTextContentControl

DateTime

DatePickerContentControl

BuildingBlockGalleryContentControl ComboBoxContentControl PlainTextContentControl RichTextContentControl

Image Byte array

PictureContentControl

None

In document-level and application-level projects, you can bind a content control to a data source programmatically by using the Add method of the DataBindings property of the control. If you do this, pass in the string Text to the propertyName parameter of the Add method. The Text property is the default data binding property of content controls. Content controls also support two-way data binding, in which changes in the control are updated to the data source. For more information, see How to: Update a Data Source with Data from a Host Control.

Note

Content controls do not support complex data binding. If you bind a DropDownListContentControl or ComboBoxContentControl to a data source by using the Windows Forms data model, users will see only a single value when they click the control. If you want to bind these controls to a set of data values that users can choose from, you can bind these controls to elements in a custom XML part.

Binding Content Controls to Custom XML Parts

You can bind some content controls to elements in custom XML parts that are embedded in the document. For more information about custom XML parts, see Custom XML Parts Overview. To bind a content control to an element in a custom XML part, use the XMLMapping property of the control. The following code example demonstrates how to bind a PlainTextContentControl to the Price element under the Product node in a custom XML part that has already been added to the document. C# VB Copy

plainTextContentControl1.XMLMapping.SetMapping("/Product/Price", String.Empty, nul l);

For a walkthrough that demonstrates how to bind content controls to custom XML parts in more detail, see Walkthrough: Binding Content Controls to Custom XML Parts. When you bind a content control to a custom XML part, two-way data binding is automatically enabled. If a user edits text in the control, the corresponding XML elements are automatically updated. Similarly, if element values in the custom XML parts are changed, the content controls that are bound to the XML elements will display the new data. You can bind the following types of content controls to custom XML parts:

ComboBoxContentControl DatePickerContentControl DropDownListContentControl PictureContentControl PlainTextContentControl

Data Binding Events for Content Controls

All content controls provide a set of events that you can handle to perform data-related tasks, such as validating that the text in a control meets certain criteria before the data source is updated. The following table lists the content control events that are related to data binding.

Task
Run code just before Word automatically updates the text in a content control that is bound to a custom XML part.

Event
ContentUpdating

Run code just before Word automatically updates data in a custom XML part that is bound to a content control (that is, after the text in the content control changes).

StoreUpdating

Run your own code to validate the contents of the control according to custom criteria.

Validating

Run code after the contents of the control have been successfully validated.

Validated

Limitations of Content Controls

When you use content controls in your Office projects, be aware of the following limitations.

Behavior Differences Between Design Time and Run Time

Many of the limitations that Microsoft Office Word imposes on content controls at run time are not enforced at design time. When you design the UI of a document-level solution in Visual Studio, be sure to modify content controls only in ways that are supported at run time. If you modify a content control at design time in a way that the control does not support at run time, the Visual Studio designer will not alert you of the unsupported changes. However, when you debug or run the project, or if you save and then reopen the project, Word will display an error message and request permission to repair the document. When you repair the document, Word removes all unsupported content and formatting from the control. For example, Word does not prevent you from adding a table to a PlainTextContentControl at design time. However, because PlainTextContentControl objects cannot contain tables at run time, Word will display an error message when the document is opened. Also note that many properties that define the behavior of content controls have no effect at design time. For example, if you set the LockContents property of a content control to True at design time, you can still edit text in the control in the Visual Studio designer. This property only prevents users from editing the control at run time.

Event Limitations
Content controls do not provide an event that is raised when the user changes text or other items in the control. For example, there is no event that is raised when a user selects a different item in a DropDownListContentControl or ComboBoxContentControl. To determine when a user edits the contents of a content control, you can bind the control to a custom XML part, and then handle the StoreUpdating event. This event is raised when the user changes the contents of a control that is bound to a custom XML part. For a walkthrough that demonstrates how to bind a content control to a custom XML part, see Walkthrough: Binding Content Controls to Custom XML Parts.

Check Box Content Controls in Word 2010 Projects

Word 2010 introduced a new type of content control that represents a check box. However, the Visual Studio Tools for Office runtime does not provide a corresponding CheckBoxContentControl type for you

to use in Office projects. To create a check box content control in a Word 2010 project, use the AddContentControl method to create a Microsoft.Office.Tools.Word.ContentControl object, and pass the wdContentControlCheckBox value to the method to specify a check box content control. The following code example demonstrates how to do this. C# VB Copy

this.Paragraphs[1].Range.InsertParagraphBefore(); this.Paragraphs[1].Range.Select(); Microsoft.Office.Tools.Word.ContentControl checkBoxControl1 = this.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType. wdContentControlCheckBox);

// The following line of code compiles in projects that target the .NET Framework 4, but it does not compile // in projects that target the .NET Framework 3.5. checkBoxControl1.Checked = true;

// In projects that target the .NET Framework 3.5, use the following code. checkBoxControl1.InnerObject.Checked = true;

Note
The Checked property of Microsoft.Office.Tools.Word.ContentControl objects can be used directly only in projects that target the .NET Framework 4. In projects that target the .NET Framework 3.5, you must use the InnerObject property to access the Checked property of the underlying Microsoft.Office.Interop.Word.ContentControl object. For more information, see Programmatic Limitations of Host Items and Host Controls.

See Also

Tasks How to: Add Content Controls to Word Documents Walkthrough: Creating a Template By Using Content Controls Concepts Automating Word by Using Extended Objects Programmatic Limitations of Host Items and Host Controls Other Resources Data in Office Solutions Binding Data to Controls in Office Solutions

How to: Add Content Controls to Word Documents

Visual Studio 2010 Other Versions

In document-level Word projects, you can add content controls to the document in your project at design time or at run time. In application-level Word projects, you can add content controls to any open document at run time. Applies to: The information in this topic applies to document-level projects and application-level projects for Word 2007 and Word 2010. For more information, see Features Available by Office Application and Project Type. This topic describes the following tasks:

Adding content controls at design time Adding content controls at run time in a document-level project Adding content controls at run time in an application-level project

For information about content controls, see Content Controls.

Adding Content Controls at Design Time

There are several ways to add content controls to the document in a document-level project at design time:

Add a content control from the Word Controls tab of the Toolbox. Add a content control to your document in the same manner you would add a native content control in Word. Drag a content control to your document from the Data Sources window. This is useful when you want to bind the control to data when the control is created. For more information, see How to: Populate Documents with Data from Objects and How to: Populate Documents with Data from a Database.

Note
Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Visual Studio Settings.

To add a content control to a document by using the Toolbox

1. 2. 3.

In the document that is hosted in the Visual Studio designer, put the cursor where you want to add the content control, or select the text that you want the content control to replace. Open the Toolbox and click the Word Controls tab. Add the control one of the following ways: Double-click a content control in the Toolbox. or

Click a content control in the Toolbox and then press the ENTER key. or

Drag a content control from the Toolbox to the document. The content control is added at the current selection in the document, not at the location of the mouse pointer.

Note
You cannot add a GroupContentControl by using the Toolbox. You can only add a GroupContentControl in Word, or at run time.

Note
Visual Studio does not provide a check box content control in the Toolbox for Word 2010 projects. To add a check box content control to the document, you must create a ContentControl object programmatically. For more information, see Content Controls.

To add a content control to a document in Word

1. 2. In the document that is hosted in the Visual Studio designer, put the cursor where you want to add the content control, or select the text that you want the content control to replace. On the Ribbon, click the Developer tab.

Note
If the Developer tab is not visible, you must first show it. For more information, see How to: Show the Developer Tab on the Ribbon.

3.

In the Controls group, click the icon for the content control that you want to add.

Adding Content Controls at Run Time in a Document-Level Project

You can add content controls programmatically to your document at run time by using methods of the Controls property of the ThisDocument class in your project. Each method has three overloads that you can use to add a content control in the following ways:

Add a control at the current selection. Add a control at a specified range. Add a control that is based on a native content control in the document.

Dynamically created content controls are not persisted in the document when the document is closed. However, a native content control remains in the document. You can recreate a content control that is based on a native content control the next time the document is opened. For more information, see Adding Controls to Office Documents at Run Time.

Note
To add a check box content control to a document in a Word 2010 project, you must create a ContentControl object. For more information, see Content Controls.

To add a content control at the current selection

Use a ControlCollection method that has the name Add<control class> (where control class is the class name of the content control that you want to add, such as AddRichTextContentControl), and that has a single parameter for the name of the new control. The following code example uses the ControlCollection.AddRichTextContentControl(String) method to add a new RichTextContentControl to the beginning of the document. To run this code, add the code to the ThisDocument class in your project, and call the AddRichTextControlAtSelection method from the ThisDocument_Startup event handler. C# VB Copy

private Microsoft.Office.Tools.Word.RichTextContentControl richTextControl1;

private void AddRichTextControlAtSelection() { this.Paragraphs[1].Range.InsertParagraphBefore(); this.Paragraphs[1].Range.Select();

richTextControl1 = this.Controls.AddRichTextContentControl("richTextContro l1"); richTextControl1.PlaceholderText = "Enter your first name"; }

To add a content control at a specified range

Use a ControlCollection method that has the name Add<control class> (where control class is the name of the content control class that you want to add, such as AddRichTextContentControl), and that has a Microsoft.Office.Interop.Word.Range parameter. The following code example uses the ControlCollection.AddRichTextContentControl(Range, String) method to add a new RichTextContentControl to the beginning of the document. To run this code, add the code to the ThisDocument class in your project, and call the AddRichTextControlAtRange method from the ThisDocument_Startup event handler. C# VB Copy

private Microsoft.Office.Tools.Word.RichTextContentControl richTextControl2;

private void AddRichTextControlAtRange() { this.Paragraphs[1].Range.InsertParagraphBefore();

richTextControl2 = this.Controls.AddRichTextContentControl(this.Paragraphs [1].Range, "richTextControl2"); richTextControl2.PlaceholderText = "Enter your first name"; }

To add a content control that is based on a native content control

Use a ControlCollection method that has the name Add<control class> (where control class is the name of the content control class that you want to add, such as AddRichTextContentControl), and that has a Microsoft.Office.Interop.Word.ContentControl parameter. The following code example uses the ControlCollection.AddRichTextContentControl(ContentControl, String) method to create a new RichTextContentControl for every native rich text control that is in the document. To run this code, add the code to the ThisDocument class in your project, and call the CreateRichTextControlsFromNativeControls method from the ThisDocument_Startup event handler. C# VB Copy

private System.Collections.Generic.List <Microsoft.Office.Tools.Word.RichTextContentControl> richTextControls;

private void CreateRichTextControlsFromNativeControls() { if (this.ContentControls.Count <= 0) return;

richTextControls = new System.Collections.Generic.List <Microsoft.Office.Tools.Word.RichTextContentControl>(); int count = 0;

foreach (Word.ContentControl nativeControl in this.ContentControls) { if (nativeControl.Type == Microsoft.Office.Interop.Word.WdContentControlType.wdContentContro lRichText) { count++;

Microsoft.Office.Tools.Word.RichTextContentControl tempControl = this.Controls.AddRichTextContentControl(nativeControl, "VSTORichTextControl" + count.ToString()); richTextControls.Add(tempControl); } } }

Adding Content Controls at Run Time in an Application-Level Project

You can add content controls programmatically to any open document at run time by using an applicationlevel add-in. To do this, generate a Document host item that is based on an open document, and then use methods of the Controls property of this host item. Each method has three overloads that you can use to add a content control in the following ways:

Add a control at the current selection. Add a control at a specified range. Add a control that is based on a native content control in the document.

Dynamically created content controls are not persisted in the document when the document is closed. However, a native content control remains in the document. You can recreate a content control that is based on a native content control the next time the document is opened. For more information, see Persisting Dynamic Controls in Office Documents. For more information about generating host items in application-level projects, see Extending Word Documents and Excel Workbooks in Application-Level Add-ins at Run Time.

Note
To add a check box content control to a document in a Word 2010 project, you must create a ContentControl object. For more information, see Content Controls.

To add a content control at the current selection

Use a ControlCollection method that has the name Add<control class> (where control class is the class name of the content control that you want to add, such as AddRichTextContentControl), and that has a single parameter for the name of the new control.

The following code example uses the ControlCollection.AddRichTextContentControl(String) method to add a new RichTextContentControl to the beginning of the active document. To run this code, add the code to the ThisAddIn class in your project, and call the AddRichTextControlAtSelection method from the ThisAddIn_Startup event handler. C# VB Copy

private Microsoft.Office.Tools.Word.RichTextContentControl richTextControl1;

private void AddRichTextControlAtSelection() { Word.Document currentDocument = this.Application.ActiveDocument; currentDocument.Paragraphs[1].Range.InsertParagraphBefore(); currentDocument.Paragraphs[1].Range.Select();

// Use the following line of code in projects that target the .NET Framewo rk 4. Document extendedDocument = Globals.Factory.GetVstoObject(currentDocumen t);

// In projects that target the .NET Framework 3.5, use the following line of code. // Document extendedDocument = currentDocument.GetVstoObject();

richTextControl1 = extendedDocument.Controls.AddRichTextContentControl("ri chTextControl1"); richTextControl1.PlaceholderText = "Enter your first name"; }

To add a content control at a specified range

Use a ControlCollection method that has the name Add<control class> (where control class is the name of the content control class that you want to add, such as AddRichTextContentControl), and that has a Microsoft.Office.Interop.Word.Range parameter. The following code example uses the ControlCollection.AddRichTextContentControl(Range, String) method to add a new RichTextContentControl to the beginning of the active document. To run this code, add the code to the ThisAddIn class in your project, and call the AddRichTextControlAtRange method from the ThisAddIn_Startup event handler. C# VB Copy

private Microsoft.Office.Tools.Word.RichTextContentControl richTextControl2;

private void AddRichTextControlAtRange() { Word.Document currentDocument = this.Application.ActiveDocument; currentDocument.Paragraphs[1].Range.InsertParagraphBefore();

// Use the following line of code in projects that target the .NET Framewo rk 4. Document extendedDocument = Globals.Factory.GetVstoObject(currentDocumen t);

// In projects that target the .NET Framework 3.5, use the following line of code. // Document extendedDocument = currentDocument.GetVstoObject();

richTextControl2 = extendedDocument.Controls.AddRichTextContentControl( currentDocument.Paragraphs[1].Range, "richTextControl2"); richTextControl2.PlaceholderText = "Enter your first name"; }

To add a content control that is based on a native content control

Use a ControlCollection method that has the name Add<control class> (where control class is the name of the content control class that you want to add, such as AddRichTextContentControl), and that has a Microsoft.Office.Interop.Word.ContentControl parameter. The following code example uses the ControlCollection.AddRichTextContentControl(ContentControl, String) method to create a new RichTextContentControl for every native rich text control that is in a document, after the document is opened. To run this code, add the code to the ThisAddIn class in your project. C# VB Copy

private System.Collections.Generic.List <Microsoft.Office.Tools.Word.RichTextContentControl> richTextControls;

private void Application_DocumentOpen(Microsoft.Office.Interop.Word.Document D oc) { if (Doc.ContentControls.Count > 0) { // Use the following line of code in projects that target the .NET Fra mework 4. Document extendedDocument = Globals.Factory.GetVstoObject(Doc);

// In projects that target the .NET Framework 3.5, use the following l ine of code. // Document extendedDocument = Doc.GetVstoObject();

richTextControls = new System.Collections.Generic.List <Microsoft.Office.Tools.Word.RichTextContentControl>(); int count = 0;

foreach (Word.ContentControl nativeControl in Doc.ContentControls) { if (nativeControl.Type == Microsoft.Office.Interop.Word.WdContentControlType.wdContentCo ntrolRichText) { count++; Microsoft.Office.Tools.Word.RichTextContentControl tempControl = extendedDocument.Controls.AddRichTextContentControl(native Control, "VSTORichTextControl" + count.ToString()); richTextControls.Add(tempControl); } } } }

For C#, you must also attach the Application_DocumentOpen event handler to the DocumentOpen event. C# Copy

this.Application.DocumentOpen += new Word.ApplicationEvents4_DocumentOpenEventHandler(Application_DocumentO pen);

See Also

Concepts Automating Word by Using Extended Objects Host Items and Host Controls Overview Adding Controls to Office Documents at Run Time Programmatic Limitations of Host Items and Host Controls Helper Methods for Host Controls Other Resources Programming Application-Level Add-Ins Programming Document-Level Customizations