Aspose::Words::DocumentBuilder Class Reference

Detailed Description

Provides methods to insert text, images and other content, specify font, paragraph and section formatting.

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 headers and footers different for first, even and odd pages
builder->get_PageSetup()->set_DifferentFirstPageHeaderFooter(true);
builder->get_PageSetup()->set_OddAndEvenPagesHeaderFooter(true);
// Create the headers
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");
// Create three pages in the document
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 nice bordered table.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Start building a table
builder->StartTable();
// Set the appropriate paragraph, cell, and row formatting. The formatting properties are preserved
// until they are explicitly modified so there's no need to set them for each row or cell
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();
// Remove the shading (clear background)
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();
builder->InsertCell();
// Make the row height bigger so that a vertically oriented text could fit into cells
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 create a simple table using DocumentBuilder with default formatting.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// We call this method to start building the table
builder->StartTable();
builder->InsertCell();
builder->Write(u"Row 1, Cell 1 Content.");
// Build the second cell
builder->InsertCell();
builder->Write(u"Row 1, Cell 2 Content.");
// Call the following method to end the row and start a new row
builder->EndRow();
// Build the first cell of the second row
builder->InsertCell();
builder->Write(u"Row 2, Cell 1 Content.");
// Build the second cell.
builder->InsertCell();
builder->Write(u"Row 2, Cell 2 Content.");
builder->EndRow();
// Signal that we have finished building the table
builder->EndTable();
// Save the document to disk
doc->Save(ArtifactsDir + u"DocumentBuilder.CreateSimpleTable.docx");

#include <Aspose.Words.Cpp/Model/Document/DocumentBuilder.h>

+ Inheritance diagram for Aspose::Words::DocumentBuilder:

Public Member Functions

 DocumentBuilder ()
 Initializes a new instance of this class. More...
 
 DocumentBuilder (SharedPtr< Document > doc)
 Initializes a new instance of this class. More...
 
SharedPtr< RowDeleteRow (int32_t tableIndex, int32_t rowIndex)
 Deletes a row from a table. More...
 
SharedPtr< BookmarkEndEndBookmark (String bookmarkName)
 Marks the current position in the document as a bookmark end. More...
 
SharedPtr< EditableRangeEndEndEditableRange ()
 Marks the current position in the document as an editable range end. More...
 
SharedPtr< EditableRangeEndEndEditableRange (SharedPtr< EditableRangeStart > start)
 Marks the current position in the document as an editable range end. More...
 
SharedPtr< RowEndRow ()
 Ends a table row in the document. More...
 
SharedPtr< TableEndTable ()
 Ends a table in the document. More...
 
bool get_Bold ()
 True if the font is formatted as bold. More...
 
SharedPtr< CellFormatget_CellFormat ()
 Returns an object that represents current table cell formatting properties. More...
 
SharedPtr< Nodeget_CurrentNode ()
 Gets the node that is currently selected in this DocumentBuilder. More...
 
SharedPtr< Paragraphget_CurrentParagraph ()
 Gets the paragraph that is currently selected in this DocumentBuilder. More...
 
SharedPtr< Sectionget_CurrentSection ()
 Gets the section that is currently selected in this DocumentBuilder. More...
 
SharedPtr< Storyget_CurrentStory ()
 Gets the story that is currently selected in this DocumentBuilder. More...
 
SharedPtr< Documentget_Document () const
 Gets or sets the Document object that this object is attached to. More...
 
SharedPtr< Fontget_Font ()
 Returns an object that represents current font formatting properties. More...
 
bool get_IsAtEndOfParagraph ()
 Returns true if the cursor is at the end of the current paragraph. More...
 
bool get_IsAtStartOfParagraph ()
 Returns true if the cursor is at the beginning of the current paragraph (no text before the cursor). More...
 
bool get_Italic ()
 True if the font is formatted as italic. More...
 
SharedPtr< ListFormatget_ListFormat ()
 Returns an object that represents current list formatting properties. More...
 
SharedPtr< PageSetupget_PageSetup ()
 Returns an object that represents current page setup and section properties. More...
 
SharedPtr< ParagraphFormatget_ParagraphFormat ()
 Returns an object that represents current paragraph formatting properties. More...
 
SharedPtr< RowFormatget_RowFormat ()
 Returns an object that represents current table row formatting properties. More...
 
Underline get_Underline ()
 Gets/sets underline type for the current font. More...
 
virtual const TypeInfoGetType () const override
 
void InsertBreak (BreakType breakType)
 Inserts a break of the specified type into the document. More...
 
SharedPtr< CellInsertCell ()
 Inserts a table cell into the document. More...
 
SharedPtr< ShapeInsertChart (ChartType chartType, RelativeHorizontalPosition horzPos, double left, RelativeVerticalPosition vertPos, double top, double width, double height, WrapType wrapType)
 Inserts an chart object into the document and scales it to the specified size. More...
 
SharedPtr< ShapeInsertChart (ChartType chartType, double width, double height)
 Inserts an chart object into the document and scales it to the specified size. More...
 
SharedPtr< FormFieldInsertCheckBox (String name, bool checkedValue, int32_t size)
 Inserts a checkbox form field at the current position. More...
 
SharedPtr< FormFieldInsertCheckBox (String name, bool defaultValue, bool checkedValue, int32_t size)
 Inserts a checkbox form field at the current position. More...
 
SharedPtr< FormFieldInsertComboBox (String name, ArrayPtr< String > items, int32_t selectedIndex)
 Inserts a combobox form field at the current position. More...
 
SharedPtr< NodeInsertDocument (SharedPtr< Document > srcDoc, ImportFormatMode importFormatMode)
 Inserts a document at the cursor position. More...
 
SharedPtr< NodeInsertDocument (SharedPtr< Document > srcDoc, ImportFormatMode importFormatMode, SharedPtr< ImportFormatOptions > importFormatOptions)
 Inserts a document at the cursor position. More...
 
SharedPtr< FieldInsertField (FieldType fieldType, bool updateField)
 Inserts a Word field into a document and optionally updates the field result. More...
 
SharedPtr< FieldInsertField (String fieldCode)
 Inserts a Word field into a document and updates the field result. More...
 
SharedPtr< FieldInsertField (String fieldCode, String fieldValue)
 Inserts a Word field into a document without updating the field result. More...
 
SharedPtr< FootnoteInsertFootnote (FootnoteType footnoteType, String footnoteText)
 Inserts a footnote or endnote into the document. More...
 
SharedPtr< FootnoteInsertFootnote (FootnoteType footnoteType, String footnoteText, String referenceMark)
 Inserts a footnote or endnote into the document. More...
 
SharedPtr< ShapeInsertHorizontalRule ()
 Inserts a horizontal rule shape into the document. More...
 
void InsertHtml (String html)
 Inserts an HTML string into the document. More...
 
void InsertHtml (String html, bool useBuilderFormatting)
 Inserts an HTML string into the document. More...
 
SharedPtr< FieldInsertHyperlink (String displayText, String urlOrBookmark, bool isBookmark)
 Inserts a hyperlink into the document. More...
 
SharedPtr< ShapeInsertImage (ArrayPtr< uint8_t > imageBytes)
 Inserts an image from a byte array into the document. The image is inserted inline and at 100% scale. More...
 
SharedPtr< ShapeInsertImage (ArrayPtr< uint8_t > imageBytes, RelativeHorizontalPosition horzPos, double left, RelativeVerticalPosition vertPos, double top, double width, double height, WrapType wrapType)
 Inserts an image from a byte array at the specified position and size. More...
 
SharedPtr< ShapeInsertImage (ArrayPtr< uint8_t > imageBytes, double width, double height)
 Inserts an inline image from a byte array into the document and scales it to the specified size. More...
 
SharedPtr< ShapeInsertImage (SharedPtr< Image > image)
 Inserts an image from a .NET Image object into the document. The image is inserted inline and at 100% scale. More...
 
SharedPtr< ShapeInsertImage (SharedPtr< Image > image, RelativeHorizontalPosition horzPos, double left, RelativeVerticalPosition vertPos, double top, double width, double height, WrapType wrapType)
 Inserts an image from a .NET Image object at the specified position and size. More...
 
SharedPtr< ShapeInsertImage (SharedPtr< Image > image, double width, double height)
 Inserts an inline image from a .NET Image object into the document and scales it to the specified size. More...
 
SharedPtr< ShapeInsertImage (SharedPtr< Stream > stream)
 Inserts an image from a stream into the document. The image is inserted inline and at 100% scale. More...
 
SharedPtr< ShapeInsertImage (SharedPtr< Stream > stream, RelativeHorizontalPosition horzPos, double left, RelativeVerticalPosition vertPos, double top, double width, double height, WrapType wrapType)
 Inserts an image from a stream at the specified position and size. More...
 
SharedPtr< ShapeInsertImage (SharedPtr< Stream > stream, double width, double height)
 Inserts an inline image from a stream into the document and scales it to the specified size. More...
 
SharedPtr< ShapeInsertImage (String fileName)
 Inserts an image from a file or URL into the document. The image is inserted inline and at 100% scale. More...
 
SharedPtr< ShapeInsertImage (String fileName, RelativeHorizontalPosition horzPos, double left, RelativeVerticalPosition vertPos, double top, double width, double height, WrapType wrapType)
 Inserts an image from a file or URL at the specified position and size. More...
 
SharedPtr< ShapeInsertImage (String fileName, double width, double height)
 Inserts an inline image from a file or URL into the document and scales it to the specified size. More...
 
void InsertNode (SharedPtr< Node > node)
 Inserts a text level node inside the current paragraph before the cursor. More...
 
SharedPtr< ShapeInsertOleObject (SharedPtr< Stream > stream, String progId, bool asIcon, SharedPtr< Image > presentation)
 Inserts an embedded OLE object from a stream into the document. More...
 
SharedPtr< ShapeInsertOleObject (String fileName, bool isLinked, bool asIcon, SharedPtr< Image > presentation)
 Inserts an embedded or linked OLE object from a file into the document. Detects OLE object type using file extension. More...
 
SharedPtr< ShapeInsertOleObject (String fileName, String progId, bool isLinked, bool asIcon, SharedPtr< Image > presentation)
 Inserts an embedded or linked OLE object from a file into the document. Detects OLE object type using given progID parameter. More...
 
SharedPtr< ShapeInsertOleObjectAsIcon (String fileName, bool isLinked, String iconFile, String iconCaption)
 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. More...
 
SharedPtr< ShapeInsertOnlineVideo (String videoUrl, RelativeHorizontalPosition horzPos, double left, RelativeVerticalPosition vertPos, double top, double width, double height, WrapType wrapType)
 Inserts an online video object into the document and scales it to the specified size. More...
 
SharedPtr< ShapeInsertOnlineVideo (String videoUrl, double width, double height)
 Inserts an online video object into the document and scales it to the specified size. More...
 
SharedPtr< ShapeInsertOnlineVideo (String videoUrl, String videoEmbedCode, ArrayPtr< uint8_t > thumbnailImageBytes, RelativeHorizontalPosition horzPos, double left, RelativeVerticalPosition vertPos, double top, double width, double height, WrapType wrapType)
 Inserts an online video object into the document and scales it to the specified size. More...
 
SharedPtr< ShapeInsertOnlineVideo (String videoUrl, String videoEmbedCode, ArrayPtr< uint8_t > thumbnailImageBytes, double width, double height)
 Inserts an online video object into the document and scales it to the specified size. More...
 
SharedPtr< ParagraphInsertParagraph ()
 Inserts a paragraph break into the document. More...
 
SharedPtr< ShapeInsertShape (ShapeType shapeType, RelativeHorizontalPosition horzPos, double left, RelativeVerticalPosition vertPos, double top, double width, double height, WrapType wrapType)
 Inserts free-floating shape with specified position, size and text wrap type. More...
 
SharedPtr< ShapeInsertShape (ShapeType shapeType, double width, double height)
 Inserts inline shape with specified type and size. More...
 
SharedPtr< ShapeInsertSignatureLine (SharedPtr< SignatureLineOptions > signatureLineOptions)
 Inserts a signature line at the current position. More...
 
SharedPtr< ShapeInsertSignatureLine (SharedPtr< SignatureLineOptions > signatureLineOptions, RelativeHorizontalPosition horzPos, double left, RelativeVerticalPosition vertPos, double top, WrapType wrapType)
 Inserts a signature line at the specified position. More...
 
void InsertStyleSeparator ()
 Inserts style separator into the document. More...
 
SharedPtr< FieldInsertTableOfContents (String switches)
 Inserts a TOC (table of contents) field into the document. More...
 
SharedPtr< FormFieldInsertTextInput (String name, TextFormFieldType type, String format, String fieldValue, int32_t maxLength)
 Inserts a text form field at the current position. More...
 
virtual bool Is (const TypeInfo &target) const override
 
void MoveTo (SharedPtr< Node > node)
 Moves the cursor to an inline node or to the end of a paragraph. More...
 
bool MoveToBookmark (String bookmarkName)
 Moves the cursor to a bookmark. More...
 
bool MoveToBookmark (String bookmarkName, bool isStart, bool isAfter)
 Moves the cursor to a bookmark with greater precision. More...
 
void MoveToCell (int32_t tableIndex, int32_t rowIndex, int32_t columnIndex, int32_t characterIndex)
 Moves the cursor to a table cell in the current section. More...
 
void MoveToDocumentEnd ()
 Moves the cursor to the end of the document. More...
 
void MoveToDocumentStart ()
 Moves the cursor to the beginning of the document. More...
 
void MoveToField (SharedPtr< Field > field, bool isAfter)
 Moves the cursor to a field in the document. More...
 
void MoveToHeaderFooter (HeaderFooterType headerFooterType)
 Moves the cursor to the beginning of a header or footer in the current section. More...
 
bool MoveToMergeField (String fieldName)
 Moves the cursor to a position just beyond the specified merge field and removes the merge field. More...
 
bool MoveToMergeField (String fieldName, bool isAfter, bool isDeleteField)
 Moves the merge field to the specified merge field. More...
 
void MoveToParagraph (int32_t paragraphIndex, int32_t characterIndex)
 Moves the cursor to a paragraph in the current section. More...
 
void MoveToSection (int32_t sectionIndex)
 Moves the cursor to the beginning of the body in a specified section. More...
 
void PopFont ()
 Retrieves character formatting previously saved on the stack. More...
 
void PushFont ()
 Saves current character formatting onto the stack. More...
 
void set_Bold (bool value)
 Setter for get_Bold. More...
 
void set_Document (SharedPtr< Document > value)
 Setter for get_Document. More...
 
void set_Italic (bool value)
 Setter for get_Italic. More...
 
void set_Underline (Underline value)
 Setter for get_Underline. More...
 
SharedPtr< BookmarkStartStartBookmark (String bookmarkName)
 Marks the current position in the document as a bookmark start. More...
 
SharedPtr< EditableRangeStartStartEditableRange ()
 Marks the current position in the document as an editable range start. More...
 
SharedPtr< TableStartTable ()
 Starts a table in the document. More...
 
void Write (String text)
 Inserts a string into the document at the current insert position. More...
 
void Writeln ()
 Inserts a paragraph break into the document. More...
 
void Writeln (String text)
 Inserts a string and a paragraph break into the document. More...
 

Static Public Member Functions

static const TypeInfoType ()
 

Constructor & Destructor Documentation

◆ DocumentBuilder() [1/2]

Aspose::Words::DocumentBuilder::DocumentBuilder ( )

Initializes a new instance of this class.

◆ DocumentBuilder() [2/2]

Aspose::Words::DocumentBuilder::DocumentBuilder ( System::SharedPtr< Aspose::Words::Document doc)

Initializes a new instance of this class.

Parameters
docThe Document object to attach to.
Examples

Inserts formatted text using DocumentBuilder.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Specify font formatting before adding text
SharedPtr<Aspose::Words::Font> font = builder->get_Font();
font->set_Size(16);
font->set_Bold(true);
font->set_Name(u"Courier New");
font->set_Underline(Underline::Dash);
builder->Write(u"Hello world!");

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 headers and footers different for first, even and odd pages
builder->get_PageSetup()->set_DifferentFirstPageHeaderFooter(true);
builder->get_PageSetup()->set_OddAndEvenPagesHeaderFooter(true);
// Create the headers
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");
// Create three pages in the document
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 insert a Table of contents (TOC) into a document using heading styles as entries.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Insert a table of contents at the beginning of the document,
// and set it to pick up paragraphs with headings of levels 1 to 3 and entries to act like hyperlinks
builder->InsertTableOfContents(u"\\o \"1-3\" \\h \\z \\u");
// Start the actual document content on the second page
builder->InsertBreak(BreakType::PageBreak);
// Build a document with complex structure by applying different heading styles thus creating TOC entries
// The heading levels we use below will affect the list levels in which these items will appear in the TOC,
// and only levels 1-3 will be picked up by our TOC due to its settings
builder->get_ParagraphFormat()->set_StyleIdentifier(StyleIdentifier::Heading1);
builder->Writeln(u"Heading 1");
builder->get_ParagraphFormat()->set_StyleIdentifier(StyleIdentifier::Heading2);
builder->Writeln(u"Heading 1.1");
builder->Writeln(u"Heading 1.2");
builder->get_ParagraphFormat()->set_StyleIdentifier(StyleIdentifier::Heading1);
builder->Writeln(u"Heading 2");
builder->Writeln(u"Heading 3");
builder->get_ParagraphFormat()->set_StyleIdentifier(StyleIdentifier::Heading2);
builder->Writeln(u"Heading 3.1");
builder->get_ParagraphFormat()->set_StyleIdentifier(StyleIdentifier::Heading3);
builder->Writeln(u"Heading 3.1.1");
builder->Writeln(u"Heading 3.1.2");
builder->Writeln(u"Heading 3.1.3");
builder->get_ParagraphFormat()->set_StyleIdentifier(StyleIdentifier::Heading2);
builder->Writeln(u"Heading 3.2");
builder->Writeln(u"Heading 3.3");
// Call the method below to update the TOC and save
doc->UpdateFields();
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertToc.docx");

Member Function Documentation

◆ DeleteRow()

System::SharedPtr<Aspose::Words::Tables::Row> Aspose::Words::DocumentBuilder::DeleteRow ( int32_t  tableIndex,
int32_t  rowIndex 
)

Deletes a row from a table.

If the cursor is inside the row that is being deleted, the cursor is moved out to the next row or to the next paragraph after the table.

If you delete a row from a table that contains only one row, the whole table is deleted.

For the index parameters, when index is greater than or equal to 0, it specifies an index from the beginning with 0 being the first element. When index is less than 0, it specified an index from the end with -1 being the last element.

Parameters
tableIndexThe index of the table.
rowIndexThe index of the row in the table.
Returns
The row node that was just removed.
Examples

Shows how to delete a row from a table.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Insert a table with 2 rows
SharedPtr<Table> table = builder->StartTable();
builder->InsertCell();
builder->Write(u"Cell 1");
builder->InsertCell();
builder->Write(u"Cell 2");
builder->EndRow();
builder->InsertCell();
builder->Write(u"Cell 3");
builder->InsertCell();
builder->Write(u"Cell 4");
builder->EndTable();
ASSERT_EQ(2, table->get_Rows()->get_Count());
// Delete the first row of the first table in the document
builder->DeleteRow(0, 0);
ASSERT_EQ(1, table->get_Rows()->get_Count());

◆ EndBookmark()

System::SharedPtr<Aspose::Words::BookmarkEnd> Aspose::Words::DocumentBuilder::EndBookmark ( System::String  bookmarkName)

Marks the current position in the document as a bookmark end.

Bookmarks in a document can overlap and span any range. To create a valid bookmark you need to call both StartBookmark() and EndBookmark() with the same bookmarkName parameter.

Badly formed bookmarks or bookmarks with duplicate names will be ignored when the document is saved.

Parameters
bookmarkNameName of the bookmark.
Returns
The bookmark end node that was just created.
Examples

Shows how to add some text into the document and encloses the text in a bookmark using DocumentBuilder.

auto builder = MakeObject<DocumentBuilder>();
builder->StartBookmark(u"MyBookmark");
builder->Writeln(u"Text inside a bookmark.");
builder->EndBookmark(u"MyBookmark");

Shows how to insert a hyperlink referencing a local bookmark.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->StartBookmark(u"Bookmark1");
builder->Write(u"Bookmarked text.");
builder->EndBookmark(u"Bookmark1");
builder->Writeln(u"Some other text");
// Specify font formatting for the hyperlink
builder->get_Font()->set_Color(System::Drawing::Color::get_Blue());
builder->get_Font()->set_Underline(Underline::Single);
// Insert hyperlink
// Switch \o is used to provide hyperlink tip text
builder->InsertHyperlink(u"Hyperlink Text", u"Bookmark1\" \\o \"Hyperlink Tip", true);
// Clear hyperlink formatting
builder->get_Font()->ClearFormatting();
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertHyperlinkToLocalBookmark.docx");

◆ EndEditableRange() [1/2]

System::SharedPtr<Aspose::Words::EditableRangeEnd> Aspose::Words::DocumentBuilder::EndEditableRange ( )

Marks the current position in the document as an editable range end.

Editable range in a document can overlap and span any range. To create a valid editable range you need to call both StartEditableRange and EndEditableRange or EndEditableRange() methods.

Badly formed editable range will be ignored when the document is saved.

Returns
The editable range end node that was just created.

