Aracılığıyla paylaş

How to: Add Content Controls to Word Documents

  • Makale

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 2007

For more information, see Features Available by Application and Project Type.

In document-level projects, you can add content controls to the document in your project at design time or at run time. Starting in Visual Studio 2008 Service Pack 1 (SP1), you can also add content controls to any open document at run time by using an application-level add-in for Word 2007.

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:

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

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 Visual Studio Tools for Office 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 Visual Studio Tools for Office 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.

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

Starting in SP1, 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 Visual Studio Tools for Office 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 Visual Studio Tools for Office 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.

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 = currentDocument.GetVstoObject()
    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 = currentDocument.GetVstoObject();
    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 = currentDocument.GetVstoObject()
    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 = 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.

    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 = Doc.GetVstoObject()
        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 = 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.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

Host Items and Host Controls Overview

Adding Controls to Office Documents at Run Time

Programmatic Limitations of Host Items and Host Controls

Programming Application-Level Add-Ins

Programming Document-Level Customizations

Helper Methods for Host Controls

Other Resources

Word Host Controls

Change History

Date

History

Reason

July 2008

Added procedure for application-level add-ins.

SP1 feature change.