How to: Add Content Controls to Word Documents

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 2013 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 Customizing Development Settings in Visual Studio.

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

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

2. Open the Toolbox and click the Word Controls tab.

3. 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 2013 and 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. 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.

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

  Dim richTextControl1 As Microsoft.Office.Tools.Word.RichTextContentControl
  
  Private Sub AddRichTextControlAtSelection()
      Me.Paragraphs(1).Range.InsertParagraphBefore()
      Me.Paragraphs(1).Range.Select()
      richTextControl1 = Me.Controls.AddRichTextContentControl("richTextControl1")
      richTextControl1.PlaceholderText = "Enter your first name" 
  End Sub
  

  private Microsoft.Office.Tools.Word.RichTextContentControl richTextControl1;
  
  private void AddRichTextControlAtSelection()
  {
      this.Paragraphs[1].Range.InsertParagraphBefore();
      this.Paragraphs[1].Range.Select();
  
      richTextControl1 = this.Controls.AddRichTextContentControl("richTextControl1");
      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 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.

  Dim richTextControl2 As Microsoft.Office.Tools.Word.RichTextContentControl
  
  Private Sub AddRichTextControlAtRange()
      Me.Paragraphs(1).Range.InsertParagraphBefore()
      richTextControl2 = Me.Controls.AddRichTextContentControl(Me.Paragraphs(1).Range, _
          "richTextControl2")
      richTextControl2.PlaceholderText = "Enter your first name" 
  End Sub
  

  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.

  Private richTextControls As New System.Collections.Generic.List _
          (Of Microsoft.Office.Tools.Word.RichTextContentControl)
  
  Private Sub CreateRichTextControlsFromNativeControls()
      If Me.ContentControls.Count <= 0 Then 
          Return 
      End If 
  
      Dim count As Integer = 0
      For Each nativeControl As Word.ContentControl In Me.ContentControls
          If nativeControl.Type = Word.WdContentControlType.wdContentControlRichText Then
              count += 1
              Dim tempControl As Microsoft.Office.Tools.Word.RichTextContentControl = _
                  Me.Controls.AddRichTextContentControl(nativeControl, _
                  "VSTORichTextContentControl" + count.ToString())
              richTextControls.Add(tempControl)
          End If 
      Next nativeControl
  End Sub
  

  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.wdContentControlRichText)
          {
              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 application-level 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 2013 or 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.

  Dim richTextControl1 As Microsoft.Office.Tools.Word.RichTextContentControl
  
  Private Sub AddRichTextControlAtSelection()
      Dim currentDocument As Word.Document = Me.Application.ActiveDocument
      currentDocument.Paragraphs(1).Range.InsertParagraphBefore()
      currentDocument.Paragraphs(1).Range.Select()
  
      Dim extendedDocument As Document = Globals.Factory.GetVstoObject(currentDocument)
  
  
      richTextControl1 = extendedDocument.Controls.AddRichTextContentControl("richTextControl1")
      richTextControl1.PlaceholderText = "Enter your first name" 
  End Sub
  

  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();
  
      Document extendedDocument = Globals.Factory.GetVstoObject(currentDocument);
  
      richTextControl1 = extendedDocument.Controls.AddRichTextContentControl("richTextControl1");
      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 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.

  Dim richTextControl2 As Microsoft.Office.Tools.Word.RichTextContentControl
  
  Private Sub AddRichTextControlAtRange()
      Dim currentDocument As Word.Document = Me.Application.ActiveDocument
      currentDocument.Paragraphs(1).Range.InsertParagraphBefore()
  
      Dim extendedDocument As Document = Globals.Factory.GetVstoObject(currentDocument)
  
      richTextControl2 = extendedDocument.Controls.AddRichTextContentControl( _
          extendedDocument.Paragraphs(1).Range, "richTextControl2")
      richTextControl2.PlaceholderText = "Enter your first name" 
  End Sub
  

  private Microsoft.Office.Tools.Word.RichTextContentControl richTextControl2;
  
  private void AddRichTextControlAtRange()
  {
      Word.Document currentDocument = this.Application.ActiveDocument;
      currentDocument.Paragraphs[1].Range.InsertParagraphBefore();
  
      Document extendedDocument = Globals.Factory.GetVstoObject(currentDocument);
  
      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.

  Private richTextControls As New System.Collections.Generic.List _
      (Of Microsoft.Office.Tools.Word.RichTextContentControl)
  
  Private Sub Application_DocumentOpen(ByVal Doc As Microsoft.Office.Interop.Word.Document) _
      Handles Application.DocumentOpen
  
      If Doc.ContentControls.Count > 0 Then 
  
          Dim extendedDocument As Document = Globals.Factory.GetVstoObject(Doc)
  
          Dim count As Integer = 0
          For Each nativeControl As Word.ContentControl In Doc.ContentControls
              If nativeControl.Type = Word.WdContentControlType.wdContentControlRichText Then
                  count += 1
                  Dim tempControl As Microsoft.Office.Tools.Word.RichTextContentControl = _
                      extendedDocument.Controls.AddRichTextContentControl(nativeControl, _
                      "VSTORichTextContentControl" + count.ToString())
                  richTextControls.Add(tempControl)
              End If 
          Next nativeControl
      End If 
  End Sub
  

  private System.Collections.Generic.List
      <Microsoft.Office.Tools.Word.RichTextContentControl> richTextControls;
  
  private void Application_DocumentOpen(Microsoft.Office.Interop.Word.Document Doc)
  {
      if (Doc.ContentControls.Count > 0)
      {
          Document extendedDocument = Globals.Factory.GetVstoObject(Doc);
  
          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.wdContentControlRichText)
              {
                  count++;
                  Microsoft.Office.Tools.Word.RichTextContentControl tempControl =
                      extendedDocument.Controls.AddRichTextContentControl(nativeControl,
                      "VSTORichTextControl" + count.ToString());
                  richTextControls.Add(tempControl);
              }
          }
      }
  }
  

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

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

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

Other Resources

Programming Application-Level Add-Ins

Programming Document-Level Customizations