◆ EndEditableRange() [2/2]

System::SharedPtr<Aspose::Words::EditableRangeEnd> Aspose::Words::DocumentBuilder::EndEditableRange ( System::SharedPtr< Aspose::Words::EditableRangeStart start)

Marks the current position in the document as an editable range end.

Use this overload during creating nested editable ranges.

Editable range in a document can overlap and span any range. To create a valid editable range you need to call both StartEditableRange and EndEditableRange or EndEditableRange() methods.

Badly formed editable range will be ignored when the document is saved.

Parameters
startThis editable range start.
Returns
The editable range end node that was just created.

◆ EndRow()

System::SharedPtr<Aspose::Words::Tables::Row> Aspose::Words::DocumentBuilder::EndRow ( )

Ends a table row in the document.

Call EndRow to end a table row. If you call InsertCell immediately after that, then the table continues on a new row.

Use the RowFormat property to specify row formatting.

Returns
The row node that was just finished.
Examples

Creates a table with two columns with cells merged vertically in the first column.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->InsertCell();
builder->get_CellFormat()->set_VerticalMerge(CellMerge::First);
builder->Write(u"Text in merged cells.");
builder->InsertCell();
builder->get_CellFormat()->set_VerticalMerge(CellMerge::None);
builder->Write(u"Text in one cell");
builder->EndRow();
builder->InsertCell();
// This cell is vertically merged to the cell above and should be empty.
builder->get_CellFormat()->set_VerticalMerge(CellMerge::Previous);
builder->InsertCell();
builder->get_CellFormat()->set_VerticalMerge(CellMerge::None);
builder->Write(u"Text in another cell");
builder->EndRow();
builder->EndTable();
doc->Save(ArtifactsDir + u"CellFormat.VerticalMerge.docx");

Shows how to build a nice bordered table.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Start building a table
builder->StartTable();
// Set the appropriate paragraph, cell, and row formatting. The formatting properties are preserved
// until they are explicitly modified so there's no need to set them for each row or cell
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();
// Remove the shading (clear background)
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();
builder->InsertCell();
// Make the row height bigger so that a vertically oriented text could fit into cells
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 build a formatted table that contains 2 rows and 2 columns.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<Table> table = builder->StartTable();
// Insert a cell
builder->InsertCell();
builder->get_CellFormat()->set_VerticalAlignment(CellVerticalAlignment::Center);
builder->Write(u"This is row 1 cell 1");
// Use fixed column widths
table->AutoFit(AutoFitBehavior::FixedColumnWidths);
// Insert a cell
builder->InsertCell();
builder->Write(u"This is row 1 cell 2");
builder->EndRow();
// Insert a cell
builder->InsertCell();
// Apply new row formatting
builder->get_RowFormat()->set_Height(100);
builder->get_RowFormat()->set_HeightRule(HeightRule::Exactly);
builder->get_CellFormat()->set_Orientation(TextOrientation::Upward);
builder->Write(u"This is row 2 cell 1");
// Insert a cell
builder->InsertCell();
builder->get_CellFormat()->set_Orientation(TextOrientation::Downward);
builder->Write(u"This is row 2 cell 2");
builder->EndRow();
builder->EndTable();

◆ EndTable()

System::SharedPtr<Aspose::Words::Tables::Table> Aspose::Words::DocumentBuilder::EndTable ( )

Ends a table in the document.

This method should be called only once after EndRow was called. When called, EndTable moves the cursor out of the current cell to point just after the table.

Returns
The table node that was just finished.
Examples

Shows how to build a nice bordered table.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Start building a table
builder->StartTable();
// Set the appropriate paragraph, cell, and row formatting. The formatting properties are preserved
// until they are explicitly modified so there's no need to set them for each row or cell
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();
// Remove the shading (clear background)
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();
builder->InsertCell();
// Make the row height bigger so that a vertically oriented text could fit into cells
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 build a formatted table that contains 2 rows and 2 columns.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<Table> table = builder->StartTable();
// Insert a cell
builder->InsertCell();
builder->get_CellFormat()->set_VerticalAlignment(CellVerticalAlignment::Center);
builder->Write(u"This is row 1 cell 1");
// Use fixed column widths
table->AutoFit(AutoFitBehavior::FixedColumnWidths);
// Insert a cell
builder->InsertCell();
builder->Write(u"This is row 1 cell 2");
builder->EndRow();
// Insert a cell
builder->InsertCell();
// Apply new row formatting
builder->get_RowFormat()->set_Height(100);
builder->get_RowFormat()->set_HeightRule(HeightRule::Exactly);
builder->get_CellFormat()->set_Orientation(TextOrientation::Upward);
builder->Write(u"This is row 2 cell 1");
// Insert a cell
builder->InsertCell();
builder->get_CellFormat()->set_Orientation(TextOrientation::Downward);
builder->Write(u"This is row 2 cell 2");
builder->EndRow();
builder->EndTable();

Shows how to create a table that contains a single formatted cell.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->StartTable();
builder->InsertCell();
// Set the cell formatting
SharedPtr<CellFormat> cellFormat = builder->get_CellFormat();
cellFormat->set_Width(250);
cellFormat->set_LeftPadding(30);
cellFormat->set_RightPadding(30);
cellFormat->set_TopPadding(30);
cellFormat->set_BottomPadding(30);
builder->Write(u"Formatted cell");
builder->EndRow();
builder->EndTable();
doc->Save(ArtifactsDir + u"DocumentBuilder.DocumentBuilderSetCellFormatting.docx");

◆ get_Bold()

bool Aspose::Words::DocumentBuilder::get_Bold ( )

True if the font is formatted as bold.

Examples

Shows how to fill MERGEFIELDs with data with a DocumentBuilder and without a mail merge.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Insert some MERGEFIELDS, which accept data from columns of the same name in a data source during a mail merge
builder->InsertField(u" MERGEFIELD Chairman ");
builder->InsertField(u" MERGEFIELD ChiefFinancialOfficer ");
builder->InsertField(u" MERGEFIELD ChiefTechnologyOfficer ");
// They can also be filled in manually like this
builder->MoveToMergeField(u"Chairman");
builder->set_Bold(true);
builder->Writeln(u"John Doe");
builder->MoveToMergeField(u"ChiefFinancialOfficer");
builder->set_Italic(true);
builder->Writeln(u"Jane Doe");
builder->MoveToMergeField(u"ChiefTechnologyOfficer");
builder->set_Italic(true);
builder->Writeln(u"John Bloggs");
doc->Save(ArtifactsDir + u"DocumentBuilder.FillMergeFields.docx");

◆ get_CellFormat()

System::SharedPtr<Aspose::Words::Tables::CellFormat> Aspose::Words::DocumentBuilder::get_CellFormat ( )

Returns an object that represents current table cell formatting properties.

Examples

Shows how to build a nice bordered table.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Start building a table
builder->StartTable();
// Set the appropriate paragraph, cell, and row formatting. The formatting properties are preserved
// until they are explicitly modified so there's no need to set them for each row or cell
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();
// Remove the shading (clear background)
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();
builder->InsertCell();
// Make the row height bigger so that a vertically oriented text could fit into cells
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 build a formatted table that contains 2 rows and 2 columns.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<Table> table = builder->StartTable();
// Insert a cell
builder->InsertCell();
builder->get_CellFormat()->set_VerticalAlignment(CellVerticalAlignment::Center);
builder->Write(u"This is row 1 cell 1");
// Use fixed column widths
table->AutoFit(AutoFitBehavior::FixedColumnWidths);
// Insert a cell
builder->InsertCell();
builder->Write(u"This is row 1 cell 2");
builder->EndRow();
// Insert a cell
builder->InsertCell();
// Apply new row formatting
builder->get_RowFormat()->set_Height(100);
builder->get_RowFormat()->set_HeightRule(HeightRule::Exactly);
builder->get_CellFormat()->set_Orientation(TextOrientation::Upward);
builder->Write(u"This is row 2 cell 1");
// Insert a cell
builder->InsertCell();
builder->get_CellFormat()->set_Orientation(TextOrientation::Downward);
builder->Write(u"This is row 2 cell 2");
builder->EndRow();
builder->EndTable();

Shows how to create a table that contains a single formatted cell.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->StartTable();
builder->InsertCell();
// Set the cell formatting
SharedPtr<CellFormat> cellFormat = builder->get_CellFormat();
cellFormat->set_Width(250);
cellFormat->set_LeftPadding(30);
cellFormat->set_RightPadding(30);
cellFormat->set_TopPadding(30);
cellFormat->set_BottomPadding(30);
builder->Write(u"Formatted cell");
builder->EndRow();
builder->EndTable();
doc->Save(ArtifactsDir + u"DocumentBuilder.DocumentBuilderSetCellFormatting.docx");

◆ get_CurrentNode()

System::SharedPtr<Aspose::Words::Node> Aspose::Words::DocumentBuilder::get_CurrentNode ( )

Gets the node that is currently selected in this DocumentBuilder.

CurrentNode is a cursor of DocumentBuilder and points to a Node that is a direct child of a Paragraph. Any insert operations you perform using DocumentBuilder will insert before the CurrentNode.

When the current paragraph is empty or the cursor is positioned just before the end of the paragraph, CurrentNode returns null.

See also
Aspose::Words::DocumentBuilder::get_CurrentParagraph
Examples

Shows how to move a DocumentBuilder to different nodes in a document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Start a bookmark and add content to it using a DocumentBuilder
builder->StartBookmark(u"MyBookmark");
builder->Writeln(u"Bookmark contents.");
builder->EndBookmark(u"MyBookmark");
// The node that the DocumentBuilder is currently at is past the boundaries of the bookmark
ASPOSE_ASSERT_EQ(doc->get_Range()->get_Bookmarks()->idx_get(0)->get_BookmarkEnd(), builder->get_CurrentParagraph()->get_FirstChild());
// If we wish to revise the content of our bookmark with the DocumentBuilder, we can move back to it like this
builder->MoveToBookmark(u"MyBookmark");
// Now we're located between the bookmark's BookmarkStart and BookmarkEnd nodes, so any text the builder adds will be within it
ASPOSE_ASSERT_EQ(doc->get_Range()->get_Bookmarks()->idx_get(0)->get_BookmarkStart(), builder->get_CurrentParagraph()->get_FirstChild());
// We can move the builder to an individual node,
// which in this case will be the first node of the first paragraph, like this
builder->MoveTo(doc->get_FirstSection()->get_Body()->get_FirstParagraph()->GetChildNodes(NodeType::Any, false)->idx_get(0));
ASSERT_EQ(NodeType::BookmarkStart, builder->get_CurrentNode()->get_NodeType());
ASSERT_TRUE(builder->get_IsAtStartOfParagraph());
// A shorter way of moving the very start/end of a document is with these methods
builder->MoveToDocumentEnd();
ASSERT_TRUE(builder->get_IsAtEndOfParagraph());
builder->MoveToDocumentStart();
ASSERT_TRUE(builder->get_IsAtStartOfParagraph());

◆ get_CurrentParagraph()

System::SharedPtr<Aspose::Words::Paragraph> Aspose::Words::DocumentBuilder::get_CurrentParagraph ( )

Gets the paragraph that is currently selected in this DocumentBuilder.

Examples

Shows how to move a DocumentBuilder to different nodes in a document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Start a bookmark and add content to it using a DocumentBuilder
builder->StartBookmark(u"MyBookmark");
builder->Writeln(u"Bookmark contents.");
builder->EndBookmark(u"MyBookmark");
// The node that the DocumentBuilder is currently at is past the boundaries of the bookmark
ASPOSE_ASSERT_EQ(doc->get_Range()->get_Bookmarks()->idx_get(0)->get_BookmarkEnd(), builder->get_CurrentParagraph()->get_FirstChild());
// If we wish to revise the content of our bookmark with the DocumentBuilder, we can move back to it like this
builder->MoveToBookmark(u"MyBookmark");
// Now we're located between the bookmark's BookmarkStart and BookmarkEnd nodes, so any text the builder adds will be within it
ASPOSE_ASSERT_EQ(doc->get_Range()->get_Bookmarks()->idx_get(0)->get_BookmarkStart(), builder->get_CurrentParagraph()->get_FirstChild());
// We can move the builder to an individual node,
// which in this case will be the first node of the first paragraph, like this
builder->MoveTo(doc->get_FirstSection()->get_Body()->get_FirstParagraph()->GetChildNodes(NodeType::Any, false)->idx_get(0));
ASSERT_EQ(NodeType::BookmarkStart, builder->get_CurrentNode()->get_NodeType());
ASSERT_TRUE(builder->get_IsAtStartOfParagraph());
// A shorter way of moving the very start/end of a document is with these methods
builder->MoveToDocumentEnd();
ASSERT_TRUE(builder->get_IsAtEndOfParagraph());
builder->MoveToDocumentStart();
ASSERT_TRUE(builder->get_IsAtStartOfParagraph());

◆ get_CurrentSection()

System::SharedPtr<Aspose::Words::Section> Aspose::Words::DocumentBuilder::get_CurrentSection ( )

Gets the section that is currently selected in this DocumentBuilder.

Examples

Shows how to insert a floating image and specify its position and size.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// By default, the image is inline
SharedPtr<Shape> shape = builder->InsertImage(ImageDir + u"Logo.jpg");
// Make the image float, put it behind text and center on the page
shape->set_WrapType(WrapType::None);
// Make position relative to the page
shape->set_RelativeHorizontalPosition(RelativeHorizontalPosition::Page);
shape->set_RelativeVerticalPosition(RelativeVerticalPosition::Page);
// Set the shape's coordinates, from the top left corner of the page
shape->set_Left(100);
shape->set_Top(80);
// Set the shape's height
shape->set_Height(125.0);
// The width will be scaled to the height and the dimensions of the real image
ASPOSE_ASSERT_EQ(125.0, shape->get_Width());
// The Bottom and Right members contain the locations of the bottom and right edges of the image
ASPOSE_ASSERT_EQ(shape->get_Top() + shape->get_Height(), shape->get_Bottom());
ASPOSE_ASSERT_EQ(shape->get_Left() + shape->get_Width(), shape->get_Right());
doc->Save(ArtifactsDir + u"Image.CreateFloatingPositionSize.docx");

◆ get_CurrentStory()

System::SharedPtr<Aspose::Words::Story> Aspose::Words::DocumentBuilder::get_CurrentStory ( )

Gets the story that is currently selected in this DocumentBuilder.

Examples

Shows how to work with a document builder's current story.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// A Story is a type of node that have child Paragraph nodes, such as a Body,
// which would usually be a parent node to a DocumentBuilder's current paragraph
ASPOSE_ASSERT_EQ(builder->get_CurrentStory(), doc->get_FirstSection()->get_Body());
ASPOSE_ASSERT_EQ(builder->get_CurrentStory(), builder->get_CurrentParagraph()->get_ParentNode());
ASSERT_EQ(StoryType::MainText, builder->get_CurrentStory()->get_StoryType());
builder->get_CurrentStory()->AppendParagraph(u"Text added to current Story.");
// A Story can contain tables too
SharedPtr<Table> table = builder->StartTable();
builder->InsertCell();
builder->Write(u"Row 1 cell 1");
builder->InsertCell();
builder->Write(u"Row 1 cell 2");
builder->EndTable();
// The table we just made is automatically placed in the story
ASSERT_TRUE(builder->get_CurrentStory()->get_Tables()->Contains(table));

◆ get_Document()

System::SharedPtr<Aspose::Words::Document> Aspose::Words::DocumentBuilder::get_Document ( ) const

Gets or sets the Document object that this object is attached to.

Examples

Shows how to insert sections using DocumentBuilder, specify page setup for a section and reset page setup to defaults.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Modify the first section in the document
builder->get_PageSetup()->set_Orientation(Orientation::Landscape);
builder->get_PageSetup()->set_VerticalAlignment(PageVerticalAlignment::Center);
builder->Writeln(u"Section 1, landscape oriented and text vertically centered.");
// Start a new section and reset its formatting to defaults
builder->InsertBreak(BreakType::SectionBreakNewPage);
builder->get_PageSetup()->ClearFormatting();
builder->Writeln(u"Section 2, back to default Letter paper size, portrait orientation and top alignment.");
doc->Save(ArtifactsDir + u"PageSetup.ClearFormatting.docx");

◆ get_Font()

System::SharedPtr<Aspose::Words::Font> Aspose::Words::DocumentBuilder::get_Font ( )

Returns an object that represents current font formatting properties.

Use Font to access and modify font formatting properties.

Specify font formatting before inserting text.

Examples

Shows how to insert a string surrounded by a border into a document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->get_Font()->get_Border()->set_Color(System::Drawing::Color::get_Green());
builder->get_Font()->get_Border()->set_LineWidth(2.5);
builder->get_Font()->get_Border()->set_LineStyle(LineStyle::DashDotStroker);
builder->Write(u"Text surrounded by green border.");
doc->Save(ArtifactsDir + u"Border.FontBorder.docx");

Shows how to create a formatted table using DocumentBuilder.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<Table> table = builder->StartTable();
// Make the header row
builder->InsertCell();
// Set the left indent for the table. Table wide formatting must be applied after
// at least one row is present in the table
table->set_LeftIndent(20.0);
// Set height and define the height rule for the header row
builder->get_RowFormat()->set_Height(40.0);
builder->get_RowFormat()->set_HeightRule(HeightRule::AtLeast);
// Some special features for the header row
builder->get_CellFormat()->get_Shading()->set_BackgroundPatternColor(System::Drawing::Color::FromArgb(198, 217, 241));
builder->get_ParagraphFormat()->set_Alignment(ParagraphAlignment::Center);
builder->get_Font()->set_Size(16);
builder->get_Font()->set_Name(u"Arial");
builder->get_Font()->set_Bold(true);
builder->get_CellFormat()->set_Width(100.0);
builder->Write(u"Header Row,\n Cell 1");
// We don't need to specify the width of this cell because it's inherited from the previous cell
builder->InsertCell();
builder->Write(u"Header Row,\n Cell 2");
builder->InsertCell();
builder->get_CellFormat()->set_Width(200.0);
builder->Write(u"Header Row,\n Cell 3");
builder->EndRow();
// Set features for the other rows and cells
builder->get_CellFormat()->get_Shading()->set_BackgroundPatternColor(System::Drawing::Color::get_White());
builder->get_CellFormat()->set_Width(100.0);
builder->get_CellFormat()->set_VerticalAlignment(CellVerticalAlignment::Center);
// Reset height and define a different height rule for table body
builder->get_RowFormat()->set_Height(30.0);
builder->get_RowFormat()->set_HeightRule(HeightRule::Auto);
builder->InsertCell();
// Reset font formatting
builder->get_Font()->set_Size(12);
builder->get_Font()->set_Bold(false);
// Build the other cells
builder->Write(u"Row 1, Cell 1 Content");
builder->InsertCell();
builder->Write(u"Row 1, Cell 2 Content");
builder->InsertCell();
builder->get_CellFormat()->set_Width(200.0);
builder->Write(u"Row 1, Cell 3 Content");
builder->EndRow();
builder->InsertCell();
builder->get_CellFormat()->set_Width(100.0);
builder->Write(u"Row 2, Cell 1 Content");
builder->InsertCell();
builder->Write(u"Row 2, Cell 2 Content");
builder->InsertCell();
builder->get_CellFormat()->set_Width(200.0);
builder->Write(u"Row 2, Cell 3 Content.");
builder->EndRow();
builder->EndTable();
doc->Save(ArtifactsDir + u"DocumentBuilder.CreateFormattedTable.docx");

◆ get_IsAtEndOfParagraph()

bool Aspose::Words::DocumentBuilder::get_IsAtEndOfParagraph ( )

Returns true if the cursor is at the end of the current paragraph.

Examples

Shows how to move a DocumentBuilder to different nodes in a document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Start a bookmark and add content to it using a DocumentBuilder
builder->StartBookmark(u"MyBookmark");
builder->Writeln(u"Bookmark contents.");
builder->EndBookmark(u"MyBookmark");
// The node that the DocumentBuilder is currently at is past the boundaries of the bookmark
ASPOSE_ASSERT_EQ(doc->get_Range()->get_Bookmarks()->idx_get(0)->get_BookmarkEnd(), builder->get_CurrentParagraph()->get_FirstChild());
// If we wish to revise the content of our bookmark with the DocumentBuilder, we can move back to it like this
builder->MoveToBookmark(u"MyBookmark");
// Now we're located between the bookmark's BookmarkStart and BookmarkEnd nodes, so any text the builder adds will be within it
ASPOSE_ASSERT_EQ(doc->get_Range()->get_Bookmarks()->idx_get(0)->get_BookmarkStart(), builder->get_CurrentParagraph()->get_FirstChild());
// We can move the builder to an individual node,
// which in this case will be the first node of the first paragraph, like this
builder->MoveTo(doc->get_FirstSection()->get_Body()->get_FirstParagraph()->GetChildNodes(NodeType::Any, false)->idx_get(0));
ASSERT_EQ(NodeType::BookmarkStart, builder->get_CurrentNode()->get_NodeType());
ASSERT_TRUE(builder->get_IsAtStartOfParagraph());
// A shorter way of moving the very start/end of a document is with these methods
builder->MoveToDocumentEnd();
ASSERT_TRUE(builder->get_IsAtEndOfParagraph());
builder->MoveToDocumentStart();
ASSERT_TRUE(builder->get_IsAtStartOfParagraph());

