Aspose::Words::DocumentBuilder class

DocumentBuilder class

Provides methods to insert text, images and other content, specify font, paragraph and section formatting. To learn more, visit the Document Builder Overview documentation article.

class DocumentBuilder : public Aspose::Words::IRunAttrSource,
                        public Aspose::Words::IParaAttrSource,
                        public Aspose::Words::IRowAttrSource,
                        public Aspose::Words::ICellAttrSource

Methods

MethodDescription
DeleteRow(int32_t, int32_t)Deletes a row from a table.
DocumentBuilder()Initializes a new instance of this class.
DocumentBuilder(const System::SharedPtr<Aspose::Words::DocumentBuilderOptions>&)Initializes a new instance of this class.
DocumentBuilder(const System::SharedPtr<Aspose::Words::Document>&)Initializes a new instance of this class.
DocumentBuilder(const System::SharedPtr<Aspose::Words::Document>&, const System::SharedPtr<Aspose::Words::DocumentBuilderOptions>&)Initializes a new instance of this class.
EndBookmark(const System::String&)Marks the current position in the document as a bookmark end.
EndColumnBookmark(const System::String&)Marks the current position in the document as a column bookmark end. The position must be in a table cell.
EndEditableRange()Marks the current position in the document as an editable range end.
EndEditableRange(const System::SharedPtr<Aspose::Words::EditableRangeStart>&)Marks the current position in the document as an editable range end.
EndRow()Ends a table row in the document.
EndTable()Ends a table in the document.
get_Bold()True if the font is formatted as bold.
get_CellFormat()Returns an object that represents current table cell formatting properties.
get_CurrentNode()Gets the node that is currently selected in this DocumentBuilder.
get_CurrentParagraph()Gets the paragraph that is currently selected in this DocumentBuilder.
get_CurrentSection()Gets the section that is currently selected in this DocumentBuilder.
get_CurrentStory()Gets the story that is currently selected in this DocumentBuilder.
get_CurrentStructuredDocumentTag()Gets the structured document tag that is currently selected in this DocumentBuilder.
get_Document() constGets or sets the Document object that this object is attached to.
get_Font()Returns an object that represents current font formatting properties.
get_IsAtEndOfParagraph()Returns true if the cursor is at the end of the current paragraph.
get_IsAtEndOfStructuredDocumentTag()Returns true if the cursor is at the end of a structured document tag.
get_IsAtStartOfParagraph()Returns true if the cursor is at the beginning of the current paragraph (no text before the cursor).
get_Italic()True if the font is formatted as italic.
get_ListFormat()Returns an object that represents current list formatting properties.
get_PageSetup()Returns an object that represents current page setup and section properties.
get_ParagraphFormat()Returns an object that represents current paragraph formatting properties.
get_RowFormat()Returns an object that represents current table row formatting properties.
get_Underline()Gets/sets underline type for the current font.
GetType() const override
InsertBreak(Aspose::Words::BreakType)Inserts a break of the specified type into the document.
InsertCell()Inserts a table cell into the document.
InsertChart(Aspose::Words::Drawing::Charts::ChartType, double, double)Inserts an chart object into the document and scales it to the specified size.
InsertChart(Aspose::Words::Drawing::Charts::ChartType, Aspose::Words::Drawing::RelativeHorizontalPosition, double, Aspose::Words::Drawing::RelativeVerticalPosition, double, double, double, Aspose::Words::Drawing::WrapType)Inserts an chart object into the document and scales it to the specified size.
InsertCheckBox(const System::String&, bool, int32_t)Inserts a checkbox form field at the current position.
InsertCheckBox(const System::String&, bool, bool, int32_t)Inserts a checkbox form field at the current position.
InsertComboBox(const System::String&, const System::ArrayPtr<System::String>&, int32_t)Inserts a combobox form field at the current position.
InsertDocument(const System::SharedPtr<Aspose::Words::Document>&, Aspose::Words::ImportFormatMode)Inserts a document at the cursor position.
InsertDocument(const System::SharedPtr<Aspose::Words::Document>&, Aspose::Words::ImportFormatMode, const System::SharedPtr<Aspose::Words::ImportFormatOptions>&)Inserts a document at the cursor position.
InsertDocumentInline(const System::SharedPtr<Aspose::Words::Document>&, Aspose::Words::ImportFormatMode, const System::SharedPtr<Aspose::Words::ImportFormatOptions>&)Inserts a document inline at the cursor position.
InsertField(Aspose::Words::Fields::FieldType, bool)Inserts a Word field into a document and optionally updates the field result.
InsertField(const System::String&)Inserts a Word field into a document and updates the field result.
InsertField(const System::String&, const System::String&)Inserts a Word field into a document without updating the field result.
InsertFootnote(Aspose::Words::Notes::FootnoteType, const System::String&)Inserts a footnote or endnote into the document.
InsertFootnote(Aspose::Words::Notes::FootnoteType, const System::String&, const System::String&)Inserts a footnote or endnote into the document.
InsertForms2OleControl(const System::SharedPtr<Aspose::Words::Drawing::Ole::Forms2OleControl>&)Inserts Forms2OleControl object into current position.
InsertGroupShape(const System::ArrayPtr<System::SharedPtr<Aspose::Words::Drawing::ShapeBase>>&)Groups the shapes passed as a parameter into a new GroupShape node which is inserted into the current position.
InsertGroupShape(double, double, double, double, const System::ArrayPtr<System::SharedPtr<Aspose::Words::Drawing::ShapeBase>>&)Groups the shapes passed as a parameter into a new GroupShape node of the specified size which is inserted into the specified position.
InsertHorizontalRule()Inserts a horizontal rule shape into the document.
InsertHtml(const System::String&)Inserts an HTML string into the document.
InsertHtml(const System::String&, bool)Inserts an HTML string into the document.
InsertHtml(const System::String&, Aspose::Words::HtmlInsertOptions)Inserts an HTML string into the document. Allows to specify additional options.
InsertHyperlink(const System::String&, const System::String&, bool)Inserts a hyperlink into the document.
InsertImage(const System::SharedPtr<System::Drawing::Image>&)Inserts an image from a Image object into the document. The image is inserted inline and at 100% scale.
InsertImage(const System::String&)Inserts an image from a file or URL into the document. The image is inserted inline and at 100% scale.
InsertImage(const System::SharedPtr<System::IO::Stream>&)Inserts an image from a stream into the document. The image is inserted inline and at 100% scale.
InsertImage(const System::ArrayPtr<uint8_t>&)Inserts an image from a byte array into the document. The image is inserted inline and at 100% scale.
InsertImage(const System::SharedPtr<System::Drawing::Image>&, double, double)Inserts an inline image from a Image object into the document and scales it to the specified size.
InsertImage(const System::String&, double, double)Inserts an inline image from a file or URL into the document and scales it to the specified size.
InsertImage(const System::SharedPtr<System::IO::Stream>&, double, double)Inserts an inline image from a stream into the document and scales it to the specified size.
InsertImage(const System::ArrayPtr<uint8_t>&, double, double)Inserts an inline image from a byte array into the document and scales it to the specified size.
InsertImage(const System::SharedPtr<System::Drawing::Image>&, Aspose::Words::Drawing::RelativeHorizontalPosition, double, Aspose::Words::Drawing::RelativeVerticalPosition, double, double, double, Aspose::Words::Drawing::WrapType)Inserts an image from a Image object at the specified position and size.
InsertImage(const System::String&, Aspose::Words::Drawing::RelativeHorizontalPosition, double, Aspose::Words::Drawing::RelativeVerticalPosition, double, double, double, Aspose::Words::Drawing::WrapType)Inserts an image from a file or URL at the specified position and size.
InsertImage(const System::SharedPtr<System::IO::Stream>&, Aspose::Words::Drawing::RelativeHorizontalPosition, double, Aspose::Words::Drawing::RelativeVerticalPosition, double, double, double, Aspose::Words::Drawing::WrapType)Inserts an image from a stream at the specified position and size.
InsertImage(const System::ArrayPtr<uint8_t>&, Aspose::Words::Drawing::RelativeHorizontalPosition, double, Aspose::Words::Drawing::RelativeVerticalPosition, double, double, double, Aspose::Words::Drawing::WrapType)Inserts an image from a byte array at the specified position and size.
InsertImage(std::basic_istream<CharType, Traits>&)
InsertImage(std::basic_istream<CharType, Traits>&, double, double)
InsertImage(std::basic_istream<CharType, Traits>&, Aspose::Words::Drawing::RelativeHorizontalPosition, double, Aspose::Words::Drawing::RelativeVerticalPosition, double, double, double, Aspose::Words::Drawing::WrapType)
InsertNode(const System::SharedPtr<Aspose::Words::Node>&)Inserts a node before the cursor.
InsertOleObject(const System::SharedPtr<System::IO::Stream>&, const System::String&, bool, const System::SharedPtr<System::IO::Stream>&)Inserts an embedded OLE object from a stream into the document.
InsertOleObject(const System::String&, bool, bool, const System::SharedPtr<System::IO::Stream>&)Inserts an embedded or linked OLE object from a file into the document. Detects OLE object type using file extension.
InsertOleObject(const System::String&, const System::String&, bool, bool, const System::SharedPtr<System::IO::Stream>&)Inserts an embedded or linked OLE object from a file into the document. Detects OLE object type using given progID parameter.
InsertOleObject(std::basic_istream<CharType, Traits>&, System::String, bool, std::basic_istream<CharType, Traits>&)
InsertOleObject(System::String, bool, bool, std::basic_istream<CharType, Traits>&)
InsertOleObject(System::String, System::String, bool, bool, std::basic_istream<CharType, Traits>&)
InsertOleObjectAsIcon(const System::String&, bool, const System::String&, const System::String&)Inserts an embedded or linked OLE object as icon into the document. Allows to specify icon file and caption. Detects OLE object type using file extension.
InsertOleObjectAsIcon(const System::String&, const System::String&, bool, const System::String&, const System::String&)Inserts an embedded or linked OLE object as icon into the document. Allows to specify icon file and caption. Detects OLE object type using given progID parameter.
InsertOleObjectAsIcon(const System::SharedPtr<System::IO::Stream>&, const System::String&, const System::String&, const System::String&)Inserts an embedded OLE object as icon from a stream into the document. Allows to specify icon file and caption. Detects OLE object type using given progID parameter.
InsertOleObjectAsIcon(std::basic_istream<CharType, Traits>&, System::String, System::String, System::String)
InsertOnlineVideo(const System::String&, double, double)Inserts an online video object into the document and scales it to the specified size.
InsertOnlineVideo(const System::String&, Aspose::Words::Drawing::RelativeHorizontalPosition, double, Aspose::Words::Drawing::RelativeVerticalPosition, double, double, double, Aspose::Words::Drawing::WrapType)Inserts an online video object into the document and scales it to the specified size.
InsertOnlineVideo(const System::String&, const System::String&, const System::ArrayPtr<uint8_t>&, double, double)Inserts an online video object into the document and scales it to the specified size.
InsertOnlineVideo(const System::String&, const System::String&, const System::ArrayPtr<uint8_t>&, Aspose::Words::Drawing::RelativeHorizontalPosition, double, Aspose::Words::Drawing::RelativeVerticalPosition, double, double, double, Aspose::Words::Drawing::WrapType)Inserts an online video object into the document and scales it to the specified size.
InsertParagraph()Inserts a paragraph break into the document.
InsertShape(Aspose::Words::Drawing::ShapeType, double, double)Inserts inline shape with specified type and size.
InsertShape(Aspose::Words::Drawing::ShapeType, Aspose::Words::Drawing::RelativeHorizontalPosition, double, Aspose::Words::Drawing::RelativeVerticalPosition, double, double, double, Aspose::Words::Drawing::WrapType)Inserts free-floating shape with specified position, size and text wrap type.
InsertSignatureLine(const System::SharedPtr<Aspose::Words::SignatureLineOptions>&)Inserts a signature line at the current position.
InsertSignatureLine(const System::SharedPtr<Aspose::Words::SignatureLineOptions>&, Aspose::Words::Drawing::RelativeHorizontalPosition, double, Aspose::Words::Drawing::RelativeVerticalPosition, double, Aspose::Words::Drawing::WrapType)Inserts a signature line at the specified position.
InsertStructuredDocumentTag(Aspose::Words::Markup::SdtType)Inserts a StructuredDocumentTag into the document.
InsertStyleSeparator()Inserts style separator into the document.
InsertTableOfContents(const System::String&)Inserts a TOC (table of contents) field into the document.
InsertTextInput(const System::String&, Aspose::Words::Fields::TextFormFieldType, const System::String&, const System::String&, int32_t)Inserts a text form field at the current position.
Is(const System::TypeInfo&) const override
MoveTo(const System::SharedPtr<Aspose::Words::Node>&)Moves the cursor to an inline node or to the end of a paragraph.
MoveToBookmark(const System::String&)Moves the cursor to a bookmark.
MoveToBookmark(const System::String&, bool, bool)Moves the cursor to a bookmark with greater precision.
MoveToCell(int32_t, int32_t, int32_t, int32_t)Moves the cursor to a table cell in the current section.
MoveToDocumentEnd()Moves the cursor to the end of the document.
MoveToDocumentStart()Moves the cursor to the beginning of the document.
MoveToField(const System::SharedPtr<Aspose::Words::Fields::Field>&, bool)Moves the cursor to a field in the document.
MoveToHeaderFooter(Aspose::Words::HeaderFooterType)Moves the cursor to the beginning of a header or footer in the current section.
MoveToMergeField(const System::String&)Moves the cursor to a position just beyond the specified merge field and removes the merge field.
MoveToMergeField(const System::String&, bool, bool)Moves the merge field to the specified merge field.
MoveToParagraph(int32_t, int32_t)Moves the cursor to a paragraph in the current section.
MoveToSection(int32_t)Moves the cursor to the beginning of the body in a specified section.
MoveToStructuredDocumentTag(int32_t, int32_t)Moves the cursor to a structured document tag in the current section.
MoveToStructuredDocumentTag(const System::SharedPtr<Aspose::Words::Markup::StructuredDocumentTag>&, int32_t)Moves the cursor to the structured document tag.
PopFont()Retrieves character formatting previously saved on the stack.
PushFont()Saves current character formatting onto the stack.
set_Bold(bool)Setter for Aspose::Words::DocumentBuilder::get_Bold.
set_Document(const System::SharedPtr<Aspose::Words::Document>&)Setter for Aspose::Words::DocumentBuilder::get_Document.
set_Italic(bool)Setter for Aspose::Words::DocumentBuilder::get_Italic.
set_Underline(Aspose::Words::Underline)Setter for Aspose::Words::DocumentBuilder::get_Underline.
StartBookmark(const System::String&)Marks the current position in the document as a bookmark start.
StartColumnBookmark(const System::String&)Marks the current position in the document as a column bookmark start. The position must be in a table cell.
StartEditableRange()Marks the current position in the document as an editable range start.
StartTable()Starts a table in the document.
static Type()
Write(const System::String&)Inserts a string into the document at the current insert position.
Writeln(const System::String&)Inserts a string and a paragraph break into the document.
Writeln()Inserts a paragraph break into the document.

