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

Methods

MethodDescription
Accept(System::SharedPtr<Aspose::Words::DocumentVisitor>) overrideAccepts a visitor.
AcceptEnd(System::SharedPtr<Aspose::Words::DocumentVisitor>) override
AcceptStart(System::SharedPtr<Aspose::Words::DocumentVisitor>) override
AppendChild(T)
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_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_NextNode() const
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_PrevNode() const
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.
GetAncestorOf()
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(T, const System::SharedPtr<Aspose::Words::Node>&)
InsertBefore(T, const System::SharedPtr<Aspose::Words::Node>&)
Is(const System::TypeInfo&) const override
IsAncestorNode(const System::SharedPtr<Aspose::Words::Node>&)
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(T)
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(T)
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_NextNode(const System::SharedPtr<Aspose::Words::Node>&)
set_PrevNode(const System::SharedPtr<Aspose::Words::Node>&)
set_Type(Aspose::Words::BuildingBlocks::BuildingBlockType)Setter for Aspose::Words::BuildingBlocks::BuildingBlock::get_Type.
SetParent(const System::SharedPtr<Aspose::Words::Node>&)
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()

Remarks

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.

Examples

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>();
    doc->set_GlossaryDocument(glossaryDoc);

    // 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");

    glossaryDoc->AppendChild(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()));

    block->set_Guid(System::Guid::NewGuid());

    // 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);
    block->Accept(visitor);

    // 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]()
    {
        System::Guid::Parse(System::ObjectExt::ToString(customBlock->get_Guid()));
    };

    // 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
{
public:
    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_Behavior(BuildingBlockBehavior::Paragraph);
        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.");
        block->set_Gallery(BuildingBlockGallery::QuickParts);

        // 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);
        block->AppendChild(section);
        block->get_FirstSection()->EnsureMinimum();

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

        return VisitorAction::Continue;
    }

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

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

See Also

Aspose::Words::BuildingBlocks::BuildingBlockCollection class