◆ get_IsAtStartOfParagraph()

bool Aspose::Words::DocumentBuilder::get_IsAtStartOfParagraph ( )

Returns true if the cursor is at the beginning of the current paragraph (no text before the cursor).

Examples

Shows how to move a DocumentBuilder to different nodes in a document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Start a bookmark and add content to it using a DocumentBuilder
builder->StartBookmark(u"MyBookmark");
builder->Writeln(u"Bookmark contents.");
builder->EndBookmark(u"MyBookmark");
// The node that the DocumentBuilder is currently at is past the boundaries of the bookmark
ASPOSE_ASSERT_EQ(doc->get_Range()->get_Bookmarks()->idx_get(0)->get_BookmarkEnd(), builder->get_CurrentParagraph()->get_FirstChild());
// If we wish to revise the content of our bookmark with the DocumentBuilder, we can move back to it like this
builder->MoveToBookmark(u"MyBookmark");
// Now we're located between the bookmark's BookmarkStart and BookmarkEnd nodes, so any text the builder adds will be within it
ASPOSE_ASSERT_EQ(doc->get_Range()->get_Bookmarks()->idx_get(0)->get_BookmarkStart(), builder->get_CurrentParagraph()->get_FirstChild());
// We can move the builder to an individual node,
// which in this case will be the first node of the first paragraph, like this
builder->MoveTo(doc->get_FirstSection()->get_Body()->get_FirstParagraph()->GetChildNodes(NodeType::Any, false)->idx_get(0));
ASSERT_EQ(NodeType::BookmarkStart, builder->get_CurrentNode()->get_NodeType());
ASSERT_TRUE(builder->get_IsAtStartOfParagraph());
// A shorter way of moving the very start/end of a document is with these methods
builder->MoveToDocumentEnd();
ASSERT_TRUE(builder->get_IsAtEndOfParagraph());
builder->MoveToDocumentStart();
ASSERT_TRUE(builder->get_IsAtStartOfParagraph());

◆ get_Italic()

bool Aspose::Words::DocumentBuilder::get_Italic ( )

True if the font is formatted as italic.

Examples

Shows how to fill MERGEFIELDs with data with a DocumentBuilder and without a mail merge.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Insert some MERGEFIELDS, which accept data from columns of the same name in a data source during a mail merge
builder->InsertField(u" MERGEFIELD Chairman ");
builder->InsertField(u" MERGEFIELD ChiefFinancialOfficer ");
builder->InsertField(u" MERGEFIELD ChiefTechnologyOfficer ");
// They can also be filled in manually like this
builder->MoveToMergeField(u"Chairman");
builder->set_Bold(true);
builder->Writeln(u"John Doe");
builder->MoveToMergeField(u"ChiefFinancialOfficer");
builder->set_Italic(true);
builder->Writeln(u"Jane Doe");
builder->MoveToMergeField(u"ChiefTechnologyOfficer");
builder->set_Italic(true);
builder->Writeln(u"John Bloggs");
doc->Save(ArtifactsDir + u"DocumentBuilder.FillMergeFields.docx");

◆ get_ListFormat()

System::SharedPtr<Aspose::Words::ListFormat> Aspose::Words::DocumentBuilder::get_ListFormat ( )

Returns an object that represents current list formatting properties.

Examples

Shows how to apply default bulleted or numbered list formatting to paragraphs when using DocumentBuilder.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->Writeln(u"Aspose.Words allows:");
builder->Writeln();
// Start a numbered list with default formatting
builder->get_ListFormat()->ApplyNumberDefault();
builder->Writeln(u"Opening documents from different formats:");
ASSERT_EQ(0, builder->get_ListFormat()->get_ListLevelNumber());
// Go to second list level, add more text
builder->get_ListFormat()->ListIndent();
ASSERT_EQ(1, builder->get_ListFormat()->get_ListLevelNumber());
builder->Writeln(u"DOC");
builder->Writeln(u"PDF");
builder->Writeln(u"HTML");
// Outdent to the first list level
builder->get_ListFormat()->ListOutdent();
ASSERT_EQ(0, builder->get_ListFormat()->get_ListLevelNumber());
builder->Writeln(u"Processing documents");
builder->Writeln(u"Saving documents in different formats:");
// Indent the list level again
builder->get_ListFormat()->ListIndent();
builder->Writeln(u"DOC");
builder->Writeln(u"PDF");
builder->Writeln(u"HTML");
builder->Writeln(u"MHTML");
builder->Writeln(u"Plain text");
// Outdent the list level again
builder->get_ListFormat()->ListOutdent();
builder->Writeln(u"Doing many other things!");
// End the numbered list
builder->get_ListFormat()->RemoveNumbers();
builder->Writeln();
builder->Writeln(u"Aspose.Words main advantages are:");
builder->Writeln();
// Start a bulleted list with default formatting
builder->get_ListFormat()->ApplyBulletDefault();
builder->Writeln(u"Great performance");
builder->Writeln(u"High reliability");
builder->Writeln(u"Quality code and working");
builder->Writeln(u"Wide variety of features");
builder->Writeln(u"Easy to understand API");
// End the bulleted list
builder->get_ListFormat()->RemoveNumbers();
doc->Save(ArtifactsDir + u"Lists.ApplyDefaultBulletsAndNumbers.docx");

◆ get_PageSetup()

System::SharedPtr<Aspose::Words::PageSetup> Aspose::Words::DocumentBuilder::get_PageSetup ( )

Returns an object that represents current page setup and section properties.

Examples

Shows how to insert sections using DocumentBuilder, specify page setup for a section and reset page setup to defaults.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Modify the first section in the document
builder->get_PageSetup()->set_Orientation(Orientation::Landscape);
builder->get_PageSetup()->set_VerticalAlignment(PageVerticalAlignment::Center);
builder->Writeln(u"Section 1, landscape oriented and text vertically centered.");
// Start a new section and reset its formatting to defaults
builder->InsertBreak(BreakType::SectionBreakNewPage);
builder->get_PageSetup()->ClearFormatting();
builder->Writeln(u"Section 2, back to default Letter paper size, portrait orientation and top alignment.");
doc->Save(ArtifactsDir + u"PageSetup.ClearFormatting.docx");

◆ get_ParagraphFormat()

System::SharedPtr<Aspose::Words::ParagraphFormat> Aspose::Words::DocumentBuilder::get_ParagraphFormat ( )

Returns an object that represents current paragraph formatting properties.

Examples

Shows how to create a formatted table using DocumentBuilder.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<Table> table = builder->StartTable();
// Make the header row
builder->InsertCell();
// Set the left indent for the table. Table wide formatting must be applied after
// at least one row is present in the table
table->set_LeftIndent(20.0);
// Set height and define the height rule for the header row
builder->get_RowFormat()->set_Height(40.0);
builder->get_RowFormat()->set_HeightRule(HeightRule::AtLeast);
// Some special features for the header row
builder->get_CellFormat()->get_Shading()->set_BackgroundPatternColor(System::Drawing::Color::FromArgb(198, 217, 241));
builder->get_ParagraphFormat()->set_Alignment(ParagraphAlignment::Center);
builder->get_Font()->set_Size(16);
builder->get_Font()->set_Name(u"Arial");
builder->get_Font()->set_Bold(true);
builder->get_CellFormat()->set_Width(100.0);
builder->Write(u"Header Row,\n Cell 1");
// We don't need to specify the width of this cell because it's inherited from the previous cell
builder->InsertCell();
builder->Write(u"Header Row,\n Cell 2");
builder->InsertCell();
builder->get_CellFormat()->set_Width(200.0);
builder->Write(u"Header Row,\n Cell 3");
builder->EndRow();
// Set features for the other rows and cells
builder->get_CellFormat()->get_Shading()->set_BackgroundPatternColor(System::Drawing::Color::get_White());
builder->get_CellFormat()->set_Width(100.0);
builder->get_CellFormat()->set_VerticalAlignment(CellVerticalAlignment::Center);
// Reset height and define a different height rule for table body
builder->get_RowFormat()->set_Height(30.0);
builder->get_RowFormat()->set_HeightRule(HeightRule::Auto);
builder->InsertCell();
// Reset font formatting
builder->get_Font()->set_Size(12);
builder->get_Font()->set_Bold(false);
// Build the other cells
builder->Write(u"Row 1, Cell 1 Content");
builder->InsertCell();
builder->Write(u"Row 1, Cell 2 Content");
builder->InsertCell();
builder->get_CellFormat()->set_Width(200.0);
builder->Write(u"Row 1, Cell 3 Content");
builder->EndRow();
builder->InsertCell();
builder->get_CellFormat()->set_Width(100.0);
builder->Write(u"Row 2, Cell 1 Content");
builder->InsertCell();
builder->Write(u"Row 2, Cell 2 Content");
builder->InsertCell();
builder->get_CellFormat()->set_Width(200.0);
builder->Write(u"Row 2, Cell 3 Content.");
builder->EndRow();
builder->EndTable();
doc->Save(ArtifactsDir + u"DocumentBuilder.CreateFormattedTable.docx");

◆ get_RowFormat()

System::SharedPtr<Aspose::Words::Tables::RowFormat> Aspose::Words::DocumentBuilder::get_RowFormat ( )

Returns an object that represents current table row formatting properties.

Examples

Shows how to build a nice bordered table.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Start building a table
builder->StartTable();
// Set the appropriate paragraph, cell, and row formatting. The formatting properties are preserved
// until they are explicitly modified so there's no need to set them for each row or cell
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();
// Remove the shading (clear background)
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();
builder->InsertCell();
// Make the row height bigger so that a vertically oriented text could fit into cells
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 build a formatted table that contains 2 rows and 2 columns.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<Table> table = builder->StartTable();
// Insert a cell
builder->InsertCell();
builder->get_CellFormat()->set_VerticalAlignment(CellVerticalAlignment::Center);
builder->Write(u"This is row 1 cell 1");
// Use fixed column widths
table->AutoFit(AutoFitBehavior::FixedColumnWidths);
// Insert a cell
builder->InsertCell();
builder->Write(u"This is row 1 cell 2");
builder->EndRow();
// Insert a cell
builder->InsertCell();
// Apply new row formatting
builder->get_RowFormat()->set_Height(100);
builder->get_RowFormat()->set_HeightRule(HeightRule::Exactly);
builder->get_CellFormat()->set_Orientation(TextOrientation::Upward);
builder->Write(u"This is row 2 cell 1");
// Insert a cell
builder->InsertCell();
builder->get_CellFormat()->set_Orientation(TextOrientation::Downward);
builder->Write(u"This is row 2 cell 2");
builder->EndRow();
builder->EndTable();

Shows how to create a table that contains a single cell and apply row formatting.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<Table> table = builder->StartTable();
builder->InsertCell();
// Set the row formatting
SharedPtr<RowFormat> rowFormat = builder->get_RowFormat();
rowFormat->set_Height(100);
rowFormat->set_HeightRule(HeightRule::Exactly);
// These formatting properties are set on the table and are applied to all rows in the table
table->set_LeftPadding(30);
table->set_RightPadding(30);
table->set_TopPadding(30);
table->set_BottomPadding(30);
builder->Writeln(u"Contents of formatted row.");
builder->EndRow();
builder->EndTable();
doc->Save(ArtifactsDir + u"DocumentBuilder.DocumentBuilderSetRowFormatting.docx");

◆ get_Underline()

Aspose::Words::Underline Aspose::Words::DocumentBuilder::get_Underline ( )

Gets/sets underline type for the current font.

Examples

Shows how to set and edit a document builder's underline.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Set a new style for our underline
builder->set_Underline(Underline::Dash);
// Same object as DocumentBuilder.Font.Underline
ASSERT_EQ(builder->get_Underline(), builder->get_Font()->get_Underline());
ASSERT_EQ(Underline::Dash, builder->get_Font()->get_Underline());
// These properties will be applied to the underline as well
builder->get_Font()->set_Color(System::Drawing::Color::get_Blue());
builder->get_Font()->set_Size(32);
builder->Writeln(u"Underlined text.");
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertUnderline.docx");

◆ GetType()

virtual const System::TypeInfo& Aspose::Words::DocumentBuilder::GetType ( ) const
overridevirtual

◆ InsertBreak()

void Aspose::Words::DocumentBuilder::InsertBreak ( Aspose::Words::BreakType  breakType)

Inserts a break of the specified type into the document.

Parameters
breakTypeSpecifies the type of the break to insert.
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 headers and footers different for first, even and odd pages
builder->get_PageSetup()->set_DifferentFirstPageHeaderFooter(true);
builder->get_PageSetup()->set_OddAndEvenPagesHeaderFooter(true);
// Create the headers
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");
// Create three pages in the document
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 insert a Table of contents (TOC) into a document using heading styles as entries.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Insert a table of contents at the beginning of the document,
// and set it to pick up paragraphs with headings of levels 1 to 3 and entries to act like hyperlinks
builder->InsertTableOfContents(u"\\o \"1-3\" \\h \\z \\u");
// Start the actual document content on the second page
builder->InsertBreak(BreakType::PageBreak);
// Build a document with complex structure by applying different heading styles thus creating TOC entries
// The heading levels we use below will affect the list levels in which these items will appear in the TOC,
// and only levels 1-3 will be picked up by our TOC due to its settings
builder->get_ParagraphFormat()->set_StyleIdentifier(StyleIdentifier::Heading1);
builder->Writeln(u"Heading 1");
builder->get_ParagraphFormat()->set_StyleIdentifier(StyleIdentifier::Heading2);
builder->Writeln(u"Heading 1.1");
builder->Writeln(u"Heading 1.2");
builder->get_ParagraphFormat()->set_StyleIdentifier(StyleIdentifier::Heading1);
builder->Writeln(u"Heading 2");
builder->Writeln(u"Heading 3");
builder->get_ParagraphFormat()->set_StyleIdentifier(StyleIdentifier::Heading2);
builder->Writeln(u"Heading 3.1");
builder->get_ParagraphFormat()->set_StyleIdentifier(StyleIdentifier::Heading3);
builder->Writeln(u"Heading 3.1.1");
builder->Writeln(u"Heading 3.1.2");
builder->Writeln(u"Heading 3.1.3");
builder->get_ParagraphFormat()->set_StyleIdentifier(StyleIdentifier::Heading2);
builder->Writeln(u"Heading 3.2");
builder->Writeln(u"Heading 3.3");
// Call the method below to update the TOC and save
doc->UpdateFields();
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertToc.docx");

Shows how to insert sections using DocumentBuilder, specify page setup for a section and reset page setup to defaults.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Modify the first section in the document
builder->get_PageSetup()->set_Orientation(Orientation::Landscape);
builder->get_PageSetup()->set_VerticalAlignment(PageVerticalAlignment::Center);
builder->Writeln(u"Section 1, landscape oriented and text vertically centered.");
// Start a new section and reset its formatting to defaults
builder->InsertBreak(BreakType::SectionBreakNewPage);
builder->get_PageSetup()->ClearFormatting();
builder->Writeln(u"Section 2, back to default Letter paper size, portrait orientation and top alignment.");
doc->Save(ArtifactsDir + u"PageSetup.ClearFormatting.docx");

◆ InsertCell()

System::SharedPtr<Aspose::Words::Tables::Cell> Aspose::Words::DocumentBuilder::InsertCell ( )

Inserts a table cell into the document.

To start a table, just call InsertCell. After this, any content you add using other methods of the DocumentBuilder class will be added to the current cell.

To start a new cell in the same row, call InsertCell again.

To end a table row call EndRow.

Use the CellFormat property to specify cell formatting.

Returns
The cell node that was just inserted.
Examples

Shows how to build a nice bordered table.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Start building a table
builder->StartTable();
// Set the appropriate paragraph, cell, and row formatting. The formatting properties are preserved
// until they are explicitly modified so there's no need to set them for each row or cell
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();
// Remove the shading (clear background)
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();
builder->InsertCell();
// Make the row height bigger so that a vertically oriented text could fit into cells
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 create a simple table using DocumentBuilder with default formatting.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// We call this method to start building the table
builder->StartTable();
builder->InsertCell();
builder->Write(u"Row 1, Cell 1 Content.");
// Build the second cell
builder->InsertCell();
builder->Write(u"Row 1, Cell 2 Content.");
// Call the following method to end the row and start a new row
builder->EndRow();
// Build the first cell of the second row
builder->InsertCell();
builder->Write(u"Row 2, Cell 1 Content.");
// Build the second cell.
builder->InsertCell();
builder->Write(u"Row 2, Cell 2 Content.");
builder->EndRow();
// Signal that we have finished building the table
builder->EndTable();
// Save the document to disk
doc->Save(ArtifactsDir + u"DocumentBuilder.CreateSimpleTable.docx");

◆ InsertChart() [1/2]

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertChart ( Aspose::Words::Drawing::Charts::ChartType  chartType,
Aspose::Words::Drawing::RelativeHorizontalPosition  horzPos,
double  left,
Aspose::Words::Drawing::RelativeVerticalPosition  vertPos,
double  top,
double  width,
double  height,
Aspose::Words::Drawing::WrapType  wrapType 
)

Inserts an chart object into the document and scales it to the specified size.

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Parameters
chartTypeThe chart type to insert into the document.
horzPosSpecifies where the distance to the image is measured from.
leftDistance in points from the origin to the left side of the image.
vertPosSpecifies where the distance to the image measured from.
topDistance in points from the origin to the top side of the image.
widthThe width of the image in points. Can be a negative or zero value to request 100% scale.
heightThe height of the image in points. Can be a negative or zero value to request 100% scale.
wrapTypeSpecifies how to wrap text around the image.
Returns
The image node that was just inserted.
Examples

Shows how to insert a chart into a document and specify position and size.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->InsertChart(ChartType::Pie, RelativeHorizontalPosition::Margin, 100, RelativeVerticalPosition::Margin, 100, 200, 100, WrapType::Square);
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertedChartRelativePosition.docx");

◆ InsertChart() [2/2]

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertChart ( Aspose::Words::Drawing::Charts::ChartType  chartType,
double  width,
double  height 
)

Inserts an chart object into the document and scales it to the specified size.

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Parameters
chartTypeThe chart type to insert into the document.
widthThe width of the image in points. Can be a negative or zero value to request 100% scale.
heightThe height of the image in points. Can be a negative or zero value to request 100% scale.
Returns
The image node that was just inserted.
Examples

Shows how to insert a chart into a document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->InsertChart(ChartType::Pie, ConvertUtil::PixelToPoint(300), ConvertUtil::PixelToPoint(300));
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertedChartDouble.docx");

◆ InsertCheckBox() [1/2]

System::SharedPtr<Aspose::Words::Fields::FormField> Aspose::Words::DocumentBuilder::InsertCheckBox ( System::String  name,
bool  checkedValue,
int32_t  size 
)

Inserts a checkbox form field at the current position.

If you specify a name for the form field, then a bookmark is automatically created with the same name.

Parameters
nameThe name of the form field. Can be an empty string. The value longer than 20 characters will be truncated.
checkedValueChecked status of the checkbox form field.
sizeSpecifies the size of the checkbox in points. Specify 0 for MS Word to calculate the size of the checkbox automatically.
Returns
The form field node that was just inserted.
Examples

Shows how to insert checkboxes to the document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->InsertCheckBox(String::Empty, false, false, 0);
builder->InsertCheckBox(u"CheckBox_Default", true, true, 50);
builder->InsertCheckBox(u"CheckBox_OnlyCheckedValue", true, 100);

◆ InsertCheckBox() [2/2]

System::SharedPtr<Aspose::Words::Fields::FormField> Aspose::Words::DocumentBuilder::InsertCheckBox ( System::String  name,
bool  defaultValue,
bool  checkedValue,
int32_t  size 
)

Inserts a checkbox form field at the current position.

If you specify a name for the form field, then a bookmark is automatically created with the same name.

Parameters
nameThe name of the form field. Can be an empty string. The value longer than 20 characters will be truncated.
defaultValueDefault value of the checkbox form field.
checkedValueCurrent checked status of the checkbox form field.
sizeSpecifies the size of the checkbox in points. Specify 0 for MS Word to calculate the size of the checkbox automatically.
Returns
The form field node that was just inserted.
Examples

Shows how to insert checkboxes to the document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->InsertCheckBox(String::Empty, false, false, 0);
builder->InsertCheckBox(u"CheckBox_Default", true, true, 50);
builder->InsertCheckBox(u"CheckBox_OnlyCheckedValue", true, 100);

◆ InsertComboBox()

System::SharedPtr<Aspose::Words::Fields::FormField> Aspose::Words::DocumentBuilder::InsertComboBox ( System::String  name,
System::ArrayPtr< System::String items,
int32_t  selectedIndex 
)

Inserts a combobox form field at the current position.

If you specify a name for the form field, then a bookmark is automatically created with the same name.

Parameters
nameThe name of the form field. Can be an empty string. The value longer than 20 characters will be truncated.
itemsThe items of the ComboBox. Maximum is 25 items.
selectedIndexThe index of the selected item in the ComboBox.
Returns
The form field node that was just inserted.
Examples

Shows how to build a form field.

