Aspose::Words::BuildingBlocks::BuildingBlock class

BuildingBlock class

Represents a glossary document entry such as a Building Block, AutoText or an AutoCorrect entry. To learn more, visit the Aspose.Words Document Object Model (DOM) documentation article.

class BuildingBlock : public Aspose::Words::CompositeNode


Accept(System::SharedPtr<Aspose::Words::DocumentVisitor>) overrideAccepts a visitor.
AppendChild(const System::SharedPtr<Aspose::Words::Node>&)Adds the specified node to the end of the list of child nodes for this node.
BuildingBlock(const System::SharedPtr<Aspose::Words::BuildingBlocks::GlossaryDocument>&)Initializes a new instance of this class.
Clone(bool)Creates a duplicate of the node.
get_Behavior() constSpecifies the behavior that shall be applied when the contents of the building block is inserted into the main document.
get_Category() constSpecifies the second-level categorization for the building block.
get_ChildNodes()Gets all immediate child nodes of this node.
get_Count()Gets the number of immediate children of this node.
get_CustomNodeId() constSpecifies custom node identifier.
get_Description() constGets or sets the description associated with this building block.
virtual get_Document() constGets the document to which this node belongs.
get_FirstChild() constGets the first child of the node.
get_FirstSection()Gets the first section in the building block.
get_Gallery() constSpecifies the first-level categorization for the building block for the purposes of classification or user interface sorting.
get_Guid() constGets or sets an identifier (a 128-bit GUID) that uniquely identifies this building block.
get_HasChildNodes()Returns true if this node has any child nodes.
get_IsComposite() overrideReturns true as this node can have child nodes.
get_LastChild() constGets the last child of the node.
get_LastSection()Gets the last section in the building block.
get_Name() constGets or sets the name of this building block.
get_NextSibling()Gets the node immediately following this node.
get_NodeType() const overrideReturns the BuildingBlock value.
get_ParentNode()Gets the immediate parent of this node.
get_PreviousSibling()Gets the node immediately preceding this node.
get_Range()Returns a Range object that represents the portion of a document that is contained in this node.
get_Sections()Returns a collection that represents all sections in the building block.
get_Type() constSpecifies the building block type.
GetAncestor(Aspose::Words::NodeType)Gets the first ancestor of the specified NodeType.
GetChild(Aspose::Words::NodeType, int32_t, bool)Returns an Nth child node that matches the specified type.
GetChildNodes(Aspose::Words::NodeType, bool)Returns a live collection of child nodes that match the specified type.
GetEnumerator() overrideProvides support for the for each style iteration over the child nodes of this node.
GetText() overrideGets the text of this node and of all its children.
GetType() const override
IndexOf(const System::SharedPtr<Aspose::Words::Node>&)Returns the index of the specified child node in the child node array.
InsertAfter(const System::SharedPtr<Aspose::Words::Node>&, const System::SharedPtr<Aspose::Words::Node>&)Inserts the specified node immediately after the specified reference node.
InsertBefore(const System::SharedPtr<Aspose::Words::Node>&, const System::SharedPtr<Aspose::Words::Node>&)Inserts the specified node immediately before the specified reference node.
Is(const System::TypeInfo&) const override
NextPreOrder(const System::SharedPtr<Aspose::Words::Node>&)Gets next node according to the pre-order tree traversal algorithm.
static NodeTypeToString(Aspose::Words::NodeType)A utility method that converts a node type enum value into a user friendly string.
PrependChild(const System::SharedPtr<Aspose::Words::Node>&)Adds the specified node to the beginning of the list of child nodes for this node.
PreviousPreOrder(const System::SharedPtr<Aspose::Words::Node>&)Gets the previous node according to the pre-order tree traversal algorithm.
Remove()Removes itself from the parent.
RemoveAllChildren()Removes all the child nodes of the current node.
RemoveChild(const System::SharedPtr<Aspose::Words::Node>&)Removes the specified child node.
RemoveSmartTags()Removes all SmartTag descendant nodes of the current node.
SelectNodes(const System::String&)Selects a list of nodes matching the XPath expression.
SelectSingleNode(const System::String&)Selects the first Node that matches the XPath expression.
set_Behavior(Aspose::Words::BuildingBlocks::BuildingBlockBehavior)Setter for Aspose::Words::BuildingBlocks::BuildingBlock::get_Behavior.
set_Category(const System::String&)Setter for Aspose::Words::BuildingBlocks::BuildingBlock::get_Category.
set_CustomNodeId(int32_t)Setter for Aspose::Words::Node::get_CustomNodeId.
set_Description(const System::String&)Setter for Aspose::Words::BuildingBlocks::BuildingBlock::get_Description.
set_Gallery(Aspose::Words::BuildingBlocks::BuildingBlockGallery)Setter for Aspose::Words::BuildingBlocks::BuildingBlock::get_Gallery.
set_Guid(System::Guid)Setter for Aspose::Words::BuildingBlocks::BuildingBlock::get_Guid.
set_Name(const System::String&)Setter for Aspose::Words::BuildingBlocks::BuildingBlock::get_Name.
set_Type(Aspose::Words::BuildingBlocks::BuildingBlockType)Setter for Aspose::Words::BuildingBlocks::BuildingBlock::get_Type.
SetTemplateWeakPtr(uint32_t) override
ToString(Aspose::Words::SaveFormat)Exports the content of the node into a string in the specified format.
ToString(const System::SharedPtr<Aspose::Words::Saving::SaveOptions>&)Exports the content of the node into a string using the specified save options.
static Type()


