ControlCollection.AddGroupContentControl Method (ContentControl, String)

Adds a new GroupContentControl that is based on a native content control in the document.

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

Syntax

'Declaration
Function AddGroupContentControl ( _
    contentControl As ContentControl, _
    name As String _
) As GroupContentControl

GroupContentControl AddGroupContentControl(
    ContentControl contentControl,
    string name
)

Parameters

• contentControl
  Type: Microsoft.Office.Interop.Word.ContentControl
  The Microsoft.Office.Interop.Word.ContentControl that is the basis for the new control.

• name
  Type: System.String
  The name of the new control.

Return Value

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

Exceptions

Exception	Condition
ArgumentNullException	contentControl is nulla null reference (Nothing in Visual Basic). -or- 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.
ArgumentException	contentControl is not a building block gallery (that is, the Type property of contentControl does not have the value Microsoft.Office.Interop.Word.WdContentControlType.wdContentControlGroup).

Remarks

Use this method to add a new GroupContentControl that is based on a native content control in the document at run time. This is useful when you create a GroupContentControl at run time, and you want to recreate the same control the next time the document is opened. For more information, see Adding Controls to Office Documents at Run Time.

Examples

The following code example creates a new GroupContentControl for every native group control that is in the document.

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

Private groupControls As New System.Collections.Generic.List _
        (Of Microsoft.Office.Tools.Word.GroupContentControl)

Private Sub CreateGroupControlsFromNativeControls()
    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.wdContentControlGroup Then
            count += 1
            Dim tempControl As Microsoft.Office.Tools.Word.GroupContentControl = _
                Me.Controls.AddGroupContentControl(nativeControl, _
                "VSTOGroupContentControl" + count.ToString())
            groupControls.Add(tempControl)
        End If
    Next nativeControl
End Sub

private System.Collections.Generic.List
    <Microsoft.Office.Tools.Word.GroupContentControl> groupControls;

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

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

    foreach (Word.ContentControl nativeControl in this.ContentControls)
    {
        if (nativeControl.Type == Word.WdContentControlType.wdContentControlGroup)
        {
            count++;
            Microsoft.Office.Tools.Word.GroupContentControl tempControl =
                this.Controls.AddGroupContentControl(nativeControl,
                "VSTOGroupControl" + count.ToString());
            groupControls.Add(tempControl);
        }
    }
}

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 CreateGroupControlsFromNativeControls method from the ThisAddIn_Startup method.

Private groupControls As New System.Collections.Generic.List _
        (Of Microsoft.Office.Tools.Word.GroupContentControl)

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

    Dim vstoDoc As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)
    If vstoDoc.ContentControls.Count <= 0 Then
        Return
    End If

    Dim count As Integer = 0
    For Each nativeControl As Word.ContentControl In vstoDoc.ContentControls
        If nativeControl.Type = Word.WdContentControlType.wdContentControlGroup Then
            count += 1
            Dim tempControl As Microsoft.Office.Tools.Word.GroupContentControl = _
                vstoDoc.Controls.AddGroupContentControl(nativeControl, _
                "VSTOGroupContentControl" + count.ToString())
            groupControls.Add(tempControl)
        End If
    Next nativeControl
End Sub

private System.Collections.Generic.List
    <Microsoft.Office.Tools.Word.GroupContentControl> groupControls;

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

    Document vstoDoc = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);
    if (vstoDoc.ContentControls.Count <= 0)
        return;

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

    foreach (Word.ContentControl nativeControl in vstoDoc.ContentControls)
    {
        if (nativeControl.Type == Word.WdContentControlType.wdContentControlGroup)
        {
            count++;
            Microsoft.Office.Tools.Word.GroupContentControl tempControl =
                vstoDoc.Controls.AddGroupContentControl(nativeControl,
                "VSTOGroupControl" + count.ToString());
            groupControls.Add(tempControl);
        }
    }
}

The following code example creates a new GroupContentControl for every native group control that the user adds to the document.

This version is for a document-level customization. To use this code, paste it into the ThisDocument class in your project. For C#, you must also attach the ThisDocument_GroupContentControlAfterAdd event handler to the ContentControlAfterAdd event of the ThisDocument class.

Private Sub ThisDocument_GroupContentControlAfterAdd(ByVal NewContentControl As Word.ContentControl, _
    ByVal InUndoRedo As Boolean) Handles Me.ContentControlAfterAdd

    If NewContentControl.Type = Word.WdContentControlType.wdContentControlGroup Then
        Me.Controls.AddGroupContentControl(NewContentControl, _
            "GroupControl" + NewContentControl.ID)
    End If
End Sub

void ThisDocument_GroupContentControlAfterAdd(Word.ContentControl NewContentControl, bool InUndoRedo)
{
    if (NewContentControl.Type == Word.WdContentControlType.wdContentControlGroup)
    {
        this.Controls.AddGroupContentControl(NewContentControl,
            "GroupControl" + NewContentControl.ID);
    }
}

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. Also, you must attach the ActiveDocument_GroupContentControlAfterAdd event handler to the ContentControlAfterAdd event of the active document.

Private Sub ActiveDocument_GroupContentControlAfterAdd( _
    ByVal NewContentControl As Word.ContentControl, _
    ByVal InUndoRedo As Boolean)

    Dim vstoDoc As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)
    If NewContentControl.Type = Word.WdContentControlType. _
        wdContentControlGroup Then
        vstoDoc.Controls.AddGroupContentControl(NewContentControl, _
            "GroupControl" + NewContentControl.ID)
    End If
End Sub

void ActiveDocument_GroupContentControlAfterAdd(
    Word.ContentControl NewContentControl, bool InUndoRedo)
{
    Document vstoDoc = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);
    if (NewContentControl.Type == Word.WdContentControlType.wdContentControlGroup)
    {
        vstoDoc.Controls.AddGroupContentControl(NewContentControl,
            "GroupControl" + NewContentControl.ID);
    }
}

.NET Framework Security

• Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see Using Libraries from Partially Trusted Code.

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