auto builder = MakeObject<DocumentBuilder>();
// Insert a text form field for input a name
builder->InsertTextInput(u"", TextFormFieldType::Regular, u"", u"Enter your name here", 30);
// Insert two blank lines
builder->Writeln(u"");
builder->Writeln(u"");
ArrayPtr<String> items = MakeArray<String>({u"-- Select your favorite footwear --", u"Sneakers", u"Oxfords", u"Flip-flops", u"Other", u"I prefer to be barefoot"});
// Insert a combo box to select a footwear type
builder->InsertComboBox(u"", items, 0);
// Insert 2 blank lines
builder->Writeln(u"");
builder->Writeln(u"");
builder->get_Document()->Save(ArtifactsDir + u"DocumentBuilder.CreateForm.docx");

Shows how to insert a combobox form field into a document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
ArrayPtr<String> items = MakeArray<String>({u"One", u"Two", u"Three"});
builder->InsertComboBox(u"DropDown", items, 0);

◆ InsertDocument() [1/2]

System::SharedPtr<Aspose::Words::Node> Aspose::Words::DocumentBuilder::InsertDocument ( System::SharedPtr< Aspose::Words::Document srcDoc,
Aspose::Words::ImportFormatMode  importFormatMode 
)

Inserts a document at the cursor position.

Parameters
srcDocSource document for inserting.
importFormatModeSpecifies how to merge style formatting that clashes.
Returns
First node of the inserted content.
Examples

Shows how to insert a document content into another document keep formatting of inserted document.

auto doc = MakeObject<Document>(MyDir + u"Document.docx");
auto builder = MakeObject<DocumentBuilder>(doc);
builder->MoveToDocumentEnd();
builder->InsertBreak(BreakType::PageBreak);
auto docToInsert = MakeObject<Document>(MyDir + u"Formatted elements.docx");
builder->InsertDocument(docToInsert, ImportFormatMode::KeepSourceFormatting);
builder->get_Document()->Save(ArtifactsDir + u"DocumentBuilder.InsertDocument.docx");

◆ InsertDocument() [2/2]

System::SharedPtr<Aspose::Words::Node> Aspose::Words::DocumentBuilder::InsertDocument ( System::SharedPtr< Aspose::Words::Document srcDoc,
Aspose::Words::ImportFormatMode  importFormatMode,
System::SharedPtr< Aspose::Words::ImportFormatOptions importFormatOptions 
)

Inserts a document at the cursor position.

Parameters
srcDocSource document for inserting.
importFormatModeSpecifies how to merge style formatting that clashes.
importFormatOptionsAllows to specify options that affect formatting of a result document.
Returns
First node of the inserted content.
Examples

Shows how to resolve styles behavior while inserting documents.

auto dstDoc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(dstDoc);
SharedPtr<Style> myStyle = builder->get_Document()->get_Styles()->Add(StyleType::Paragraph, u"MyStyle");
myStyle->get_Font()->set_Size(14);
myStyle->get_Font()->set_Name(u"Courier New");
myStyle->get_Font()->set_Color(System::Drawing::Color::get_Blue());
// Append text with custom style
builder->get_ParagraphFormat()->set_StyleName(myStyle->get_Name());
builder->Writeln(u"Hello world!");
// Clone the document, and edit the clone's "MyStyle" style so it is a different color than that of the original
// If we append this document to the original, the different styles will clash since they are the same name, and we will need to resolve it
SharedPtr<Document> srcDoc = dstDoc->Clone();
srcDoc->get_Styles()->idx_get(u"MyStyle")->get_Font()->set_Color(System::Drawing::Color::get_Red());
// When SmartStyleBehavior is enabled,
// a source style will be expanded into a direct attributes inside a destination document,
// if KeepSourceFormatting importing mode is used
auto options = MakeObject<ImportFormatOptions>();
options->set_SmartStyleBehavior(true);
builder->InsertDocument(srcDoc, ImportFormatMode::KeepSourceFormatting, options);
dstDoc->Save(ArtifactsDir + u"DocumentBuilder.SmartStyleBehavior.docx");

◆ InsertField() [1/3]

System::SharedPtr<Aspose::Words::Fields::Field> Aspose::Words::DocumentBuilder::InsertField ( Aspose::Words::Fields::FieldType  fieldType,
bool  updateField 
)

Inserts a Word field into a document and optionally updates the field result.

This method inserts a field into a document. Aspose.Words can update fields of most types, but not all. For more details see the InsertField() overload.

Parameters
fieldTypeThe type of the field to append.
updateFieldSpecifies whether to update the field immediately.
Returns
A Field object that represents the inserted field.
See also
Aspose::Words::Fields::Field
Examples

Shows how to insert a field into a document using FieldType.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Insert an AUTHOR field using a DocumentBuilder
doc->get_BuiltInDocumentProperties()->set_Author(u"John Doe");
builder->Write(u"This document was written by ");
builder->InsertField(FieldType::FieldAuthor, true);
// Insert a PAGE field using a DocumentBuilder, but do not immediately update it
builder->Write(u"\nThis is page ");
builder->InsertField(FieldType::FieldPage, false);
// Some fields types, such as ones that display document word/page counts may not keep track of their results in real time,
// and will only display an accurate result during a field update
// We can defer the updating of those fields until right before we need to see an accurate result
// This method will manually update all the fields in a document
doc->UpdateFields();
ASSERT_EQ(u"1", doc->get_Range()->get_Fields()->idx_get(1)->get_Result());

◆ InsertField() [2/3]

System::SharedPtr<Aspose::Words::Fields::Field> Aspose::Words::DocumentBuilder::InsertField ( System::String  fieldCode)

Inserts a Word field into a document and updates the field result.

This method inserts a field into a document and updates the field result immediately. Aspose.Words can update fields of most types, but not all. For more details see the InsertField() overload.

Parameters
fieldCodeThe field code to insert (without curly braces).
Returns
A Field object that represents the inserted field.
See also
Aspose::Words::Fields::Field
Examples

Shows how to insert merge fields and move between them.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->InsertField(u"MERGEFIELD MyMergeField1 \\* MERGEFORMAT");
builder->InsertField(u"MERGEFIELD MyMergeField2 \\* MERGEFORMAT");
// The second merge field starts immediately after the end of the first
// We'll move the builder's cursor to the end of the first so we can split them by text
builder->MoveToMergeField(u"MyMergeField1", true, false);
ASPOSE_ASSERT_EQ(doc->get_Range()->get_Fields()->idx_get(1)->get_Start(), builder->get_CurrentNode());
builder->Write(u" Text between our two merge fields. ");
doc->Save(ArtifactsDir + u"DocumentBuilder.MergeFields.docx");

Shows how to insert a field into a document by FieldCode.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Insert a simple Date field into the document
// When we insert a field through the DocumentBuilder class we can get the
// special Field object which contains information about the field
SharedPtr<Field> dateField = builder->InsertField(u"DATE \\* MERGEFORMAT");
// Update this particular field in the document so we can get the FieldResult
dateField->Update();
// Display some information from this field
// The field result is where the last evaluated value is stored. This is what is displayed in the document
// When field codes are not showing
ASSERT_EQ(System::DateTime::get_Today(), System::DateTime::Parse(dateField->get_Result()));
// Display the field code which defines the behavior of the field. This can been seen in Microsoft Word by pressing ALT+F9
ASSERT_EQ(u"DATE \\* MERGEFORMAT", dateField->GetFieldCode());
// The field type defines what type of field in the Document this is. In this case the type is "FieldDate"
ASSERT_EQ(FieldType::FieldDate, dateField->get_Type());
// Finally let's completely remove the field from the document. This can easily be done by invoking the Remove method on the object
dateField->Remove();

◆ InsertField() [3/3]

System::SharedPtr<Aspose::Words::Fields::Field> Aspose::Words::DocumentBuilder::InsertField ( System::String  fieldCode,
System::String  fieldValue 
)

Inserts a Word field into a document without updating the field result.

Fields in Microsoft Word documents consist of a field code and a field result. The field code is like a formula and the field result is like the value that the formula produces. The field code may also contain field switches that are like additional instructions to perform a specific action.

You can switch between displaying field codes and results in your document in Microsoft Word using the keyboard shortcut Alt+F9. Field codes appear between curly braces ( { } ).

To create a field, you need to specify a field type, field code and a "placeholder" field value. If you are not sure about a particular field code syntax, create the field in Microsoft Word first and switch to see its field code.

Aspose.Words can calculate field results for most of the field types, but this method does not update the field result automatically. Because the field result is not calculated automatically, you are expected to pass some string value (or even an empty string) that will be inserted into the field result. This value will remain in the field result as a placeholder until the field is updated. To update the field result you can call Update on the field object returned to you or UpdateFields to update fields in the whole document.

Parameters
fieldCodeThe field code to insert (without curly braces).
fieldValueThe field value to insert. Pass null for fields that do not have a value.
Returns
A Field object that represents the inserted field.
See also
Aspose::Words::Fields::Field
Examples

Shows how to control page numbering per section.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->Writeln(u"Section 1");
builder->InsertBreak(BreakType::SectionBreakNewPage);
builder->Writeln(u"Section 2");
// Use document builder to create a header with a page number field for the first section
// The page number will look like "Page V"
builder->MoveToSection(0);
builder->MoveToHeaderFooter(HeaderFooterType::HeaderPrimary);
builder->Write(u"Page ");
builder->InsertField(u"PAGE", u"");
// Set first section page numbering
SharedPtr<PageSetup> pageSetup = doc->get_Sections()->idx_get(0)->get_PageSetup();
pageSetup->set_RestartPageNumbering(true);
pageSetup->set_PageStartingNumber(5);
pageSetup->set_PageNumberStyle(NumberStyle::UppercaseRoman);
// Create a header for the section
// The page number will look like " - 10 - ".
builder->MoveToSection(1);
builder->MoveToHeaderFooter(HeaderFooterType::HeaderPrimary);
builder->get_ParagraphFormat()->set_Alignment(ParagraphAlignment::Center);
builder->Write(u" - ");
builder->InsertField(u"PAGE", u"");
builder->Write(u" - ");
// Set second section page numbering
pageSetup = doc->get_Sections()->idx_get(1)->get_PageSetup();
pageSetup->set_PageStartingNumber(10);
pageSetup->set_RestartPageNumbering(true);
pageSetup->set_PageNumberStyle(NumberStyle::Arabic);
doc->Save(ArtifactsDir + u"PageSetup.PageNumbering.docx");

◆ InsertFootnote() [1/2]

System::SharedPtr<Aspose::Words::Footnote> Aspose::Words::DocumentBuilder::InsertFootnote ( Aspose::Words::FootnoteType  footnoteType,
System::String  footnoteText 
)

Inserts a footnote or endnote into the document.

Parameters
footnoteTypeSpecifies whether to insert a footnote or an endnote.
footnoteTextSpecifies the text of the footnote.
Returns
Returns a footnote object that was just created.
Examples

Shows how to reference text with a footnote and an endnote.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Insert some text and mark it with a footnote with the IsAuto attribute set to "true" by default,
// so the marker seen in the body text will be auto-numbered at "1", and the footnote will appear at the bottom of the page
builder->Write(u"This text will be referenced by a footnote.");
builder->InsertFootnote(FootnoteType::Footnote, u"Footnote comment regarding referenced text.");
// Insert more text and mark it with an endnote with a custom reference mark,
// which will be used in place of the number "2" and will set "IsAuto" to false
builder->Write(u"This text will be referenced by an endnote.");
builder->InsertFootnote(FootnoteType::Endnote, u"Endnote comment regarding referenced text.", u"CustomMark");
// Footnotes always appear at the bottom of the page of their referenced text, so this page break will not affect the footnote
// On the other hand, endnotes are always at the end of the document, so this page break will push the endnote down to the next page
builder->InsertBreak(BreakType::PageBreak);
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertFootnote.docx");

◆ InsertFootnote() [2/2]

System::SharedPtr<Aspose::Words::Footnote> Aspose::Words::DocumentBuilder::InsertFootnote ( Aspose::Words::FootnoteType  footnoteType,
System::String  footnoteText,
System::String  referenceMark 
)

Inserts a footnote or endnote into the document.

Parameters
footnoteTypeSpecifies whether to insert a footnote or an endnote.
footnoteTextSpecifies the text of the footnote.
referenceMarkSpecifies the custom reference mark of the footnote.
Returns
Returns a footnote object that was just created.
Examples

Shows how to reference text with a footnote and an endnote.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Insert some text and mark it with a footnote with the IsAuto attribute set to "true" by default,
// so the marker seen in the body text will be auto-numbered at "1", and the footnote will appear at the bottom of the page
builder->Write(u"This text will be referenced by a footnote.");
builder->InsertFootnote(FootnoteType::Footnote, u"Footnote comment regarding referenced text.");
// Insert more text and mark it with an endnote with a custom reference mark,
// which will be used in place of the number "2" and will set "IsAuto" to false
builder->Write(u"This text will be referenced by an endnote.");
builder->InsertFootnote(FootnoteType::Endnote, u"Endnote comment regarding referenced text.", u"CustomMark");
// Footnotes always appear at the bottom of the page of their referenced text, so this page break will not affect the footnote
// On the other hand, endnotes are always at the end of the document, so this page break will push the endnote down to the next page
builder->InsertBreak(BreakType::PageBreak);
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertFootnote.docx");

◆ InsertHorizontalRule()

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertHorizontalRule ( )

Inserts a horizontal rule shape into the document.

Returns
The shape that is a horizontal rule.
Examples

Shows how to insert horizontal rule shape in a document and customize the formatting.

// Use a document builder to insert a horizontal rule
auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<Shape> shape = builder->InsertHorizontalRule();
SharedPtr<HorizontalRuleFormat> horizontalRuleFormat = shape->get_HorizontalRuleFormat();
horizontalRuleFormat->set_Alignment(HorizontalRuleAlignment::Center);
horizontalRuleFormat->set_WidthPercent(70);
horizontalRuleFormat->set_Height(3);
horizontalRuleFormat->set_Color(System::Drawing::Color::get_Blue());
horizontalRuleFormat->set_NoShade(true);
ASSERT_TRUE(shape->get_IsHorizontalRule());
ASSERT_TRUE(shape->get_HorizontalRuleFormat()->get_NoShade());

◆ InsertHtml() [1/2]

void Aspose::Words::DocumentBuilder::InsertHtml ( System::String  html)

Inserts an HTML string into the document.

You can use InsertHtml to insert an HTML fragment or whole HTML document.

Parameters
htmlAn HTML string to insert into the document.
Examples

Shows how to insert Html content into a document using a builder.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
const String html = String(u"<P align='right'>Paragraph right</P>") + u"<b>Implicit paragraph left</b>" + u"<div align='center'>Div center</div>" + u"<h1 align='left'>Heading 1 left.</h1>";
builder->InsertHtml(html);
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertHtml.docx");

◆ InsertHtml() [2/2]

void Aspose::Words::DocumentBuilder::InsertHtml ( System::String  html,
bool  useBuilderFormatting 
)

Inserts an HTML string into the document.

You can use InsertHtml to insert an HTML fragment or whole HTML document.

When useBuilderFormatting is false, DocumentBuilder formating is ignored and formatting of inserted text is based on default HTML formatting. As a result, the text looks as it is rendered in browsers.

When useBuilderFormatting is true, formatting of inserted text is based on DocumentBuilder formatting, and the text looks as if it were inserted with Write().

Parameters
htmlAn HTML string to insert into the document.
useBuilderFormattingA value indicating whether formatting specified in DocumentBuilder is used as base formatting for text imported from HTML.
Examples

Shows how to insert Html content into a document using a builder while applying the builder's formatting.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Set the builder's text alignment
builder->get_ParagraphFormat()->set_Alignment(ParagraphAlignment::Distributed);
// If we insert text while setting useBuilderFormatting to true, any formatting applied to the builder will be applied to inserted .html content
// However, if the html text has formatting coded into it, that formatting takes precedence over the builder's formatting
// In this case, elements with "align" attributes do not get affected by the ParagraphAlignment we specified above
builder->InsertHtml(String(u"<P align='right'>Paragraph right</P>") + u"<b>Implicit paragraph left</b>" + u"<div align='center'>Div center</div>" + u"<h1 align='left'>Heading 1 left.</h1>", true);
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertHtmlWithFormatting.docx");

◆ InsertHyperlink()

System::SharedPtr<Aspose::Words::Fields::Field> Aspose::Words::DocumentBuilder::InsertHyperlink ( System::String  displayText,
System::String  urlOrBookmark,
bool  isBookmark 
)

Inserts a hyperlink into the document.

Note that you need to specify font formatting for the hyperlink display text explicitly using the Font property.

This methods internally calls InsertField() to insert an MS Word HYPERLINK field into the document.

Parameters
displayTextText of the link to be displayed in the document.
urlOrBookmarkLink destination. Can be a url or a name of a bookmark inside the document. This method always adds apostrophes at the beginning and end of the url.
isBookmarkTrue if the previous parameter is a name of a bookmark inside the document; false is the previous parameter is a URL.
Returns
A Field object that represents the inserted field.
Examples

Shows how to insert a hyperlink into a document using DocumentBuilder.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->Write(u"Please make sure to visit ");
// Specify font formatting for the hyperlink
builder->get_Font()->set_Color(System::Drawing::Color::get_Blue());
builder->get_Font()->set_Underline(Underline::Single);
// Insert the link
builder->InsertHyperlink(u"Aspose Website", u"https://www.aspose.com", false);
// Revert to default formatting
builder->get_Font()->ClearFormatting();
builder->Write(u" for more information.");
// Holding Ctrl and left clicking on the field in Microsoft Word will take you to the link's address in a web browser
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertHyperlink.docx");

Shows how to use temporarily save and restore character formatting when building a document with DocumentBuilder.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Set up font formatting and write text that goes before the hyperlink
builder->get_Font()->set_Name(u"Arial");
builder->get_Font()->set_Size(24);
builder->get_Font()->set_Bold(true);
builder->Write(u"To visit Google, hold Ctrl and click ");
// Save the font formatting so we use different formatting for hyperlink and restore old formatting later
builder->PushFont();
// Set new font formatting for the hyperlink and insert the hyperlink
// The "Hyperlink" style is a Microsoft Word built-in style so we don't have to worry to
// create it, it will be created automatically if it does not yet exist in the document
builder->get_Font()->set_StyleIdentifier(StyleIdentifier::Hyperlink);
builder->InsertHyperlink(u"here", u"http://www.google.com", false);
// Restore the formatting that was before the hyperlink
builder->PopFont();
builder->Write(u". We hope you enjoyed the example.");
doc->Save(ArtifactsDir + u"DocumentBuilder.PushPopFont.docx");

Shows how to insert a hyperlink referencing a local bookmark.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->StartBookmark(u"Bookmark1");
builder->Write(u"Bookmarked text.");
builder->EndBookmark(u"Bookmark1");
builder->Writeln(u"Some other text");
// Specify font formatting for the hyperlink
builder->get_Font()->set_Color(System::Drawing::Color::get_Blue());
builder->get_Font()->set_Underline(Underline::Single);
// Insert hyperlink
// Switch \o is used to provide hyperlink tip text
builder->InsertHyperlink(u"Hyperlink Text", u"Bookmark1\" \\o \"Hyperlink Tip", true);
// Clear hyperlink formatting
builder->get_Font()->ClearFormatting();
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertHyperlinkToLocalBookmark.docx");

◆ InsertImage() [1/12]

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertImage ( System::ArrayPtr< uint8_t >  imageBytes)

Inserts an image from a byte array into the document. The image is inserted inline and at 100% scale.

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Parameters
imageBytesThe byte array that contains the image.
Returns
The image node that was just inserted.
Examples

Shows different solutions of how to import an image into a document from a byte array.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<System::Drawing::Image> image = System::Drawing::Image::FromFile(ImageDir + u"Logo.jpg");
{
auto ms = MakeObject<System::IO::MemoryStream>();
ArrayPtr<uint8_t> imageByteArray = ms->ToArray();
builder->Writeln(u"\nInserted image from byte array: ");
builder->InsertImage(imageByteArray);
builder->Writeln(u"\nInserted image from byte array with a custom size: ");
builder->InsertImage(imageByteArray, ConvertUtil::PixelToPoint(250), ConvertUtil::PixelToPoint(144));
builder->Writeln(u"\nInserted image from byte array using relative positions: ");
builder->InsertImage(imageByteArray, RelativeHorizontalPosition::Margin, 100.0, RelativeVerticalPosition::Margin, 100.0, 200.0, 100.0, WrapType::Square);
}
doc->Save(ArtifactsDir + u"DocumentBuilderImages.InsertImageFromByteArray.docx");

◆ InsertImage() [2/12]

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertImage ( System::ArrayPtr< uint8_t >  imageBytes,
Aspose::Words::Drawing::RelativeHorizontalPosition  horzPos,
double  left,
Aspose::Words::Drawing::RelativeVerticalPosition  vertPos,
double  top,
double  width,
double  height,
Aspose::Words::Drawing::WrapType  wrapType 
)

Inserts an image from a byte array at the specified position and size.

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Parameters
imageBytesThe byte array that contains the image.
horzPosSpecifies where the distance to the image is measured from.
leftDistance in points from the origin to the left side of the image.
vertPosSpecifies where the distance to the image measured from.
topDistance in points from the origin to the top side of the image.
widthThe width of the image in points. Can be a negative or zero value to request 100% scale.
heightThe height of the image in points. Can be a negative or zero value to request 100% scale.
wrapTypeSpecifies how to wrap text around the image.
Returns
The image node that was just inserted.
Examples