BuildingBlock can contain only Section nodes.

BuildingBlock can only be a child of GlossaryDocument.

You can create new building blocks and insert them into a glossary document. You can modify or delete existing building blocks. You can copy or move building blocks between documents. You can insert content of a building block into a document.

Corresponds to the docPart, docPartPr and docPartBody elements in OOXML.


Shows how to add a custom building block to a document.

void CreateAndInsert()
    // A document's glossary document stores building blocks.
    auto doc = MakeObject<Document>();
    auto glossaryDoc = MakeObject<GlossaryDocument>();

    // Create a building block, name it, and then add it to the glossary document.
    auto block = MakeObject<BuildingBlock>(glossaryDoc);
    block->set_Name(u"Custom Block");


    // All new building block GUIDs have the same zero value by default, and we can give them a new unique value.
    ASSERT_EQ(u"00000000-0000-0000-0000-000000000000", System::ObjectExt::ToString(block->get_Guid()));


    // The following properties categorize building blocks
    // in the menu we can access in Microsoft Word via "Insert" -> "Quick Parts" -> "Building Blocks Organizer".
    ASSERT_EQ(u"(Empty Category)", block->get_Category());
    ASSERT_EQ(BuildingBlockType::None, block->get_Type());
    ASSERT_EQ(BuildingBlockGallery::All, block->get_Gallery());
    ASSERT_EQ(BuildingBlockBehavior::Content, block->get_Behavior());

    // Before we can add this building block to our document, we will need to give it some contents,
    // which we will do using a document visitor. This visitor will also set a category, gallery, and behavior.
    auto visitor = MakeObject<ExBuildingBlocks::BuildingBlockVisitor>(glossaryDoc);

    // We can access the block that we just made from the glossary document.
    SharedPtr<BuildingBlock> customBlock = glossaryDoc->GetBuildingBlock(BuildingBlockGallery::QuickParts, u"My custom building blocks", u"Custom Block");

    // The block itself is a section that contains the text.
    ASSERT_EQ(String::Format(u"Text inside {0}\f", customBlock->get_Name()), customBlock->get_FirstSection()->get_Body()->get_FirstParagraph()->GetText());
    ASPOSE_ASSERT_EQ(customBlock->get_FirstSection(), customBlock->get_LastSection());
    std::function<void()> parseGuid = [&customBlock]()

    // Now, we can insert it into the document as a new section.
    doc->AppendChild(doc->ImportNode(customBlock->get_FirstSection(), true));

    // We can also find it in Microsoft Word's Building Blocks Organizer and place it manually.
    doc->Save(ArtifactsDir + u"BuildingBlocks.CreateAndInsert.dotx");

class BuildingBlockVisitor : public DocumentVisitor
    BuildingBlockVisitor(SharedPtr<GlossaryDocument> ownerGlossaryDoc)
        mBuilder = MakeObject<System::Text::StringBuilder>();
        mGlossaryDoc = ownerGlossaryDoc;

    VisitorAction VisitBuildingBlockStart(SharedPtr<BuildingBlock> block) override
        // Configure the building block as a quick part, and add properties used by Building Blocks Organizer.
        block->set_Category(u"My custom building blocks");
        block->set_Description(u"Using this block in the Quick Parts section of word will place its contents at the cursor.");

        // Add a section with text.
        // Inserting the block into the document will append this section with its child nodes at the location.
        auto section = MakeObject<Section>(mGlossaryDoc);

        auto run = MakeObject<Run>(mGlossaryDoc, String(u"Text inside ") + block->get_Name());

        return VisitorAction::Continue;

    VisitorAction VisitBuildingBlockEnd(SharedPtr<BuildingBlock> block) override
        mBuilder->Append(String(u"Visited ") + block->get_Name() + u"\r\n");
        return VisitorAction::Continue;

    SharedPtr<System::Text::StringBuilder> mBuilder;
    SharedPtr<GlossaryDocument> mGlossaryDoc;

See Also