Remarks

DocumentBuilder makes the process of building a Document easier. Document is a composite object consisting of a tree of nodes and while inserting content nodes directly into the tree is possible, it requires good understanding of the tree structure. DocumentBuilder is a “facade” for the complex structure of Document and allows to insert content and formatting quickly and easily.

Create a DocumentBuilder and associate it with a Document.

The DocumentBuilder has an internal cursor where the text will be inserted when you call Write(), Writeln(), InsertBreak() and other methods. You can navigate the DocumentBuilder cursor to a different location in a document using various MoveToXXX methods.

Use the Font property to specify character formatting that will apply to all text inserted from the current position in the document onwards.

Use the ParagraphFormat property to specify paragraph formatting for the current and all paragraphs that will be inserted.

Use the PageSetup property to specify page and section properties for the current section and all section that will be inserted.

Use the CellFormat and RowFormat properties to specify formatting properties for table cells and rows. User the InsertCell and EndRow methods to build a table.

Note that Font, ParagraphFormat and PageSetup properties are updated whenever you navigate to a different place in the document to reflect formatting properties available at the new location.

Examples

Shows how to create headers and footers in a document using DocumentBuilder.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);

// Specify that we want different headers and footers for first, even and odd pages.
builder->get_PageSetup()->set_DifferentFirstPageHeaderFooter(true);
builder->get_PageSetup()->set_OddAndEvenPagesHeaderFooter(true);