Shows different solutions of how to import an image into a document from a byte array.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<System::Drawing::Image> image = System::Drawing::Image::FromFile(ImageDir + u"Logo.jpg");
{
auto ms = MakeObject<System::IO::MemoryStream>();
ArrayPtr<uint8_t> imageByteArray = ms->ToArray();
builder->Writeln(u"\nInserted image from byte array: ");
builder->InsertImage(imageByteArray);
builder->Writeln(u"\nInserted image from byte array with a custom size: ");
builder->InsertImage(imageByteArray, ConvertUtil::PixelToPoint(250), ConvertUtil::PixelToPoint(144));
builder->Writeln(u"\nInserted image from byte array using relative positions: ");
builder->InsertImage(imageByteArray, RelativeHorizontalPosition::Margin, 100.0, RelativeVerticalPosition::Margin, 100.0, 200.0, 100.0, WrapType::Square);
}
doc->Save(ArtifactsDir + u"DocumentBuilderImages.InsertImageFromByteArray.docx");

◆ InsertImage() [3/12]

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertImage ( System::ArrayPtr< uint8_t >  imageBytes,
double  width,
double  height 
)

Inserts an inline image from a byte array into the document and scales it to the specified size.

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Parameters
imageBytesThe byte array that contains the image.
widthThe width of the image in points. Can be a negative or zero value to request 100% scale.
heightThe height of the image in points. Can be a negative or zero value to request 100% scale.
Returns
The image node that was just inserted.
Examples

Shows different solutions of how to import an image into a document from a byte array.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<System::Drawing::Image> image = System::Drawing::Image::FromFile(ImageDir + u"Logo.jpg");
{
auto ms = MakeObject<System::IO::MemoryStream>();
ArrayPtr<uint8_t> imageByteArray = ms->ToArray();
builder->Writeln(u"\nInserted image from byte array: ");
builder->InsertImage(imageByteArray);
builder->Writeln(u"\nInserted image from byte array with a custom size: ");
builder->InsertImage(imageByteArray, ConvertUtil::PixelToPoint(250), ConvertUtil::PixelToPoint(144));
builder->Writeln(u"\nInserted image from byte array using relative positions: ");
builder->InsertImage(imageByteArray, RelativeHorizontalPosition::Margin, 100.0, RelativeVerticalPosition::Margin, 100.0, 200.0, 100.0, WrapType::Square);
}
doc->Save(ArtifactsDir + u"DocumentBuilderImages.InsertImageFromByteArray.docx");

◆ InsertImage() [4/12]

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertImage ( System::SharedPtr< System::Drawing::Image image)

Inserts an image from a .NET Image object into the document. The image is inserted inline and at 100% scale.

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Parameters
imageThe image to insert into the document.
Returns
The image node that was just inserted.
Examples

Shows how to a watermark image into a document using DocumentBuilder.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// The best place for the watermark image is in the header or footer so it is shown on every page
builder->MoveToHeaderFooter(HeaderFooterType::HeaderPrimary);
SharedPtr<System::Drawing::Image> image = System::Drawing::Image::FromFile(ImageDir + u"Transparent background logo.png");
// Insert a floating picture
SharedPtr<Shape> shape = builder->InsertImage(image);
shape->set_WrapType(WrapType::None);
shape->set_BehindText(true);
shape->set_RelativeHorizontalPosition(RelativeHorizontalPosition::Page);
shape->set_RelativeVerticalPosition(RelativeVerticalPosition::Page);
// Calculate image left and top position so it appears in the center of the page
shape->set_Left((builder->get_PageSetup()->get_PageWidth() - shape->get_Width()) / 2);
shape->set_Top((builder->get_PageSetup()->get_PageHeight() - shape->get_Height()) / 2);
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertWatermark.docx");

◆ InsertImage() [5/12]

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertImage ( System::SharedPtr< System::Drawing::Image image,
Aspose::Words::Drawing::RelativeHorizontalPosition  horzPos,
double  left,
Aspose::Words::Drawing::RelativeVerticalPosition  vertPos,
double  top,
double  width,
double  height,
Aspose::Words::Drawing::WrapType  wrapType 
)

Inserts an image from a .NET Image object at the specified position and size.

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Parameters
imageThe image to insert into the document.
horzPosSpecifies where the distance to the image is measured from.
leftDistance in points from the origin to the left side of the image.
vertPosSpecifies where the distance to the image measured from.
topDistance in points from the origin to the top side of the image.
widthThe width of the image in points. Can be a negative or zero value to request 100% scale.
heightThe height of the image in points. Can be a negative or zero value to request 100% scale.
wrapTypeSpecifies how to wrap text around the image.
Returns
The image node that was just inserted.
Examples

Shows different solutions of how to import an image into a document from Image class.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<System::Drawing::Image> image = System::Drawing::Image::FromFile(ImageDir + u"Logo.jpg");
builder->Writeln(u"\nInserted image from Image class: ");
builder->InsertImage(image);
builder->Writeln(u"\nInserted image from Image class with a custom size: ");
builder->InsertImage(image, ConvertUtil::PixelToPoint(250), ConvertUtil::PixelToPoint(144));
builder->Writeln(u"\nInserted image from Image class using relative positions: ");
builder->InsertImage(image, RelativeHorizontalPosition::Margin, 100.0, RelativeVerticalPosition::Margin, 100.0, 200.0, 100.0, WrapType::Square);
doc->Save(ArtifactsDir + u"DocumentBuilderImages.InsertImageFromImageClass.docx");

◆ InsertImage() [6/12]

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertImage ( System::SharedPtr< System::Drawing::Image image,
double  width,
double  height 
)

Inserts an inline image from a .NET Image object into the document and scales it to the specified size.

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Parameters
imageThe image to insert into the document.
widthThe width of the image in points. Can be a negative or zero value to request 100% scale.
heightThe height of the image in points. Can be a negative or zero value to request 100% scale.
Returns
The image node that was just inserted.
Examples

Shows different solutions of how to import an image into a document from Image class.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<System::Drawing::Image> image = System::Drawing::Image::FromFile(ImageDir + u"Logo.jpg");
builder->Writeln(u"\nInserted image from Image class: ");
builder->InsertImage(image);
builder->Writeln(u"\nInserted image from Image class with a custom size: ");
builder->InsertImage(image, ConvertUtil::PixelToPoint(250), ConvertUtil::PixelToPoint(144));
builder->Writeln(u"\nInserted image from Image class using relative positions: ");
builder->InsertImage(image, RelativeHorizontalPosition::Margin, 100.0, RelativeVerticalPosition::Margin, 100.0, 200.0, 100.0, WrapType::Square);
doc->Save(ArtifactsDir + u"DocumentBuilderImages.InsertImageFromImageClass.docx");

◆ InsertImage() [7/12]

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertImage ( System::SharedPtr< System::IO::Stream stream)

Inserts an image from a stream into the document. The image is inserted inline and at 100% scale.

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Parameters
streamThe stream that contains the image.
Returns
The image node that was just inserted.
Examples

Shows different solutions of how to import an image into a document from a stream.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
{
SharedPtr<System::IO::Stream> stream = System::IO::File::OpenRead(ImageDir + u"Logo.jpg");
builder->Writeln(u"Inserted image from stream: ");
builder->InsertImage(stream);
builder->Writeln(u"\nInserted image from stream with a custom size: ");
builder->InsertImage(stream, ConvertUtil::PixelToPoint(250), ConvertUtil::PixelToPoint(144));
builder->Writeln(u"\nInserted image from stream using relative positions: ");
builder->InsertImage(stream, RelativeHorizontalPosition::Margin, 100.0, RelativeVerticalPosition::Margin, 100.0, 200.0, 100.0, WrapType::Square);
}
doc->Save(ArtifactsDir + u"DocumentBuilderImages.InsertImageFromStream.docx");

Shows how to insert an image from a stream.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
{
SharedPtr<System::IO::Stream> stream = System::IO::File::OpenRead(ImageDir + u"Logo.jpg");
builder->Write(u"Image from stream: ");
builder->InsertImage(stream);
}
doc->Save(ArtifactsDir + u"Image.CreateFromStream.docx");

◆ InsertImage() [8/12]

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertImage ( System::SharedPtr< System::IO::Stream stream,
Aspose::Words::Drawing::RelativeHorizontalPosition  horzPos,
double  left,
Aspose::Words::Drawing::RelativeVerticalPosition  vertPos,
double  top,
double  width,
double  height,
Aspose::Words::Drawing::WrapType  wrapType 
)

Inserts an image from a stream at the specified position and size.

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Parameters
streamThe stream that contains the image.
horzPosSpecifies where the distance to the image is measured from.
leftDistance in points from the origin to the left side of the image.
vertPosSpecifies where the distance to the image measured from.
topDistance in points from the origin to the top side of the image.
widthThe width of the image in points. Can be a negative or zero value to request 100% scale.
heightThe height of the image in points. Can be a negative or zero value to request 100% scale.
wrapTypeSpecifies how to wrap text around the image.
Returns
The image node that was just inserted.
Examples

Shows different solutions of how to import an image into a document from a stream.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
{
SharedPtr<System::IO::Stream> stream = System::IO::File::OpenRead(ImageDir + u"Logo.jpg");
builder->Writeln(u"Inserted image from stream: ");
builder->InsertImage(stream);
builder->Writeln(u"\nInserted image from stream with a custom size: ");
builder->InsertImage(stream, ConvertUtil::PixelToPoint(250), ConvertUtil::PixelToPoint(144));
builder->Writeln(u"\nInserted image from stream using relative positions: ");
builder->InsertImage(stream, RelativeHorizontalPosition::Margin, 100.0, RelativeVerticalPosition::Margin, 100.0, 200.0, 100.0, WrapType::Square);
}
doc->Save(ArtifactsDir + u"DocumentBuilderImages.InsertImageFromStream.docx");

◆ InsertImage() [9/12]

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertImage ( System::SharedPtr< System::IO::Stream stream,
double  width,
double  height 
)

Inserts an inline image from a stream into the document and scales it to the specified size.

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Parameters
streamThe stream that contains the image.
widthThe width of the image in points. Can be a negative or zero value to request 100% scale.
heightThe height of the image in points. Can be a negative or zero value to request 100% scale.
Returns
The image node that was just inserted.
Examples

Shows different solutions of how to import an image into a document from a stream.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
{
SharedPtr<System::IO::Stream> stream = System::IO::File::OpenRead(ImageDir + u"Logo.jpg");
builder->Writeln(u"Inserted image from stream: ");
builder->InsertImage(stream);
builder->Writeln(u"\nInserted image from stream with a custom size: ");
builder->InsertImage(stream, ConvertUtil::PixelToPoint(250), ConvertUtil::PixelToPoint(144));
builder->Writeln(u"\nInserted image from stream using relative positions: ");
builder->InsertImage(stream, RelativeHorizontalPosition::Margin, 100.0, RelativeVerticalPosition::Margin, 100.0, 200.0, 100.0, WrapType::Square);
}
doc->Save(ArtifactsDir + u"DocumentBuilderImages.InsertImageFromStream.docx");

◆ InsertImage() [10/12]

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertImage ( System::String  fileName)

Inserts an image from a file or URL into the document. The image is inserted inline and at 100% scale.

This overload will automatically download the image before inserting into the document if you specify a remote URI.

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Parameters
fileNameThe file with the image. Can be any valid local or remote URI.
Returns
The image node that was just inserted.
Examples

Shows different solutions of how to import an image into a document from a string.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->Writeln(u"\nInserted image from string: ");
builder->InsertImage(ImageDir + u"Logo.jpg");
builder->Writeln(u"\nInserted image from string with a custom size: ");
builder->InsertImage(ImageDir + u"Transparent background logo.png", ConvertUtil::PixelToPoint(250), ConvertUtil::PixelToPoint(144));
builder->Writeln(u"\nInserted image from string using relative positions: ");
builder->InsertImage(ImageDir + u"Windows Metafile.wmf", RelativeHorizontalPosition::Margin, 100.0, RelativeVerticalPosition::Margin, 100.0, 200.0, 100.0, WrapType::Square);
doc->Save(ArtifactsDir + u"DocumentBuilderImages.InsertImageFromString.docx");

Shows how to inserts an image from a URL.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->Write(u"Image from local file: ");
builder->InsertImage(ImageDir + u"Logo.jpg");
builder->Writeln();
builder->Write(u"Image from a URL: ");
builder->InsertImage(AsposeLogoUrl);
builder->Writeln();
doc->Save(ArtifactsDir + u"Image.CreateFromUrl.docx");

Shows how to insert a floating image in the middle of a page.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// By default, the image is inline
SharedPtr<Shape> shape = builder->InsertImage(ImageDir + u"Logo.jpg");
// Make the image float, put it behind text and center on the page
shape->set_WrapType(WrapType::None);
shape->set_BehindText(true);
shape->set_RelativeHorizontalPosition(RelativeHorizontalPosition::Page);
shape->set_RelativeVerticalPosition(RelativeVerticalPosition::Page);
shape->set_HorizontalAlignment(HorizontalAlignment::Center);
shape->set_VerticalAlignment(VerticalAlignment::Center);
doc->Save(ArtifactsDir + u"Image.CreateFloatingPageCenter.docx");

◆ InsertImage() [11/12]

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertImage ( System::String  fileName,
Aspose::Words::Drawing::RelativeHorizontalPosition  horzPos,
double  left,
Aspose::Words::Drawing::RelativeVerticalPosition  vertPos,
double  top,
double  width,
double  height,
Aspose::Words::Drawing::WrapType  wrapType 
)

Inserts an image from a file or URL at the specified position and size.

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Parameters
fileNameThe file that contains the image.
horzPosSpecifies where the distance to the image is measured from.
leftDistance in points from the origin to the left side of the image.
vertPosSpecifies where the distance to the image measured from.
topDistance in points from the origin to the top side of the image.
widthThe width of the image in points. Can be a negative or zero value to request 100% scale.
heightThe height of the image in points. Can be a negative or zero value to request 100% scale.
wrapTypeSpecifies how to wrap text around the image.
Returns
The image node that was just inserted.
Examples

Shows how to insert a floating image from a file or URL.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->InsertImage(ImageDir + u"Transparent background logo.png", RelativeHorizontalPosition::Margin, 100.0, RelativeVerticalPosition::Margin, 100.0, 200.0, 100.0, WrapType::Square);

Shows how to insert a floating image from a file or URL and retain the original image size in the document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Pass a negative value to the width and height values to specify using the size of the source image
builder->InsertImage(ImageDir + u"Logo.jpg", RelativeHorizontalPosition::Margin, 200.0, RelativeVerticalPosition::Margin, 100.0, -1.0, -1.0, WrapType::Square);

Shows different solutions of how to import an image into a document from a string.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->Writeln(u"\nInserted image from string: ");
builder->InsertImage(ImageDir + u"Logo.jpg");
builder->Writeln(u"\nInserted image from string with a custom size: ");
builder->InsertImage(ImageDir + u"Transparent background logo.png", ConvertUtil::PixelToPoint(250), ConvertUtil::PixelToPoint(144));
builder->Writeln(u"\nInserted image from string using relative positions: ");
builder->InsertImage(ImageDir + u"Windows Metafile.wmf", RelativeHorizontalPosition::Margin, 100.0, RelativeVerticalPosition::Margin, 100.0, 200.0, 100.0, WrapType::Square);
doc->Save(ArtifactsDir + u"DocumentBuilderImages.InsertImageFromString.docx");

◆ InsertImage() [12/12]

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertImage ( System::String  fileName,
double  width,
double  height 
)

Inserts an inline image from a file or URL into the document and scales it to the specified size.

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Parameters
fileNameThe file that contains the image.
widthThe width of the image in points. Can be a negative or zero value to request 100% scale.
heightThe height of the image in points. Can be a negative or zero value to request 100% scale.
Returns
The image node that was just inserted.
Examples

Shows different solutions of how to import an image into a document from a string.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->Writeln(u"\nInserted image from string: ");
builder->InsertImage(ImageDir + u"Logo.jpg");
builder->Writeln(u"\nInserted image from string with a custom size: ");
builder->InsertImage(ImageDir + u"Transparent background logo.png", ConvertUtil::PixelToPoint(250), ConvertUtil::PixelToPoint(144));
builder->Writeln(u"\nInserted image from string using relative positions: ");
builder->InsertImage(ImageDir + u"Windows Metafile.wmf", RelativeHorizontalPosition::Margin, 100.0, RelativeVerticalPosition::Margin, 100.0, 200.0, 100.0, WrapType::Square);
doc->Save(ArtifactsDir + u"DocumentBuilderImages.InsertImageFromString.docx");

◆ InsertNode()

void Aspose::Words::DocumentBuilder::InsertNode ( System::SharedPtr< Aspose::Words::Node node)

Inserts a text level node inside the current paragraph before the cursor.

Examples

Shows how to insert a linked image into a document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
String imageFileName = ImageDir + u"Windows MetaFile.wmf";
builder->Write(u"Image linked, not stored in the document: ");
auto shape = MakeObject<Shape>(builder->get_Document(), ShapeType::Image);
shape->set_WrapType(WrapType::Inline);
shape->get_ImageData()->set_SourceFullName(imageFileName);
builder->InsertNode(shape);
builder->Writeln();
builder->Write(u"Image linked and stored in the document: ");
shape = MakeObject<Shape>(builder->get_Document(), ShapeType::Image);
shape->set_WrapType(WrapType::Inline);
shape->get_ImageData()->set_SourceFullName(imageFileName);
shape->get_ImageData()->SetImage(imageFileName);
builder->InsertNode(shape);
builder->Writeln();
builder->Write(u"Image stored in the document, but not linked: ");
shape = MakeObject<Shape>(builder->get_Document(), ShapeType::Image);
shape->set_WrapType(WrapType::Inline);
shape->get_ImageData()->SetImage(imageFileName);
builder->InsertNode(shape);
builder->Writeln();
doc->Save(ArtifactsDir + u"Image.CreateLinkedImage.docx");

◆ InsertOleObject() [1/3]

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertOleObject ( System::SharedPtr< System::IO::Stream stream,
System::String  progId,
bool  asIcon,
System::SharedPtr< System::Drawing::Image presentation 
)

Inserts an embedded OLE object from a stream into the document.

Parameters
streamStream containing application data.
progIdProgrammatic Identifier of OLE object.
asIconSpecifies either Iconic or Normal mode of OLE object being inserted.
presentationImage presentation of OLE object. If value is null Aspose.Words will use one of the predefined images.
Returns
Shape node containing Ole object and inserted at the current Builder position.
Examples

Shows how to use document builder to embed Ole objects in a document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Let's take a spreadsheet from our system and insert it into the document
{
SharedPtr<System::IO::Stream> spreadsheetStream = System::IO::File::Open(MyDir + u"Spreadsheet.xlsx", System::IO::FileMode::Open);
// The spreadsheet can be activated by double clicking the panel that you'll see in the document immediately under the text we will add
// We did not set the area to double click as an icon nor did we change its appearance so it looks like a simple panel
builder->Writeln(u"Spreadsheet Ole object:");
builder->InsertOleObject(spreadsheetStream, u"OleObject.xlsx", false, nullptr);
// A powerpoint presentation is another type of object we can embed in our document
// This time we'll also exercise some control over how it looks
{
SharedPtr<System::IO::Stream> powerpointStream = System::IO::File::Open(MyDir + u"Presentation.pptx", System::IO::FileMode::Open);
// If we insert the Ole object as an icon, we are still provided with a default icon
// If that is not suitable, we can make the icon to look like any image
{
auto webClient = MakeObject<System::Net::WebClient>();
ArrayPtr<uint8_t> imgBytes = webClient->DownloadData(AsposeLogoUrl);
{
auto stream = MakeObject<System::IO::MemoryStream>(imgBytes);
{
SharedPtr<System::Drawing::Image> image = System::Drawing::Image::FromStream(stream);
// If we double click the image, the powerpoint presentation will open
builder->InsertParagraph();
builder->Writeln(u"Powerpoint Ole object:");
builder->InsertOleObject(powerpointStream, u"OleObject.pptx", true, image);
}
}
}
}
}
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertOlePowerpoint.docx");

◆ InsertOleObject() [2/3]

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertOleObject ( System::String  fileName,
bool  isLinked,
bool  asIcon,
System::SharedPtr< System::Drawing::Image presentation 
)

Inserts an embedded or linked OLE object from a file into the document. Detects OLE object type using file extension.

Parameters
fileNameFull path to the file.
isLinkedIf true then linked OLE object is inserted otherwise embedded OLE object is inserted.
asIconSpecifies either Iconic or Normal mode of OLE object being inserted.
presentationImage presentation of OLE object. If value is null Aspose.Words will use one of the predefined images.
Returns
Shape node containing Ole object and inserted at the current Builder position.
Examples

Shows how to insert an OLE object into a document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Insert ole object
SharedPtr<System::Drawing::Image> representingImage = System::Drawing::Image::FromFile(ImageDir + u"Logo.jpg");
builder->InsertOleObject(MyDir + u"Spreadsheet.xlsx", false, false, representingImage);
// Insert ole object with ProgId
builder->InsertOleObject(MyDir + u"Spreadsheet.xlsx", u"Excel.Sheet", false, true, nullptr);
// Insert ole object as Icon
// There is one limitation for now: the maximum size of the icon must be 32x32 for the correct display
builder->InsertOleObjectAsIcon(MyDir + u"Presentation.pptx", false, ImageDir + u"Logo icon.ico", u"Caption (can not be null)");
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertOleObject.docx");

