Aspose::Words::BuildingBlocks Namespace Reference

Detailed Description

The Aspose.Words.BuildingBlocks namespace provides classes that allow to access and use AutoText, AutoCorrect entries and Building Blocks in a document.

Classes

class  BuildingBlock
 Represents a glossary document entry such as a Building Block, AutoText or an AutoCorrect entry. More...
 
class  BuildingBlockCollection
 A collection of BuildingBlock objects in the document. More...
 
class  GlossaryDocument
 Represents the root element for a glossary document within a Word document. A glossary document is a storage for AutoText, AutoCorrect entries and Building Blocks. More...
 

Enumerations

enum class  BuildingBlockBehavior
 Specifies the behavior that shall be applied to the contents of the building block when it is inserted into the main document. More...
 
enum class  BuildingBlockGallery
 Specifies the predefined gallery into which a building block is classified. More...
 
enum class  BuildingBlockType
 Specifies a building block type. The type might affect the visibility and behavior of the building block in Microsoft Word. More...
 

Enumeration Type Documentation

◆ BuildingBlockBehavior

Specifies the behavior that shall be applied to the contents of the building block when it is inserted into the main document.

Corresponds to the ST_DocPartBehavior type in OOXML.

See also
Aspose::Words::BuildingBlocks::BuildingBlock::get_Behavior
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]()
{
};
// 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);
}
VisitorAction VisitBuildingBlockEnd(SharedPtr<BuildingBlock> block) override
{
mBuilder->Append(String(u"Visited ") + block->get_Name() + u"\r\n");
}
private:
SharedPtr<System::Text::StringBuilder> mBuilder;
SharedPtr<GlossaryDocument> mGlossaryDoc;
};
Enumerator
Content 

Specifies that the building block shall be inserted as inline content.

Paragraph 

Specifies that the building block shall be inserted into its own paragraph.

Page 

Specifies that the building block shall be added into its own page.

Default 

Same as Content.

◆ BuildingBlockGallery

Specifies the predefined gallery into which a building block is classified.

Corresponds to the ST_DocPartGallery type in OOXML.

See also
Aspose::Words::BuildingBlocks::BuildingBlock::get_Gallery
Examples

Shows ways of accessing building blocks in a glossary document.