// Create the headers, then add three pages to the document to display each header type.
builder->MoveToHeaderFooter(HeaderFooterType::HeaderFirst);
builder->Write(u"Header for the first page");
builder->MoveToHeaderFooter(HeaderFooterType::HeaderEven);
builder->Write(u"Header for even pages");
builder->MoveToHeaderFooter(HeaderFooterType::HeaderPrimary);
builder->Write(u"Header for all other pages");

builder->MoveToSection(0);
builder->Writeln(u"Page1");
builder->InsertBreak(BreakType::PageBreak);
builder->Writeln(u"Page2");
builder->InsertBreak(BreakType::PageBreak);
builder->Writeln(u"Page3");

doc->Save(ArtifactsDir + u"DocumentBuilder.HeadersAndFooters.docx");

Shows how to build a table with custom borders.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);

builder->StartTable();

// Setting table formatting options for a document builder
// will apply them to every row and cell that we add with it.
builder->get_ParagraphFormat()->set_Alignment(ParagraphAlignment::Center);

builder->get_CellFormat()->ClearFormatting();
builder->get_CellFormat()->set_Width(150);
builder->get_CellFormat()->set_VerticalAlignment(CellVerticalAlignment::Center);
builder->get_CellFormat()->get_Shading()->set_BackgroundPatternColor(System::Drawing::Color::get_GreenYellow());
builder->get_CellFormat()->set_WrapText(false);
builder->get_CellFormat()->set_FitText(true);