◆ InsertOleObject() [3/3]

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertOleObject ( System::String  fileName,
System::String  progId,
bool  isLinked,
bool  asIcon,
System::SharedPtr< System::Drawing::Image presentation 
)

Inserts an embedded or linked OLE object from a file into the document. Detects OLE object type using given progID parameter.

Parameters
fileNameFull path to the file.
progIdProgId of OLE object.
isLinkedIf true then linked OLE object is inserted otherwise embedded OLE object is inserted.
asIconSpecifies either Iconic or Normal mode of OLE object being inserted.
presentationImage presentation of OLE object. If value is null Aspose.Words will use one of the predefined images.
Returns
Shape node containing Ole object and inserted at the current Builder position.
Examples

Shows how to insert an OLE object into a document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Insert ole object
SharedPtr<System::Drawing::Image> representingImage = System::Drawing::Image::FromFile(ImageDir + u"Logo.jpg");
builder->InsertOleObject(MyDir + u"Spreadsheet.xlsx", false, false, representingImage);
// Insert ole object with ProgId
builder->InsertOleObject(MyDir + u"Spreadsheet.xlsx", u"Excel.Sheet", false, true, nullptr);
// Insert ole object as Icon
// There is one limitation for now: the maximum size of the icon must be 32x32 for the correct display
builder->InsertOleObjectAsIcon(MyDir + u"Presentation.pptx", false, ImageDir + u"Logo icon.ico", u"Caption (can not be null)");
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertOleObject.docx");

◆ InsertOleObjectAsIcon()

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertOleObjectAsIcon ( System::String  fileName,
bool  isLinked,
System::String  iconFile,
System::String  iconCaption 
)

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.

Parameters
fileNameFull path to the file.
isLinkedIf true then linked OLE object is inserted otherwise embedded OLE object is inserted.
iconFileFull path to the ICO file. If the value is null, Aspose.Words will use a predefined image.
iconCaptionIcon caption.
Returns
Shape node containing Ole object and inserted at the current Builder position.
Examples

Shows how to insert an OLE object into a document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Insert ole object
SharedPtr<System::Drawing::Image> representingImage = System::Drawing::Image::FromFile(ImageDir + u"Logo.jpg");
builder->InsertOleObject(MyDir + u"Spreadsheet.xlsx", false, false, representingImage);
// Insert ole object with ProgId
builder->InsertOleObject(MyDir + u"Spreadsheet.xlsx", u"Excel.Sheet", false, true, nullptr);
// Insert ole object as Icon
// There is one limitation for now: the maximum size of the icon must be 32x32 for the correct display
builder->InsertOleObjectAsIcon(MyDir + u"Presentation.pptx", false, ImageDir + u"Logo icon.ico", u"Caption (can not be null)");
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertOleObject.docx");

◆ InsertOnlineVideo() [1/4]

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertOnlineVideo ( System::String  videoUrl,
Aspose::Words::Drawing::RelativeHorizontalPosition  horzPos,
double  left,
Aspose::Words::Drawing::RelativeVerticalPosition  vertPos,
double  top,
double  width,
double  height,
Aspose::Words::Drawing::WrapType  wrapType 
)

Inserts an online video object into the document and scales it to the specified size.

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Insertion of online video from the following resources is supported:

If your online video is not displaying correctly, use InsertOnlineVideo(), which accepts custom embedded html code.

The code for embedding video can vary between providers, consult your corresponding provider of choice for details.

Parameters
videoUrlThe URL to the video.
horzPosSpecifies where the distance to the image is measured from.
leftDistance in points from the origin to the left side of the image.
vertPosSpecifies where the distance to the image measured from.
topDistance in points from the origin to the top side of the image.
widthThe width of the image in points. Can be a negative or zero value to request 100% scale.
heightThe height of the image in points. Can be a negative or zero value to request 100% scale.
wrapTypeSpecifies how to wrap text around the image.
Returns
The image node that was just inserted.
Examples

Shows how to insert online video into a document using html code.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Visible url
String vimeoVideoUrl = u"https://vimeo.com/52477838";
// Embed Html code
String vimeoEmbedCode = u"<iframe src=\"https://player.vimeo.com/video/52477838\" width=\"640\" height=\"360\" frameborder=\"0\" title=\"Aspose\" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>";
// This video will have an automatically generated thumbnail, and we are setting the size according to its 16:9 aspect ratio
builder->Writeln(u"Video with an automatically generated thumbnail at the top left corner of the page:");
builder->InsertOnlineVideo(vimeoVideoUrl, RelativeHorizontalPosition::LeftMargin, 0, RelativeVerticalPosition::TopMargin, 0, 320, 180, WrapType::Square);
builder->InsertBreak(BreakType::PageBreak);
// We can get an image to use as a custom thumbnail
{
auto webClient = MakeObject<System::Net::WebClient>();
ArrayPtr<uint8_t> imageBytes = webClient->DownloadData(AsposeLogoUrl);
{
auto stream = MakeObject<System::IO::MemoryStream>(imageBytes);
{
SharedPtr<System::Drawing::Image> image = System::Drawing::Image::FromStream(stream);
// This puts the video where we are with our document builder, with a custom thumbnail and size depending on the size of the image
builder->Writeln(u"Custom thumbnail at document builder's cursor:");
builder->InsertOnlineVideo(vimeoVideoUrl, vimeoEmbedCode, imageBytes, image->get_Width(), image->get_Height());
builder->InsertBreak(BreakType::PageBreak);
// We can put the video at the bottom right edge of the page too, but we'll have to take the page margins into account
double left = builder->get_PageSetup()->get_RightMargin() - image->get_Width();
double top = builder->get_PageSetup()->get_BottomMargin() - image->get_Height();
// Here we use a custom thumbnail and relative positioning to put it and the bottom right of tha page
builder->Writeln(u"Bottom right of page with custom thumbnail:");
builder->InsertOnlineVideo(vimeoVideoUrl, vimeoEmbedCode, imageBytes, RelativeHorizontalPosition::RightMargin, left, RelativeVerticalPosition::BottomMargin, top, image->get_Width(), image->get_Height(), WrapType::Square);
}
}
}
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertOnlineVideo.docx");

◆ InsertOnlineVideo() [2/4]

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertOnlineVideo ( System::String  videoUrl,
double  width,
double  height 
)

Inserts an online video object into the document and scales it to the specified size.

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Insertion of online video from the following resources is supported:

If your online video is not displaying correctly, use InsertOnlineVideo(), which accepts custom embedded html code.

The code for embedding video can vary between providers, consult your corresponding provider of choice for details.

Parameters
videoUrlThe URL to the video.
widthThe width of the image in points. Can be a negative or zero value to request 100% scale.
heightThe height of the image in points. Can be a negative or zero value to request 100% scale.
Returns
The image node that was just inserted.
Examples

Shows how to insert online video into a document using video url

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Insert a video from Youtube
builder->InsertOnlineVideo(u"https://youtu.be/t_1LYZ102RA", 360, 270);
// Click on the shape in the output document to watch the video from Microsoft Word
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertVideoWithUrl.docx");

◆ InsertOnlineVideo() [3/4]

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertOnlineVideo ( System::String  videoUrl,
System::String  videoEmbedCode,
System::ArrayPtr< uint8_t >  thumbnailImageBytes,
Aspose::Words::Drawing::RelativeHorizontalPosition  horzPos,
double  left,
Aspose::Words::Drawing::RelativeVerticalPosition  vertPos,
double  top,
double  width,
double  height,
Aspose::Words::Drawing::WrapType  wrapType 
)

Inserts an online video object into the document and scales it to the specified size.

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Parameters
videoUrlThe URL to the video.
videoEmbedCodeThe embed code for the video.
thumbnailImageBytesThe thumbnail image bytes.
horzPosSpecifies where the distance to the image is measured from.
leftDistance in points from the origin to the left side of the image.
vertPosSpecifies where the distance to the image measured from.
topDistance in points from the origin to the top side of the image.
widthThe width of the image in points. Can be a negative or zero value to request 100% scale.
heightThe height of the image in points. Can be a negative or zero value to request 100% scale.
wrapTypeSpecifies how to wrap text around the image.
Returns
The image node that was just inserted.
Examples

Shows how to insert online video into a document using html code.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Visible url
String vimeoVideoUrl = u"https://vimeo.com/52477838";
// Embed Html code
String vimeoEmbedCode = u"<iframe src=\"https://player.vimeo.com/video/52477838\" width=\"640\" height=\"360\" frameborder=\"0\" title=\"Aspose\" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>";
// This video will have an automatically generated thumbnail, and we are setting the size according to its 16:9 aspect ratio
builder->Writeln(u"Video with an automatically generated thumbnail at the top left corner of the page:");
builder->InsertOnlineVideo(vimeoVideoUrl, RelativeHorizontalPosition::LeftMargin, 0, RelativeVerticalPosition::TopMargin, 0, 320, 180, WrapType::Square);
builder->InsertBreak(BreakType::PageBreak);
// We can get an image to use as a custom thumbnail
{
auto webClient = MakeObject<System::Net::WebClient>();
ArrayPtr<uint8_t> imageBytes = webClient->DownloadData(AsposeLogoUrl);
{
auto stream = MakeObject<System::IO::MemoryStream>(imageBytes);
{
SharedPtr<System::Drawing::Image> image = System::Drawing::Image::FromStream(stream);
// This puts the video where we are with our document builder, with a custom thumbnail and size depending on the size of the image
builder->Writeln(u"Custom thumbnail at document builder's cursor:");
builder->InsertOnlineVideo(vimeoVideoUrl, vimeoEmbedCode, imageBytes, image->get_Width(), image->get_Height());
builder->InsertBreak(BreakType::PageBreak);
// We can put the video at the bottom right edge of the page too, but we'll have to take the page margins into account
double left = builder->get_PageSetup()->get_RightMargin() - image->get_Width();
double top = builder->get_PageSetup()->get_BottomMargin() - image->get_Height();
// Here we use a custom thumbnail and relative positioning to put it and the bottom right of tha page
builder->Writeln(u"Bottom right of page with custom thumbnail:");
builder->InsertOnlineVideo(vimeoVideoUrl, vimeoEmbedCode, imageBytes, RelativeHorizontalPosition::RightMargin, left, RelativeVerticalPosition::BottomMargin, top, image->get_Width(), image->get_Height(), WrapType::Square);
}
}
}
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertOnlineVideo.docx");

◆ InsertOnlineVideo() [4/4]

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertOnlineVideo ( System::String  videoUrl,
System::String  videoEmbedCode,
System::ArrayPtr< uint8_t >  thumbnailImageBytes,
double  width,
double  height 
)

Inserts an online video object into the document and scales it to the specified size.

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Parameters
videoUrlThe URL to the video.
videoEmbedCodeThe embed code for the video.
thumbnailImageBytesThe thumbnail image bytes.
widthThe width of the image in points. Can be a negative or zero value to request 100% scale.
heightThe height of the image in points. Can be a negative or zero value to request 100% scale.
Returns
The image node that was just inserted.
Examples

Shows how to insert online video into a document using html code.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Visible url
String vimeoVideoUrl = u"https://vimeo.com/52477838";
// Embed Html code
String vimeoEmbedCode = u"<iframe src=\"https://player.vimeo.com/video/52477838\" width=\"640\" height=\"360\" frameborder=\"0\" title=\"Aspose\" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>";
// This video will have an automatically generated thumbnail, and we are setting the size according to its 16:9 aspect ratio
builder->Writeln(u"Video with an automatically generated thumbnail at the top left corner of the page:");
builder->InsertOnlineVideo(vimeoVideoUrl, RelativeHorizontalPosition::LeftMargin, 0, RelativeVerticalPosition::TopMargin, 0, 320, 180, WrapType::Square);
builder->InsertBreak(BreakType::PageBreak);
// We can get an image to use as a custom thumbnail
{
auto webClient = MakeObject<System::Net::WebClient>();
ArrayPtr<uint8_t> imageBytes = webClient->DownloadData(AsposeLogoUrl);
{
auto stream = MakeObject<System::IO::MemoryStream>(imageBytes);
{
SharedPtr<System::Drawing::Image> image = System::Drawing::Image::FromStream(stream);
// This puts the video where we are with our document builder, with a custom thumbnail and size depending on the size of the image
builder->Writeln(u"Custom thumbnail at document builder's cursor:");
builder->InsertOnlineVideo(vimeoVideoUrl, vimeoEmbedCode, imageBytes, image->get_Width(), image->get_Height());
builder->InsertBreak(BreakType::PageBreak);
// We can put the video at the bottom right edge of the page too, but we'll have to take the page margins into account
double left = builder->get_PageSetup()->get_RightMargin() - image->get_Width();
double top = builder->get_PageSetup()->get_BottomMargin() - image->get_Height();
// Here we use a custom thumbnail and relative positioning to put it and the bottom right of tha page
builder->Writeln(u"Bottom right of page with custom thumbnail:");
builder->InsertOnlineVideo(vimeoVideoUrl, vimeoEmbedCode, imageBytes, RelativeHorizontalPosition::RightMargin, left, RelativeVerticalPosition::BottomMargin, top, image->get_Width(), image->get_Height(), WrapType::Square);
}
}
}
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertOnlineVideo.docx");

◆ InsertParagraph()

System::SharedPtr<Aspose::Words::Paragraph> Aspose::Words::DocumentBuilder::InsertParagraph ( )

Inserts a paragraph break into the document.

Current paragraph formatting specified by the ParagraphFormat property is used.

Breaks the current paragraph in two. After inserting the paragraph, the cursor is placed at the beginning of the new paragraph.

Returns
The paragraph node that was just inserted. It is the same node as CurrentParagraph.
Examples

Shows how to insert a paragraph into the document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Specify font formatting
SharedPtr<Font> font = builder->get_Font();
font->set_Size(16);
font->set_Bold(true);
font->set_Name(u"Arial");
font->set_Underline(Underline::Dash);
// Specify paragraph formatting
SharedPtr<ParagraphFormat> paragraphFormat = builder->get_ParagraphFormat();
paragraphFormat->set_FirstLineIndent(8);
paragraphFormat->set_Alignment(ParagraphAlignment::Justify);
paragraphFormat->set_AddSpaceBetweenFarEastAndAlpha(true);
paragraphFormat->set_AddSpaceBetweenFarEastAndDigit(true);
paragraphFormat->set_KeepTogether(true);
// Using Writeln() ends the paragraph after writing and makes a new one, while Write() stays on the same paragraph
builder->Writeln(u"A whole paragraph.");
// We can use this flag to ensure that we're at the end of the document
ASSERT_TRUE(builder->get_CurrentParagraph()->get_IsEndOfDocument());

◆ InsertShape() [1/2]

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertShape ( Aspose::Words::Drawing::ShapeType  shapeType,
Aspose::Words::Drawing::RelativeHorizontalPosition  horzPos,
double  left,
Aspose::Words::Drawing::RelativeVerticalPosition  vertPos,
double  top,
double  width,
double  height,
Aspose::Words::Drawing::WrapType  wrapType 
)

Inserts free-floating shape with specified position, size and text wrap type.

Parameters
shapeTypeThe shape type to insert into the document
horzPosSpecifies where the horizontal distance to the shape is measured from.
leftDistance in points from the origin to the left side of the shape.
vertPosSpecifies where the vertical distance to the shape is measured from.
topDistance in points from the origin to the top side of the shape.
widthThe width of the shape in points.
heightThe width of the shape in points.
wrapTypeSpecifies how to wrap text around the shape.
Returns
The shape node that was inserted.
Examples

Shows how to insert DML shapes into the document using a document builder.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// There are two ways of shape insertion
// These methods allow inserting DML shape into the document model
// Document must be saved in the format, which supports DML shapes, otherwise, such nodes will be converted
// to VML shape, while document saving
// 1. Free-floating shape insertion
SharedPtr<Shape> freeFloatingShape = builder->InsertShape(ShapeType::TopCornersRounded, RelativeHorizontalPosition::Page, 100, RelativeVerticalPosition::Page, 100, 50, 50, WrapType::None);
freeFloatingShape->set_Rotation(30.0);
// 2. Inline shape insertion
SharedPtr<Shape> inlineShape = builder->InsertShape(ShapeType::DiagonalCornersRounded, 50, 50);
inlineShape->set_Rotation(30.0);
// If you need to create "NonPrimitive" shapes, like SingleCornerSnipped, TopCornersSnipped, DiagonalCornersSnipped,
// TopCornersOneRoundedOneSnipped, SingleCornerRounded, TopCornersRounded, DiagonalCornersRounded
// please save the document with "Strict" or "Transitional" compliance which allows saving shape as DML
auto saveOptions = MakeObject<OoxmlSaveOptions>(SaveFormat::Docx);
saveOptions->set_Compliance(OoxmlCompliance::Iso29500_2008_Transitional);
doc->Save(ArtifactsDir + u"Shape.ShapeInsertion.docx", saveOptions);

◆ InsertShape() [2/2]

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertShape ( Aspose::Words::Drawing::ShapeType  shapeType,
double  width,
double  height 
)

Inserts inline shape with specified type and size.

Parameters
shapeTypeThe shape type to insert into the document.
widthThe width of the shape in points.
heightThe height of the shape in points.
Returns
The shape node that was inserted.
Examples

Shows how to insert DML shapes into the document using a document builder.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// There are two ways of shape insertion
// These methods allow inserting DML shape into the document model
// Document must be saved in the format, which supports DML shapes, otherwise, such nodes will be converted
// to VML shape, while document saving
// 1. Free-floating shape insertion
SharedPtr<Shape> freeFloatingShape = builder->InsertShape(ShapeType::TopCornersRounded, RelativeHorizontalPosition::Page, 100, RelativeVerticalPosition::Page, 100, 50, 50, WrapType::None);
freeFloatingShape->set_Rotation(30.0);
// 2. Inline shape insertion
SharedPtr<Shape> inlineShape = builder->InsertShape(ShapeType::DiagonalCornersRounded, 50, 50);
inlineShape->set_Rotation(30.0);
// If you need to create "NonPrimitive" shapes, like SingleCornerSnipped, TopCornersSnipped, DiagonalCornersSnipped,
// TopCornersOneRoundedOneSnipped, SingleCornerRounded, TopCornersRounded, DiagonalCornersRounded
// please save the document with "Strict" or "Transitional" compliance which allows saving shape as DML
auto saveOptions = MakeObject<OoxmlSaveOptions>(SaveFormat::Docx);
saveOptions->set_Compliance(OoxmlCompliance::Iso29500_2008_Transitional);
doc->Save(ArtifactsDir + u"Shape.ShapeInsertion.docx", saveOptions);

◆ InsertSignatureLine() [1/2]

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertSignatureLine ( System::SharedPtr< Aspose::Words::SignatureLineOptions signatureLineOptions)

Inserts a signature line at the current position.

Parameters
signatureLineOptionsThe object that stores parameters of creating signature line.
Returns
The signature line node that was just inserted.
Examples

Shows how to sign document with personal certificate and specific signature line.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
auto signatureLineOptions = MakeObject<SignatureLineOptions>();
signatureLineOptions->set_Signer(u"vderyushev");
signatureLineOptions->set_SignerTitle(u"QA");
signatureLineOptions->set_Email(u"vderyushev@aspose.com");
signatureLineOptions->set_ShowDate(true);
signatureLineOptions->set_DefaultInstructions(false);
signatureLineOptions->set_Instructions(u"You need more info about signature line");
signatureLineOptions->set_AllowComments(true);
SharedPtr<SignatureLine> signatureLine = builder->InsertSignatureLine(signatureLineOptions)->get_SignatureLine();
signatureLine->set_ProviderId(System::Guid::Parse(u"CF5A7BB4-8F3C-4756-9DF6-BEF7F13259A2"));
doc->Save(ArtifactsDir + u"DocumentBuilder.SignatureLineProviderId.docx");
auto signOptions = MakeObject<SignOptions>();
signOptions->set_SignatureLineId(signatureLine->get_Id());
signOptions->set_ProviderId(signatureLine->get_ProviderId());
signOptions->set_Comments(u"Document was signed by vderyushev");
signOptions->set_SignTime(System::DateTime::get_Now());
SharedPtr<CertificateHolder> certHolder = CertificateHolder::Create(MyDir + u"morzal.pfx", u"aw");
DigitalSignatureUtil::Sign(ArtifactsDir + u"DocumentBuilder.SignatureLineProviderId.docx", ArtifactsDir + u"DocumentBuilder.SignatureLineProviderId.Signed.docx", certHolder, signOptions);

◆ InsertSignatureLine() [2/2]

System::SharedPtr<Aspose::Words::Drawing::Shape> Aspose::Words::DocumentBuilder::InsertSignatureLine ( System::SharedPtr< Aspose::Words::SignatureLineOptions signatureLineOptions,
Aspose::Words::Drawing::RelativeHorizontalPosition  horzPos,
double  left,
Aspose::Words::Drawing::RelativeVerticalPosition  vertPos,
double  top,
Aspose::Words::Drawing::WrapType  wrapType 
)

Inserts a signature line at the specified position.

You can change the image size, location, positioning method and other settings using the Shape object returned by this method.

