ControlCollection.AddBuildingBlockGalleryContentControl Method (Range, String)

Adds a new BuildingBlockGalleryContentControl 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 AddBuildingBlockGalleryContentControl ( _
    range As Range, _
    name As String _
) As BuildingBlockGalleryContentControl

BuildingBlockGalleryContentControl AddBuildingBlockGalleryContentControl(
    Range range,
    string name
)

Parameters

• range
  Type: Microsoft.Office.Interop.Word.Range
  A Range that provides the bounds for the new control.

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

Return Value

Type: Microsoft.Office.Tools.Word.BuildingBlockGalleryContentControl
The BuildingBlockGalleryContentControl 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 BuildingBlockGalleryContentControl 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 BuildingBlockGalleryContentControl to the beginning of the document. The BuildingBlockGalleryContentControl displays equation building blocks that are provided by Microsoft Office Word.

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

Dim buildingBlockGalleryControl2 As Microsoft.Office.Tools.Word.BuildingBlockGalleryContentControl

Private Sub AddBuildingBlockGalleryControlAtRange()
    Me.Paragraphs(1).Range.InsertParagraphBefore()
    buildingBlockGalleryControl2 = Me.Controls.AddBuildingBlockGalleryContentControl( _
        Me.Paragraphs(1).Range, "buildingBlockGalleryControl2")
    With buildingBlockGalleryControl2
        .PlaceholderText = "Choose an equation"
        .BuildingBlockCategory = "Built-In"
        .BuildingBlockType = Word.WdBuildingBlockTypes.wdTypeEquations
    End With
End Sub

private Microsoft.Office.Tools.Word.BuildingBlockGalleryContentControl buildingBlockControl2;

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

    buildingBlockControl2 = this.Controls.AddBuildingBlockGalleryContentControl(
       this.Paragraphs[1].Range, "buildingBlockControl2");
    buildingBlockControl2.PlaceholderText = "Choose an equation";
    buildingBlockControl2.BuildingBlockCategory = "Built-In";
    buildingBlockControl2.BuildingBlockType = Word.WdBuildingBlockTypes.wdTypeEquations;
}

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

Dim buildingBlockGalleryControl2 As BuildingBlockGalleryContentControl

Private Sub AddBuildingBlockGalleryControlAtRange()
    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()
    buildingBlockGalleryControl2 = vstoDoc.Controls.AddBuildingBlockGalleryContentControl( _
        vstoDoc.Paragraphs(1).Range, "buildingBlockGalleryControl2")
    With buildingBlockGalleryControl2
        .PlaceholderText = "Choose an equation"
        .BuildingBlockCategory = "Built-In"
        .BuildingBlockType = Word.WdBuildingBlockTypes.wdTypeEquations
    End With
End Sub

private Microsoft.Office.Tools.Word.BuildingBlockGalleryContentControl buildingBlockControl2;

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

    Document vstoDoc = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);
    vstoDoc.Paragraphs[1].Range.InsertParagraphBefore();

    buildingBlockControl2 = vstoDoc.Controls.AddBuildingBlockGalleryContentControl(
       vstoDoc.Paragraphs[1].Range, "buildingBlockControl2");
    buildingBlockControl2.PlaceholderText = "Choose an equation";
    buildingBlockControl2.BuildingBlockCategory = "Built-In";
    buildingBlockControl2.BuildingBlockType = Word.WdBuildingBlockTypes.wdTypeEquations;
}

.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

AddBuildingBlockGalleryContentControl 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