ControlCollection.AddGroupContentControl Method (Range, String)

  • Article

Adds a new GroupContentControl at the specified range in the document.

Namespace:  Microsoft.Office.Tools.Word
Assembly:  Microsoft.Office.Tools.Word (in Microsoft.Office.Tools.Word.dll)

Syntax

'Declaration
Function AddGroupContentControl ( _
    range As Range, _
    name As String _
) As GroupContentControl

GroupContentControl AddGroupContentControl(
    Range range,
    string name
)

Parameters

Return Value

Type: Microsoft.Office.Tools.Word.GroupContentControl
The GroupContentControl that was added to the document.

Exceptions

Exception Condition
ArgumentNullException

name is nulla null reference (Nothing in Visual Basic) or has zero length.
ControlNameAlreadyExistsException

A control with the same name is already in the ControlCollection.

Remarks

Use this method to add a new GroupContentControl at a specified range in the document at run time. For more information, see Adding Controls to Office Documents at Run Time.

Examples

The following code example adds a new paragraph to the beginning of the document, and it creates a GroupContentControl that contains this paragraph. The GroupContentControl prevents users from editing the text in the paragraph. For more information about using a GroupContentControl to protect a part of a document, see Content Controls.

This version is for a document-level customization. To use this code, paste it into the ThisDocument class in your project, and call the AddGroupControlAtRange method from the ThisDocument_Startup method.

Dim groupControl2 As Microsoft.Office.Tools.Word.GroupContentControl

Private Sub AddGroupControlAtRange()
    Me.Paragraphs(1).Range.InsertParagraphBefore()
    Dim range1 As Word.Range = Me.Paragraphs(1).Range
    range1.Text = "You cannot edit or change the formatting of text " & _
            "in this paragraph, because this paragraph is in a GroupContentControl."
    range1.Select()
    groupControl2 = Me.Controls.AddGroupContentControl(range1, "groupControl2")
End Sub

private Microsoft.Office.Tools.Word.GroupContentControl groupControl2;

private void AddGroupControlAtRange()
{
    this.Paragraphs[1].Range.InsertParagraphBefore();
    Word.Range range1 = this.Paragraphs[1].Range;
    range1.Text = "You cannot edit or change the formatting of text " +
        "in this paragraph, because this paragraph is in a GroupContentControl.";
    range1.Select();

    groupControl2 = this.Controls.AddGroupContentControl(range1, "groupControl2");
}

This version is for an application-level add-in that targets the .NET Framework 4. To use this code, paste it into the ThisAddIn class in your project, and call the AddGroupControlAtRange method from the ThisAddIn_Startup method.

Dim groupControl2 As Microsoft.Office.Tools.Word.GroupContentControl

Private Sub AddGroupControlAtRange()
    If Me.Application.ActiveDocument Is Nothing Then
        Return
    End If

    Dim vstoDoc As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)
    vstoDoc.Paragraphs(1).Range.InsertParagraphBefore()
    Dim range1 As Word.Range = vstoDoc.Paragraphs(1).Range
    range1.Text = "You cannot edit or change the formatting of text " & _
            "in this paragraph, because this paragraph is in a GroupContentControl."
    range1.Select()
    groupControl2 = vstoDoc.Controls.AddGroupContentControl(range1, "groupControl2")
End Sub

private Microsoft.Office.Tools.Word.GroupContentControl groupControl2;

private void AddGroupControlAtRange()
{
    if (this.Application.ActiveDocument == null)
        return;

    Document vstoDoc = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);
    vstoDoc.Paragraphs[1].Range.InsertParagraphBefore();
    Word.Range range1 = vstoDoc.Paragraphs[1].Range;
    range1.Text = "You cannot edit or change the formatting of text " +
        "in this paragraph, because this paragraph is in a GroupContentControl.";
    range1.Select();

    groupControl2 = vstoDoc.Controls.AddGroupContentControl(range1, "groupControl2");
}

.NET Framework Security

See Also

Reference

ControlCollection Interface

AddGroupContentControl Overload

Microsoft.Office.Tools.Word Namespace

Other Resources

Adding Controls to Office Documents at Run Time

Helper Methods for Host Controls

How to: Add Content Controls to Word Documents