Parameters
signatureLineOptionsThe object that stores parameters of creating signature line.
horzPosSpecifies where the distance to the signature line is measured from.
leftDistance in points from the origin to the left side of the signature line.
vertPosSpecifies where the distance to the signature line measured from.
topDistance in points from the origin to the top side of the signature line.
wrapTypeSpecifies how to wrap text around the signature line.
Returns
The signature line node that was just inserted.
Examples

Shows how to insert signature line at the specified position.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
auto options = MakeObject<SignatureLineOptions>();
options->set_Signer(u"John Doe");
options->set_SignerTitle(u"Manager");
options->set_Email(u"johndoe@aspose.com");
options->set_ShowDate(true);
options->set_DefaultInstructions(false);
options->set_Instructions(u"You need more info about signature line");
options->set_AllowComments(true);
builder->InsertSignatureLine(options, RelativeHorizontalPosition::RightMargin, 2.0, RelativeVerticalPosition::Page, 3.0, WrapType::Inline);

◆ InsertStyleSeparator()

void Aspose::Words::DocumentBuilder::InsertStyleSeparator ( )

Inserts style separator into the document.

Examples

Shows how to separate styles from two different paragraphs used in one logical printed paragraph.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Append text in the "Heading 1" style
builder->get_ParagraphFormat()->set_StyleIdentifier(StyleIdentifier::Heading1);
builder->Write(u"This text is in a Heading style. ");
// Insert a style separator
builder->InsertStyleSeparator();
// The style separator appears in the form of a paragraph break that doesn't start a new line
// So, while this looks like one continuous paragraph with two styles in the output document,
// it is actually two paragraphs with different styles, but no line break between the first and second paragraph
ASSERT_EQ(2, doc->get_FirstSection()->get_Body()->get_Paragraphs()->get_Count());
// Append text with another style
SharedPtr<Style> paraStyle = builder->get_Document()->get_Styles()->Add(StyleType::Paragraph, u"MyParaStyle");
paraStyle->get_Font()->set_Bold(false);
paraStyle->get_Font()->set_Size(8);
paraStyle->get_Font()->set_Name(u"Arial");
// Set the style of the current paragraph to our custom style
// This will apply to only the text after the style separator
builder->get_ParagraphFormat()->set_StyleName(paraStyle->get_Name());
builder->Write(u"This text is in a custom style. ");
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertStyleSeparator.docx");

◆ InsertTableOfContents()

System::SharedPtr<Aspose::Words::Fields::Field> Aspose::Words::DocumentBuilder::InsertTableOfContents ( System::String  switches)

Inserts a TOC (table of contents) field into the document.

This method inserts a TOC (table of contents) field into the document at the current position.

A table of contents in a Word document can be built in a number of ways and formatted using a variety of options. The way the table is built and displayed by Microsoft Word is controlled by the field switches.

The easiest way to specify the switches is to insert and configure a table of contents into a Word document using the Insert->Reference->Index and Tables menu, then switch display of field codes on to see the switches. You can press Alt+F9 in Microsoft Word to toggle display of field codes on or off.

For example, after creating a table of contents, the following field is inserted into the document: { TOC \o "1-3" \h \z \u }. You can copy \o "1-3" \h \z \u and use it as the switches parameter.

Note that InsertTableOfContents will only insert a TOC field, but will not actually build the table of contents. The table of contents is built by Microsoft Word when the field is updated.

If you insert a table of contents using this method and then open the file in Microsoft Word, you will not see the table of contents because the TOC field has not yet been updated.

In Microsoft Word, fields are not automatically updated when a document is opened, but you can update fields in a document at any time by pressing F9.

Parameters
switchesThe TOC field switches.
Examples

Shows how to insert a Table of contents (TOC) into a document using heading styles as entries.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Insert a table of contents at the beginning of the document,
// and set it to pick up paragraphs with headings of levels 1 to 3 and entries to act like hyperlinks
builder->InsertTableOfContents(u"\\o \"1-3\" \\h \\z \\u");
// Start the actual document content on the second page
builder->InsertBreak(BreakType::PageBreak);
// Build a document with complex structure by applying different heading styles thus creating TOC entries
// The heading levels we use below will affect the list levels in which these items will appear in the TOC,
// and only levels 1-3 will be picked up by our TOC due to its settings
builder->get_ParagraphFormat()->set_StyleIdentifier(StyleIdentifier::Heading1);
builder->Writeln(u"Heading 1");
builder->get_ParagraphFormat()->set_StyleIdentifier(StyleIdentifier::Heading2);
builder->Writeln(u"Heading 1.1");
builder->Writeln(u"Heading 1.2");
builder->get_ParagraphFormat()->set_StyleIdentifier(StyleIdentifier::Heading1);
builder->Writeln(u"Heading 2");
builder->Writeln(u"Heading 3");
builder->get_ParagraphFormat()->set_StyleIdentifier(StyleIdentifier::Heading2);
builder->Writeln(u"Heading 3.1");
builder->get_ParagraphFormat()->set_StyleIdentifier(StyleIdentifier::Heading3);
builder->Writeln(u"Heading 3.1.1");
builder->Writeln(u"Heading 3.1.2");
builder->Writeln(u"Heading 3.1.3");
builder->get_ParagraphFormat()->set_StyleIdentifier(StyleIdentifier::Heading2);
builder->Writeln(u"Heading 3.2");
builder->Writeln(u"Heading 3.3");
// Call the method below to update the TOC and save
doc->UpdateFields();
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertToc.docx");

◆ InsertTextInput()

System::SharedPtr<Aspose::Words::Fields::FormField> Aspose::Words::DocumentBuilder::InsertTextInput ( System::String  name,
Aspose::Words::Fields::TextFormFieldType  type,
System::String  format,
System::String  fieldValue,
int32_t  maxLength 
)

Inserts a text form field at the current position.

If you specify a name for the form field, then a bookmark is automatically created with the same name.

Parameters
nameThe name of the form field. Can be an empty string.
typeSpecifies the type of the text form field.
formatFormat string used to format the value of the form field.
fieldValueText that will be shown in the field.
maxLengthMaximum length the user can enter into the form field. Set to zero for unlimited length.
Returns
The form field node that was just inserted.
Examples

Shows how to build a form field.

auto builder = MakeObject<DocumentBuilder>();
// Insert a text form field for input a name
builder->InsertTextInput(u"", TextFormFieldType::Regular, u"", u"Enter your name here", 30);
// Insert two blank lines
builder->Writeln(u"");
builder->Writeln(u"");
ArrayPtr<String> items = MakeArray<String>({u"-- Select your favorite footwear --", u"Sneakers", u"Oxfords", u"Flip-flops", u"Other", u"I prefer to be barefoot"});
// Insert a combo box to select a footwear type
builder->InsertComboBox(u"", items, 0);
// Insert 2 blank lines
builder->Writeln(u"");
builder->Writeln(u"");
builder->get_Document()->Save(ArtifactsDir + u"DocumentBuilder.CreateForm.docx");

Shows how to insert a text input form field into a document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->InsertTextInput(u"TextInput", TextFormFieldType::Regular, u"", u"Hello", 0);

Shows how to insert form fields, set options and gather them back in for use.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Insert a text input field. The unique name of this field is "TextInput1", the other parameters define
// what type of FormField it is, the format of the text, the field result and the maximum text length (0 = no limit)
builder->InsertTextInput(u"TextInput1", TextFormFieldType::Regular, u"", u"", 0);

◆ Is()

virtual bool Aspose::Words::DocumentBuilder::Is ( const System::TypeInfo target) const
overridevirtual

◆ MoveTo()

void Aspose::Words::DocumentBuilder::MoveTo ( System::SharedPtr< Aspose::Words::Node node)

Moves the cursor to an inline node or to the end of a paragraph.

When node is an inline-level node, the cursor is moved to this node and further content will be inserted before that node.

When node is a Paragraph, the cursor is moved to the end of the paragraph and further content will be inserted just before the paragraph break.

When node is a block-level node but not a Paragraph, the cursor is moved to the end of the first paragraph into block-level node and further content will be inserted just before the paragraph break.

Parameters
nodeThe node must be a paragraph or a direct child of a paragraph.
Examples

Shows how to move a DocumentBuilder to different nodes in a document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Start a bookmark and add content to it using a DocumentBuilder
builder->StartBookmark(u"MyBookmark");
builder->Writeln(u"Bookmark contents.");
builder->EndBookmark(u"MyBookmark");
// The node that the DocumentBuilder is currently at is past the boundaries of the bookmark
ASPOSE_ASSERT_EQ(doc->get_Range()->get_Bookmarks()->idx_get(0)->get_BookmarkEnd(), builder->get_CurrentParagraph()->get_FirstChild());
// If we wish to revise the content of our bookmark with the DocumentBuilder, we can move back to it like this
builder->MoveToBookmark(u"MyBookmark");
// Now we're located between the bookmark's BookmarkStart and BookmarkEnd nodes, so any text the builder adds will be within it
ASPOSE_ASSERT_EQ(doc->get_Range()->get_Bookmarks()->idx_get(0)->get_BookmarkStart(), builder->get_CurrentParagraph()->get_FirstChild());
// We can move the builder to an individual node,
// which in this case will be the first node of the first paragraph, like this
builder->MoveTo(doc->get_FirstSection()->get_Body()->get_FirstParagraph()->GetChildNodes(NodeType::Any, false)->idx_get(0));
ASSERT_EQ(NodeType::BookmarkStart, builder->get_CurrentNode()->get_NodeType());
ASSERT_TRUE(builder->get_IsAtStartOfParagraph());
// A shorter way of moving the very start/end of a document is with these methods
builder->MoveToDocumentEnd();
ASSERT_TRUE(builder->get_IsAtEndOfParagraph());
builder->MoveToDocumentStart();
ASSERT_TRUE(builder->get_IsAtStartOfParagraph());

Shows how to move a DocumentBuilder's cursor position to a specified node.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Write a paragraph with the DocumentBuilder
builder->Writeln(u"Text 1. ");
// Move the DocumentBuilder to the first paragraph of the document and add another paragraph
builder->MoveTo(doc->get_FirstSection()->get_Body()->get_FirstParagraph()->get_Runs()->idx_get(0));
builder->Writeln(u"Text 2. ");
// Since we moved to a node before the first paragraph before we added a second paragraph,
// the second paragraph will appear in front of the first paragraph
ASSERT_EQ(u"Text 2. \rText 1.", doc->GetText().Trim());
// We can move the DocumentBuilder back to the end of the document like this
// and carry on adding text to the end of the document
builder->MoveTo(doc->get_FirstSection()->get_Body()->get_LastParagraph());
builder->Writeln(u"Text 3. ");
ASSERT_EQ(u"Text 2. \rText 1. \rText 3.", doc->GetText().Trim());

◆ MoveToBookmark() [1/2]

bool Aspose::Words::DocumentBuilder::MoveToBookmark ( System::String  bookmarkName)

Moves the cursor to a bookmark.

Moves the cursor to a position just after the start of the bookmark with the specified name.

The comparison is not case-sensitive. If the bookmark was not found, false is returned and the cursor is not moved.

Inserting new text does not replace existing text of the bookmark.

Note that some bookmarks in the document are assigned to form fields. Moving to such a bookmark and inserting text there inserts the text into the form field code. Although this will not invalidate the form field, the inserted text will not be visible because it becomes part of the field code.

Parameters
bookmarkNameThe name of the bookmark to move the cursor to.
Returns
True if the bookmark was found; false otherwise.
Examples

Shows how to move a DocumentBuilder to different nodes in a document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Start a bookmark and add content to it using a DocumentBuilder
builder->StartBookmark(u"MyBookmark");
builder->Writeln(u"Bookmark contents.");
builder->EndBookmark(u"MyBookmark");
// The node that the DocumentBuilder is currently at is past the boundaries of the bookmark
ASPOSE_ASSERT_EQ(doc->get_Range()->get_Bookmarks()->idx_get(0)->get_BookmarkEnd(), builder->get_CurrentParagraph()->get_FirstChild());
// If we wish to revise the content of our bookmark with the DocumentBuilder, we can move back to it like this
builder->MoveToBookmark(u"MyBookmark");
// Now we're located between the bookmark's BookmarkStart and BookmarkEnd nodes, so any text the builder adds will be within it
ASPOSE_ASSERT_EQ(doc->get_Range()->get_Bookmarks()->idx_get(0)->get_BookmarkStart(), builder->get_CurrentParagraph()->get_FirstChild());
// We can move the builder to an individual node,
// which in this case will be the first node of the first paragraph, like this
builder->MoveTo(doc->get_FirstSection()->get_Body()->get_FirstParagraph()->GetChildNodes(NodeType::Any, false)->idx_get(0));
ASSERT_EQ(NodeType::BookmarkStart, builder->get_CurrentNode()->get_NodeType());
ASSERT_TRUE(builder->get_IsAtStartOfParagraph());
// A shorter way of moving the very start/end of a document is with these methods
builder->MoveToDocumentEnd();
ASSERT_TRUE(builder->get_IsAtEndOfParagraph());
builder->MoveToDocumentStart();
ASSERT_TRUE(builder->get_IsAtStartOfParagraph());

◆ MoveToBookmark() [2/2]

bool Aspose::Words::DocumentBuilder::MoveToBookmark ( System::String  bookmarkName,
bool  isStart,
bool  isAfter 
)

Moves the cursor to a bookmark with greater precision.

Moves the cursor to a position before or after the bookmark start or end.

If desired position is not at inline level, moves to the next paragraph.

The comparison is not case-sensitive. If the bookmark was not found, false is returned and the cursor is not moved.

Parameters
bookmarkNameThe name of the bookmark to move the cursor to.
isStartWhen true, moves the cursor to the beginning of the bookmark. When false, moves the cursor to the end of the bookmark.
isAfterWhen true, moves the cursor to be after the bookmark start or end position. When false, moves the cursor to be before the bookmark start or end position.
Returns
True if the bookmark was found; false otherwise.
Examples

Shows how to move a cursor position to just after the bookmark end.

auto doc = MakeObject<Document>(MyDir + u"Bookmarks.docx");
auto builder = MakeObject<DocumentBuilder>(doc);
// Move to after the end of the first bookmark
ASSERT_TRUE(builder->MoveToBookmark(u"MyBookmark1", false, true));
builder->Write(u" Text appended via DocumentBuilder.");

◆ MoveToCell()

void Aspose::Words::DocumentBuilder::MoveToCell ( int32_t  tableIndex,
int32_t  rowIndex,
int32_t  columnIndex,
int32_t  characterIndex 
)

Moves the cursor to a table cell in the current section.

The navigation is performed inside the current story of the current section.

For the index parameters, when index is greater than or equal to 0, it specifies an index from the beginning with 0 being the first element. When index is less than 0, it specified an index from the end with -1 being the last element.

Parameters
tableIndexThe index of the table to move to.
rowIndexThe index of the row in the table.
columnIndexThe index of the column in the table.
characterIndexThe index of the character inside the cell. Currently can only specify 0 to move to the beginning of the cell or -1 to move to the end of the cell.
Examples

Shows how to move a cursor position to the specified table cell.

auto doc = MakeObject<Document>(MyDir + u"Tables.docx");
auto builder = MakeObject<DocumentBuilder>(doc);
// Move the builder to row 3, cell 4 of the first table
builder->MoveToCell(0, 2, 3, 0);
builder->Write(u"\nCell contents added by DocumentBuilder");

◆ MoveToDocumentEnd()

void Aspose::Words::DocumentBuilder::MoveToDocumentEnd ( )

Moves the cursor to the end of the document.

Examples

Shows how to move a DocumentBuilder to different nodes in a document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Start a bookmark and add content to it using a DocumentBuilder
builder->StartBookmark(u"MyBookmark");
builder->Writeln(u"Bookmark contents.");
builder->EndBookmark(u"MyBookmark");
// The node that the DocumentBuilder is currently at is past the boundaries of the bookmark
ASPOSE_ASSERT_EQ(doc->get_Range()->get_Bookmarks()->idx_get(0)->get_BookmarkEnd(), builder->get_CurrentParagraph()->get_FirstChild());
// If we wish to revise the content of our bookmark with the DocumentBuilder, we can move back to it like this
builder->MoveToBookmark(u"MyBookmark");
// Now we're located between the bookmark's BookmarkStart and BookmarkEnd nodes, so any text the builder adds will be within it
ASPOSE_ASSERT_EQ(doc->get_Range()->get_Bookmarks()->idx_get(0)->get_BookmarkStart(), builder->get_CurrentParagraph()->get_FirstChild());
// We can move the builder to an individual node,
// which in this case will be the first node of the first paragraph, like this
builder->MoveTo(doc->get_FirstSection()->get_Body()->get_FirstParagraph()->GetChildNodes(NodeType::Any, false)->idx_get(0));
ASSERT_EQ(NodeType::BookmarkStart, builder->get_CurrentNode()->get_NodeType());
ASSERT_TRUE(builder->get_IsAtStartOfParagraph());
// A shorter way of moving the very start/end of a document is with these methods
builder->MoveToDocumentEnd();
ASSERT_TRUE(builder->get_IsAtEndOfParagraph());
builder->MoveToDocumentStart();
ASSERT_TRUE(builder->get_IsAtStartOfParagraph());

◆ MoveToDocumentStart()

void Aspose::Words::DocumentBuilder::MoveToDocumentStart ( )

Moves the cursor to the beginning of the document.

Examples

Shows how to move a DocumentBuilder to different nodes in a document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Start a bookmark and add content to it using a DocumentBuilder
builder->StartBookmark(u"MyBookmark");
builder->Writeln(u"Bookmark contents.");
builder->EndBookmark(u"MyBookmark");
// The node that the DocumentBuilder is currently at is past the boundaries of the bookmark
ASPOSE_ASSERT_EQ(doc->get_Range()->get_Bookmarks()->idx_get(0)->get_BookmarkEnd(), builder->get_CurrentParagraph()->get_FirstChild());
// If we wish to revise the content of our bookmark with the DocumentBuilder, we can move back to it like this
builder->MoveToBookmark(u"MyBookmark");
// Now we're located between the bookmark's BookmarkStart and BookmarkEnd nodes, so any text the builder adds will be within it
ASPOSE_ASSERT_EQ(doc->get_Range()->get_Bookmarks()->idx_get(0)->get_BookmarkStart(), builder->get_CurrentParagraph()->get_FirstChild());
// We can move the builder to an individual node,
// which in this case will be the first node of the first paragraph, like this
builder->MoveTo(doc->get_FirstSection()->get_Body()->get_FirstParagraph()->GetChildNodes(NodeType::Any, false)->idx_get(0));
ASSERT_EQ(NodeType::BookmarkStart, builder->get_CurrentNode()->get_NodeType());
ASSERT_TRUE(builder->get_IsAtStartOfParagraph());
// A shorter way of moving the very start/end of a document is with these methods
builder->MoveToDocumentEnd();
ASSERT_TRUE(builder->get_IsAtEndOfParagraph());
builder->MoveToDocumentStart();
ASSERT_TRUE(builder->get_IsAtStartOfParagraph());

◆ MoveToField()

void Aspose::Words::DocumentBuilder::MoveToField ( System::SharedPtr< Aspose::Words::Fields::Field field,
bool  isAfter 
)

Moves the cursor to a field in the document.

Parameters
fieldThe field to move the cursor to.
isAfterWhen true, moves the cursor to be after the field end. When false, moves the cursor to be before the field start.
Examples

Shows how to move document builder's cursor to a specific field.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Insert a field using the DocumentBuilder and add a run of text after it
SharedPtr<Field> field = builder->InsertField(u"MERGEFIELD field");
builder->Write(u" Text after the field.");
// The builder's cursor is currently at end of the document
ASSERT_TRUE(builder->get_CurrentNode() == nullptr);
// We can move the builder to a field like this, placing the cursor at immediately after the field
builder->MoveToField(field, true);
// Note that the cursor is at a place past the FieldEnd node of the field, meaning that we are not actually inside the field
// If we wish to move the DocumentBuilder to inside a field,
// we will need to move it to a field's FieldStart or FieldSeparator node using the DocumentBuilder.MoveTo() method
ASPOSE_ASSERT_EQ(field->get_End(), builder->get_CurrentNode()->get_PreviousSibling());
builder->Write(u" Text immediately after the field.");

◆ MoveToHeaderFooter()

void Aspose::Words::DocumentBuilder::MoveToHeaderFooter ( Aspose::Words::HeaderFooterType  headerFooterType)

Moves the cursor to the beginning of a header or footer in the current section.

After you moved the cursor into a header or footer, you can use the rest of DocumentBuilder methods to modify the contents of the header or footer.

If you want to create headers and footers different for the first page, you need to set DifferentFirstPageHeaderFooter.

If you want to create headers and footers different for even and odd pages, you need to set OddAndEvenPagesHeaderFooter.

Use MoveToSection() to move out of the header into the main text.