builder->get_RowFormat()->ClearFormatting();
builder->get_RowFormat()->set_HeightRule(HeightRule::Exactly);
builder->get_RowFormat()->set_Height(50);
builder->get_RowFormat()->get_Borders()->set_LineStyle(LineStyle::Engrave3D);
builder->get_RowFormat()->get_Borders()->set_Color(System::Drawing::Color::get_Orange());

builder->InsertCell();
builder->Write(u"Row 1, Col 1");

builder->InsertCell();
builder->Write(u"Row 1, Col 2");
builder->EndRow();

// Changing the formatting will apply it to the current cell,
// and any new cells that we create with the builder afterward.
// This will not affect the cells that we have added previously.
builder->get_CellFormat()->get_Shading()->ClearFormatting();

builder->InsertCell();
builder->Write(u"Row 2, Col 1");

builder->InsertCell();
builder->Write(u"Row 2, Col 2");

builder->EndRow();

// Increase row height to fit the vertical text.
builder->InsertCell();
builder->get_RowFormat()->set_Height(150);
builder->get_CellFormat()->set_Orientation(TextOrientation::Upward);
builder->Write(u"Row 3, Col 1");

builder->InsertCell();
builder->get_CellFormat()->set_Orientation(TextOrientation::Downward);
builder->Write(u"Row 3, Col 2");

builder->EndRow();
builder->EndTable();

doc->Save(ArtifactsDir + u"DocumentBuilder.InsertTable.docx");

Shows how to use a document builder to create a table.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);

// Start the table, then populate the first row with two cells.
builder->StartTable();
builder->InsertCell();
builder->Write(u"Row 1, Cell 1.");
builder->InsertCell();
builder->Write(u"Row 1, Cell 2.");

// Call the builder's "EndRow" method to start a new row.
builder->EndRow();
builder->InsertCell();
builder->Write(u"Row 2, Cell 1.");
builder->InsertCell();
builder->Write(u"Row 2, Cell 2.");
builder->EndTable();

doc->Save(ArtifactsDir + u"DocumentBuilder.CreateTable.docx");

See Also

Aspose::Words::DocumentBase class Aspose::Words::DocumentBuilderOptions class