void GlossaryDocument_()
{
auto doc = MakeObject<Document>();
auto glossaryDoc = MakeObject<GlossaryDocument>();
for (int i = 1; i <= 5; ++i)
{
auto block = MakeObject<BuildingBlock>(glossaryDoc);
block->set_Name(String(u"Block ") + System::Convert::ToString(i));
glossaryDoc->AppendChild(block);
}
ASSERT_EQ(5, glossaryDoc->get_BuildingBlocks()->get_Count());
doc->set_GlossaryDocument(glossaryDoc);
// There are various ways of accessing building blocks.
// 1 - Get the first/last building blocks in the collection:
ASSERT_EQ(u"Block 1", glossaryDoc->get_FirstBuildingBlock()->get_Name());
ASSERT_EQ(u"Block 5", glossaryDoc->get_LastBuildingBlock()->get_Name());
// 2 - Get a building block by index:
ASSERT_EQ(u"Block 2", glossaryDoc->get_BuildingBlocks()->idx_get(1)->get_Name());
ASSERT_EQ(u"Block 3", glossaryDoc->get_BuildingBlocks()->ToArray()->idx_get(2)->get_Name());
// 3 - Get the first building block that matches a gallery, name and category:
ASSERT_EQ(u"Block 4", glossaryDoc->GetBuildingBlock(BuildingBlockGallery::All, u"(Empty Category)", u"Block 4")->get_Name());
// We will do that using a custom visitor,
// which will give every BuildingBlock in the GlossaryDocument a unique GUID
auto visitor = MakeObject<ExBuildingBlocks::GlossaryDocVisitor>();
glossaryDoc->Accept(visitor);
std::cout << visitor->GetText() << std::endl;
// In Microsoft Word, we can access the building blocks via "Insert" -> "Quick Parts" -> "Building Blocks Organizer".
doc->Save(ArtifactsDir + u"BuildingBlocks.GlossaryDocument.dotx");
}
class GlossaryDocVisitor : public DocumentVisitor
{
public:
GlossaryDocVisitor()
{
mBlocksByGuid = MakeObject<System::Collections::Generic::Dictionary<System::Guid, SharedPtr<BuildingBlock>>>();
mBuilder = MakeObject<System::Text::StringBuilder>();
}
String GetText()
{
return mBuilder->ToString();
}
SharedPtr<System::Collections::Generic::Dictionary<System::Guid, SharedPtr<BuildingBlock>>> GetDictionary()
{
return mBlocksByGuid;
}
VisitorAction VisitGlossaryDocumentStart(SharedPtr<GlossaryDocument> glossary) override
{
mBuilder->AppendLine(u"Glossary document found!");
}
VisitorAction VisitGlossaryDocumentEnd(SharedPtr<GlossaryDocument> glossary) override
{
mBuilder->AppendLine(u"Reached end of glossary!");
mBuilder->AppendLine(String(u"BuildingBlocks found: ") + mBlocksByGuid->get_Count());
}
VisitorAction VisitBuildingBlockStart(SharedPtr<BuildingBlock> block) override
{
block->set_Guid(System::Guid::NewGuid());
mBlocksByGuid->Add(block->get_Guid(), block);
}
VisitorAction VisitBuildingBlockEnd(SharedPtr<BuildingBlock> block) override
{
mBuilder->AppendLine(String(u"\tVisited block \"") + block->get_Name() + u"\"");
mBuilder->AppendLine(String(u"\t Type: ") + System::ObjectExt::ToString(block->get_Type()));
mBuilder->AppendLine(String(u"\t Gallery: ") + System::ObjectExt::ToString(block->get_Gallery()));
mBuilder->AppendLine(String(u"\t Behavior: ") + System::ObjectExt::ToString(block->get_Behavior()));
mBuilder->AppendLine(String(u"\t Description: ") + block->get_Description());
}
private:
SharedPtr<System::Collections::Generic::Dictionary<System::Guid, SharedPtr<BuildingBlock>>> mBlocksByGuid;
SharedPtr<System::Text::StringBuilder> mBuilder;
};
Enumerator
All 

Specifies that this glossary document entry shall be associated with all possible gallery classification values.

AutoText 
Bibliography 
CoverPage 
CustomAutoText 
CustomBibliography 
CustomCoverPage 
CustomEquations 
CustomFooters 
CustomHeaders 
Custom1 
Custom2 
Custom3 
Custom4 
Custom5 
CustomPageNumber 
CustomPageNumberAtBottom 
CustomPageNumberAtMargin 
CustomPageNumberAtTop 
CustomQuickParts 
CustomTableOfContents 
CustomTables 
CustomTextBox 
CustomWatermarks 
NoGallery 
QuickParts 
Equations 
Footers 
Headers 
PageNumber 
PageNumberAtBottom 
PageNumberAtMargin 
PageNumberAtTop 
StructuredDocumentTagPlaceholderText 
TableOfContents 
Tables 
TextBox 
Watermarks 
Default 

Same as All.

◆ BuildingBlockType

Specifies a building block type. The type might affect the visibility and behavior of the building block in Microsoft Word.

Corresponds to the ST_DocPartType type in OOXML.

See also
Aspose::Words::BuildingBlocks::BuildingBlock::get_Type
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]()
{
};
// 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);
}
VisitorAction VisitBuildingBlockEnd(SharedPtr<BuildingBlock> block) override
{
mBuilder->Append(String(u"Visited ") + block->get_Name() + u"\r\n");
}
private:
SharedPtr<System::Text::StringBuilder> mBuilder;
SharedPtr<GlossaryDocument> mGlossaryDoc;
};
Enumerator
None 

No type information is specified for the building block.

AutomaticallyReplaceNameWithContent 

Allows the building block to be automatically inserted into the document whenever its name is entered into an application.

StructuredDocumentTagPlaceholderText 

The building block is a structured document tag placeholder text.

FormFieldHelpText 

The building block is a form field help text.

Normal 

The building block is a normal (i.e. regular) glossary document entry.

AutoCorrect 

The building block is associated with the spelling and grammar tools.

AutoText 

The building block is an AutoText entry.

All 

The building block is associated with all types.

Default 

Save as None.