Parameters
headerFooterTypeSpecifies the header or footer to move to.
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 headers and footers different for first, even and odd pages
builder->get_PageSetup()->set_DifferentFirstPageHeaderFooter(true);
builder->get_PageSetup()->set_OddAndEvenPagesHeaderFooter(true);
// Create the headers
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");
// Create three pages in the document
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 a watermark image into a document using DocumentBuilder.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// The best place for the watermark image is in the header or footer so it is shown on every page
builder->MoveToHeaderFooter(HeaderFooterType::HeaderPrimary);
SharedPtr<System::Drawing::Image> image = System::Drawing::Image::FromFile(ImageDir + u"Transparent background logo.png");
// Insert a floating picture
SharedPtr<Shape> shape = builder->InsertImage(image);
shape->set_WrapType(WrapType::None);
shape->set_BehindText(true);
shape->set_RelativeHorizontalPosition(RelativeHorizontalPosition::Page);
shape->set_RelativeVerticalPosition(RelativeVerticalPosition::Page);
// Calculate image left and top position so it appears in the center of the page
shape->set_Left((builder->get_PageSetup()->get_PageWidth() - shape->get_Width()) / 2);
shape->set_Top((builder->get_PageSetup()->get_PageHeight() - shape->get_Height()) / 2);
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertWatermark.docx");

◆ MoveToMergeField() [1/2]

bool Aspose::Words::DocumentBuilder::MoveToMergeField ( System::String  fieldName)

Moves the cursor to a position just beyond the specified merge field and removes the merge field.

Note that this method deletes the merge field from the document after moving the cursor.

Parameters
fieldNameThe case-insensitive name of the mail merge field.
Returns
True if the merge field was found and the cursor was moved; false otherwise.
Examples

Shows how to fill MERGEFIELDs with data with a DocumentBuilder and without a mail merge.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Insert some MERGEFIELDS, which accept data from columns of the same name in a data source during a mail merge
builder->InsertField(u" MERGEFIELD Chairman ");
builder->InsertField(u" MERGEFIELD ChiefFinancialOfficer ");
builder->InsertField(u" MERGEFIELD ChiefTechnologyOfficer ");
// They can also be filled in manually like this
builder->MoveToMergeField(u"Chairman");
builder->set_Bold(true);
builder->Writeln(u"John Doe");
builder->MoveToMergeField(u"ChiefFinancialOfficer");
builder->set_Italic(true);
builder->Writeln(u"Jane Doe");
builder->MoveToMergeField(u"ChiefTechnologyOfficer");
builder->set_Italic(true);
builder->Writeln(u"John Bloggs");
doc->Save(ArtifactsDir + u"DocumentBuilder.FillMergeFields.docx");

◆ MoveToMergeField() [2/2]

bool Aspose::Words::DocumentBuilder::MoveToMergeField ( System::String  fieldName,
bool  isAfter,
bool  isDeleteField 
)

Moves the merge field to the specified merge field.

Parameters
fieldNameThe case-insensitive name of the mail merge field.
isAfterWhen true, moves the cursor to be after the field end. When false, moves the cursor to be before the field start.
isDeleteFieldWhen true, deletes the merge field.
Returns
True if the merge field was found and the cursor was moved; false otherwise.
Examples

Shows how to insert merge fields and move between them.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->InsertField(u"MERGEFIELD MyMergeField1 \\* MERGEFORMAT");
builder->InsertField(u"MERGEFIELD MyMergeField2 \\* MERGEFORMAT");
// The second merge field starts immediately after the end of the first
// We'll move the builder's cursor to the end of the first so we can split them by text
builder->MoveToMergeField(u"MyMergeField1", true, false);
ASPOSE_ASSERT_EQ(doc->get_Range()->get_Fields()->idx_get(1)->get_Start(), builder->get_CurrentNode());
builder->Write(u" Text between our two merge fields. ");
doc->Save(ArtifactsDir + u"DocumentBuilder.MergeFields.docx");

◆ MoveToParagraph()

void Aspose::Words::DocumentBuilder::MoveToParagraph ( int32_t  paragraphIndex,
int32_t  characterIndex 
)

Moves the cursor to a paragraph in the current section.

The navigation is performed inside the current story of the current section. That is, if you moved the cursor to the primary header of the first section, then paragraphIndex specified the index of the paragraph inside that header of that section.

When paragraphIndex is greater than or equal to 0, it specifies an index from the beginning of the section with 0 being the first paragraph. When paragraphIndex is less than 0, it specified an index from the end of the section with -1 being the last paragraph.

Parameters
paragraphIndexThe index of the paragraph to move to.
characterIndexThe index of the character inside the paragraph. Currently can only specify 0 to move to the beginning of the paragraph or -1 to move to the end of the paragraph.
Examples

Shows how to move a cursor position to the specified paragraph.

// Open a document with a lot of paragraphs
auto doc = MakeObject<Document>(MyDir + u"Paragraphs.docx");
SharedPtr<ParagraphCollection> paragraphs = doc->get_FirstSection()->get_Body()->get_Paragraphs();
ASSERT_EQ(22, paragraphs->get_Count());
// When we create a DocumentBuilder for a document, its cursor is at the very beginning of the document by default,
// and any content added by the DocumentBuilder will just be prepended to the document
auto builder = MakeObject<DocumentBuilder>(doc);
ASSERT_EQ(0, paragraphs->IndexOf(builder->get_CurrentParagraph()));
// We can manually move the DocumentBuilder to any paragraph in the document via a 0-based index like this
builder->MoveToParagraph(2, 0);
builder->Writeln(u"This is a new third paragraph. ");

◆ MoveToSection()

void Aspose::Words::DocumentBuilder::MoveToSection ( int32_t  sectionIndex)

Moves the cursor to the beginning of the body in a specified section.

When sectionIndex is greater than or equal to 0, it specifies an index from the beginning of the document with 0 being the first section. When sectionIndex is less than 0, it specified an index from the end of the document with -1 being the last section.

The cursor is moved to the first paragraph in the Body of the specified section.

Parameters
sectionIndexThe index of the section to move to.
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 headers and footers different for first, even and odd pages
builder->get_PageSetup()->set_DifferentFirstPageHeaderFooter(true);
builder->get_PageSetup()->set_OddAndEvenPagesHeaderFooter(true);
// Create the headers
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");
// Create three pages in the document
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");

◆ PopFont()

void Aspose::Words::DocumentBuilder::PopFont ( )

Retrieves character formatting previously saved on the stack.

See also
Aspose::Words::DocumentBuilder::get_Font
Aspose::Words::DocumentBuilder::PushFont
Examples

Shows how to use temporarily save and restore character formatting when building a document with DocumentBuilder.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Set up font formatting and write text that goes before the hyperlink
builder->get_Font()->set_Name(u"Arial");
builder->get_Font()->set_Size(24);
builder->get_Font()->set_Bold(true);
builder->Write(u"To visit Google, hold Ctrl and click ");
// Save the font formatting so we use different formatting for hyperlink and restore old formatting later
builder->PushFont();
// Set new font formatting for the hyperlink and insert the hyperlink
// The "Hyperlink" style is a Microsoft Word built-in style so we don't have to worry to
// create it, it will be created automatically if it does not yet exist in the document
builder->get_Font()->set_StyleIdentifier(StyleIdentifier::Hyperlink);
builder->InsertHyperlink(u"here", u"http://www.google.com", false);
// Restore the formatting that was before the hyperlink
builder->PopFont();
builder->Write(u". We hope you enjoyed the example.");
doc->Save(ArtifactsDir + u"DocumentBuilder.PushPopFont.docx");

◆ PushFont()

void Aspose::Words::DocumentBuilder::PushFont ( )

Saves current character formatting onto the stack.

See also
Aspose::Words::DocumentBuilder::get_Font
Aspose::Words::DocumentBuilder::PopFont
Examples

Shows how to use temporarily save and restore character formatting when building a document with DocumentBuilder.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Set up font formatting and write text that goes before the hyperlink
builder->get_Font()->set_Name(u"Arial");
builder->get_Font()->set_Size(24);
builder->get_Font()->set_Bold(true);
builder->Write(u"To visit Google, hold Ctrl and click ");
// Save the font formatting so we use different formatting for hyperlink and restore old formatting later
builder->PushFont();
// Set new font formatting for the hyperlink and insert the hyperlink
// The "Hyperlink" style is a Microsoft Word built-in style so we don't have to worry to
// create it, it will be created automatically if it does not yet exist in the document
builder->get_Font()->set_StyleIdentifier(StyleIdentifier::Hyperlink);
builder->InsertHyperlink(u"here", u"http://www.google.com", false);
// Restore the formatting that was before the hyperlink
builder->PopFont();
builder->Write(u". We hope you enjoyed the example.");
doc->Save(ArtifactsDir + u"DocumentBuilder.PushPopFont.docx");

◆ set_Bold()

void Aspose::Words::DocumentBuilder::set_Bold ( bool  value)

◆ set_Document()

void Aspose::Words::DocumentBuilder::set_Document ( System::SharedPtr< Aspose::Words::Document value)

◆ set_Italic()

void Aspose::Words::DocumentBuilder::set_Italic ( bool  value)

◆ set_Underline()

void Aspose::Words::DocumentBuilder::set_Underline ( Aspose::Words::Underline  value)

◆ StartBookmark()

System::SharedPtr<Aspose::Words::BookmarkStart> Aspose::Words::DocumentBuilder::StartBookmark ( System::String  bookmarkName)

Marks the current position in the document as a bookmark start.

Bookmarks in a document can overlap and span any range. To create a valid bookmark you need to call both StartBookmark() and EndBookmark() with the same bookmarkName parameter.

Badly formed bookmarks or bookmarks with duplicate names will be ignored when the document is saved.

Parameters
bookmarkNameName of the bookmark.
Returns
The bookmark start node that was just created.
Examples

Shows how to add some text into the document and encloses the text in a bookmark using DocumentBuilder.

auto builder = MakeObject<DocumentBuilder>();
builder->StartBookmark(u"MyBookmark");
builder->Writeln(u"Text inside a bookmark.");
builder->EndBookmark(u"MyBookmark");

Shows how to insert a hyperlink referencing a local bookmark.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->StartBookmark(u"Bookmark1");
builder->Write(u"Bookmarked text.");
builder->EndBookmark(u"Bookmark1");
builder->Writeln(u"Some other text");
// Specify font formatting for the hyperlink
builder->get_Font()->set_Color(System::Drawing::Color::get_Blue());
builder->get_Font()->set_Underline(Underline::Single);
// Insert hyperlink
// Switch \o is used to provide hyperlink tip text
builder->InsertHyperlink(u"Hyperlink Text", u"Bookmark1\" \\o \"Hyperlink Tip", true);
// Clear hyperlink formatting
builder->get_Font()->ClearFormatting();
doc->Save(ArtifactsDir + u"DocumentBuilder.InsertHyperlinkToLocalBookmark.docx");

◆ StartEditableRange()

System::SharedPtr<Aspose::Words::EditableRangeStart> Aspose::Words::DocumentBuilder::StartEditableRange ( )

Marks the current position in the document as an editable range start.

Editable range in a document can overlap and span any range. To create a valid editable range you need to call both StartEditableRange and EndEditableRange or EndEditableRange() methods.

Badly formed editable range will be ignored when the document is saved.

Returns
The editable range start node that was just created.

◆ StartTable()

System::SharedPtr<Aspose::Words::Tables::Table> Aspose::Words::DocumentBuilder::StartTable ( )

Starts a table in the document.

The next method to call is InsertCell.

This method starts a nested table when called inside a cell.

Returns
The table node that was just created.
Examples

Shows how to build a nice bordered table.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Start building a table
builder->StartTable();
// Set the appropriate paragraph, cell, and row formatting. The formatting properties are preserved
// until they are explicitly modified so there's no need to set them for each row or cell
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();
// Remove the shading (clear background)
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();
builder->InsertCell();
// Make the row height bigger so that a vertically oriented text could fit into cells
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 build a formatted table that contains 2 rows and 2 columns.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<Table> table = builder->StartTable();
// Insert a cell
builder->InsertCell();
builder->get_CellFormat()->set_VerticalAlignment(CellVerticalAlignment::Center);
builder->Write(u"This is row 1 cell 1");
// Use fixed column widths
table->AutoFit(AutoFitBehavior::FixedColumnWidths);
// Insert a cell
builder->InsertCell();
builder->Write(u"This is row 1 cell 2");
builder->EndRow();
// Insert a cell
builder->InsertCell();
// Apply new row formatting
builder->get_RowFormat()->set_Height(100);
builder->get_RowFormat()->set_HeightRule(HeightRule::Exactly);
builder->get_CellFormat()->set_Orientation(TextOrientation::Upward);
builder->Write(u"This is row 2 cell 1");
// Insert a cell
builder->InsertCell();
builder->get_CellFormat()->set_Orientation(TextOrientation::Downward);
builder->Write(u"This is row 2 cell 2");
builder->EndRow();
builder->EndTable();

Shows how to create a table that contains a single formatted cell.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->StartTable();
builder->InsertCell();
// Set the cell formatting
SharedPtr<CellFormat> cellFormat = builder->get_CellFormat();
cellFormat->set_Width(250);
cellFormat->set_LeftPadding(30);
cellFormat->set_RightPadding(30);
cellFormat->set_TopPadding(30);
cellFormat->set_BottomPadding(30);
builder->Write(u"Formatted cell");
builder->EndRow();
builder->EndTable();
doc->Save(ArtifactsDir + u"DocumentBuilder.DocumentBuilderSetCellFormatting.docx");

◆ Type()

static const System::TypeInfo& Aspose::Words::DocumentBuilder::Type ( )
static

◆ Write()

void Aspose::Words::DocumentBuilder::Write ( System::String  text)

Inserts a string into the document at the current insert position.

Parameters
textThe string to insert into the document.
Examples

Shows how to insert a string surrounded by a border into a document.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
builder->get_Font()->get_Border()->set_Color(System::Drawing::Color::get_Green());
builder->get_Font()->get_Border()->set_LineWidth(2.5);
builder->get_Font()->get_Border()->set_LineStyle(LineStyle::DashDotStroker);
builder->Write(u"Text surrounded by green border.");
doc->Save(ArtifactsDir + u"Border.FontBorder.docx");

Shows how to build a nice bordered table.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// Start building a table
builder->StartTable();
// Set the appropriate paragraph, cell, and row formatting. The formatting properties are preserved
// until they are explicitly modified so there's no need to set them for each row or cell
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();
// Remove the shading (clear background)
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();
builder->InsertCell();
// Make the row height bigger so that a vertically oriented text could fit into cells
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 create a simple table using DocumentBuilder with default formatting.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
// We call this method to start building the table
builder->StartTable();
builder->InsertCell();
builder->Write(u"Row 1, Cell 1 Content.");
// Build the second cell
builder->InsertCell();
builder->Write(u"Row 1, Cell 2 Content.");
// Call the following method to end the row and start a new row
builder->EndRow();
// Build the first cell of the second row
builder->InsertCell();
builder->Write(u"Row 2, Cell 1 Content.");
// Build the second cell.
builder->InsertCell();
builder->Write(u"Row 2, Cell 2 Content.");
builder->EndRow();
// Signal that we have finished building the table
builder->EndTable();
// Save the document to disk
doc->Save(ArtifactsDir + u"DocumentBuilder.CreateSimpleTable.docx");

Shows how to build a formatted table that contains 2 rows and 2 columns.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<Table> table = builder->StartTable();
// Insert a cell
builder->InsertCell();
builder->get_CellFormat()->set_VerticalAlignment(CellVerticalAlignment::Center);
builder->Write(u"This is row 1 cell 1");
// Use fixed column widths
table->AutoFit(AutoFitBehavior::FixedColumnWidths);
// Insert a cell
builder->InsertCell();
builder->Write(u"This is row 1 cell 2");
builder->EndRow();
// Insert a cell
builder->InsertCell();
// Apply new row formatting
builder->get_RowFormat()->set_Height(100);
builder->get_RowFormat()->set_HeightRule(HeightRule::Exactly);
builder->get_CellFormat()->set_Orientation(TextOrientation::Upward);
builder->Write(u"This is row 2 cell 1");
// Insert a cell
builder->InsertCell();
builder->get_CellFormat()->set_Orientation(TextOrientation::Downward);
builder->Write(u"This is row 2 cell 2");
builder->EndRow();
builder->EndTable();

◆ Writeln() [1/2]

void Aspose::Words::DocumentBuilder::Writeln ( )

Inserts a paragraph break into the document.

Calls InsertParagraph.

◆ Writeln() [2/2]

void Aspose::Words::DocumentBuilder::Writeln ( System::String  text)

Inserts a string and a paragraph break into the document.

Parameters
textThe string to insert into the document.
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 headers and footers different for first, even and odd pages
builder->get_PageSetup()->set_DifferentFirstPageHeaderFooter(true);
builder->get_PageSetup()->set_OddAndEvenPagesHeaderFooter(true);
// Create the headers
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");
// Create three pages in the document
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 formatted table that contains 2 rows and 2 columns.

auto doc = MakeObject<Document>();
auto builder = MakeObject<DocumentBuilder>(doc);
SharedPtr<Table> table = builder->StartTable();
// Insert a cell
builder->InsertCell();
builder->get_CellFormat()->set_VerticalAlignment(CellVerticalAlignment::Center);
builder->Write(u"This is row 1 cell 1");
// Use fixed column widths
table->AutoFit(AutoFitBehavior::FixedColumnWidths);
// Insert a cell
builder->InsertCell();
builder->Write(u"This is row 1 cell 2");
builder->EndRow();
// Insert a cell
builder->InsertCell();
// Apply new row formatting
builder->get_RowFormat()->set_Height(100);
builder->get_RowFormat()->set_HeightRule(HeightRule::Exactly);
builder->get_CellFormat()->set_Orientation(TextOrientation::Upward);
builder->Write(u"This is row 2 cell 1");
// Insert a cell
builder->InsertCell();
builder->get_CellFormat()->set_Orientation(TextOrientation::Downward);
builder->Write(u"This is row 2 cell 2");
builder->EndRow();
builder->EndTable();
static ASPOSECPP_SHARED_API Color get_White()
String
@ Open
static ASPOSECPP_SHARED_API Color get_GreenYellow()
@ PageBreak
Explicit page break.
@ AtLeast
The height will be at least the specified height in points. It will grow, if needed,...
@ Engrave3D
@ Downward
Text is rotated 90 degrees to the right to appear from top to bottom (tb-rl).
@ HeaderEven
Header for even numbered pages.
@ Heading3
The Heading 3 style.
static ASPOSECPP_SHARED_API FileStreamPtr OpenRead(const String &path)
static ASPOSECPP_SHARED_API DateTime Parse(const String &s)
static ASPOSECPP_SHARED_API DateTime get_Now()
static ASPOSECPP_SHARED_API SharedPtr< Image > FromStream(const SharedPtr< System::IO::Stream > &stream, bool use_embedded_color_management=false, bool validate_image_data=1)
static void Sign(System::SharedPtr< System::IO::Stream > srcStream, System::SharedPtr< System::IO::Stream > dstStream, System::SharedPtr< Aspose::Words::CertificateHolder > certHolder, System::SharedPtr< Aspose::Words::SignOptions > signOptions)
Signs source document using given CertificateHolder and SignOptions with digital signature and writes...
static ASPOSECPP_SHARED_API FileStreamPtr Open(const String &path, FileMode mode)
static ASPOSECPP_SHARED_API SharedPtr< Image > FromFile(const String &filename, bool use_embedded_color_management=false)
@ HeaderFirst
Header for the first page of the section.
@ Docx
Saves the document as an Office Open XML WordprocessingML Document (macro-free).
static ASPOSECPP_SHARED_API Guid Parse(const String &input)
@ DashDotStroker
@ Heading1
The Heading 1 style.
static ASPOSECPP_SHARED_API Color FromArgb(int argb)
@ Distributed
Text is evenly distributed.
@ Center
Text is aligned in the middle of the page.
static ASPOSECPP_SHARED_API Color get_Orange()
@ UppercaseRoman
Upper case Roman (I, II, III, ...)
@ Paragraph
The style is a paragraph style.
@ KeepSourceFormatting
Copy all required styles to the destination document, generate unique style names if needed.
static ASPOSECPP_SHARED_API Color get_Green()
@ Justify
Text is aligned to both left and right.
@ HeaderPrimary
Primary header, also used for odd numbered pages.
@ MainText
Contains the main text of the document, represented by Body.
@ Dash
@ Upward
Text is rotated 90 degrees to the left to appear from bottom to top (bt-lr).
static ImageFormatPtr get_Png()
@ Arabic
Arabic numbering (1, 2, 3, ...)
@ Heading2
The Heading 2 style.
static System::SharedPtr< Aspose::Words::CertificateHolder > Create(System::ArrayPtr< uint8_t > certBytes, System::SharedPtr< System::Security::SecureString > password)
Creates CertificateHolder object using byte array of PKCS12 store and its password.
static ASPOSECPP_SHARED_API Color get_Blue()
@ Exactly
The height is specified exactly in points. Please note that if the text cannot fit inside the object ...
@ Hyperlink
The Hyperlink style.
@ Endnote
The object is an endnote.
@ Auto
The height will grow automatically to accommodate all text inside an object.
static ASPOSECPP_SHARED_API Color get_Red()
@ BookmarkStart
A beginning of a bookmark marker.
static ASPOSECPP_SHARED_API DateTime get_Today()
@ Footnote
The object is a footnote.
@ Single
static double PixelToPoint(double pixels)
Converts pixels to points at 96 dpi.
@ Landscape
Landscape page orientation (wide and short).
@ Any
Indicates all node types. Allows to select all children.
@ SectionBreakNewPage
Specifies start of new section on a new page.
@ Center
Text is centered horizontally.