DocumentBuilder Class
Provides methods to insert text, images and other content, specify font, paragraph and section formatting.
Inheritance Hierarchy
SystemObject
  Aspose.WordsDocumentBuilder

Namespace: Aspose.Words
Assembly: Aspose.Words (in Aspose.Words.dll) Version: 17.6
Syntax
public class DocumentBuilder

public class DocumentBuilder

The DocumentBuilder type exposes the following members.

Constructors
  NameDescription
Public methodCode exampleDocumentBuilder
Initializes a new instance of this class.
Public methodCode exampleDocumentBuilder(Document)
Initializes a new instance of this class.
Top
Properties
  NameDescription
Public propertyCode exampleBold
True if the font is formatted as bold.
Public propertyCode exampleCellFormat
Returns an object that represents current table cell formatting properties.
Public propertyCode exampleCurrentNode
Gets the node that is currently selected in this DocumentBuilder.
Public propertyCode exampleCurrentParagraph
Gets the paragraph that is currently selected in this DocumentBuilder.
Public propertyCode exampleCurrentSection
Gets the section that is currently selected in this DocumentBuilder.
Public propertyCurrentStory
Gets the story that is currently selected in this DocumentBuilder.
Public propertyCode exampleDocument
Gets or sets the Document object that this object is attached to.
Public propertyCode exampleFont
Returns an object that represents current font formatting properties.
Public propertyIsAtEndOfParagraph
Returns true if the cursor is at the end of the current paragraph.
Public propertyIsAtStartOfParagraph
Returns true if the cursor is at the beginning of the current paragraph (no text before the cursor).
Public propertyCode exampleItalic
True if the font is formatted as italic.
Public propertyCode exampleListFormat
Returns an object that represents current list formatting properties.
Public propertyCode examplePageSetup
Returns an object that represents current page setup and section properties.
Public propertyCode exampleParagraphFormat
Returns an object that represents current paragraph formatting properties.
Public propertyCode exampleRowFormat
Returns an object that represents current table row formatting properties.
Public propertyUnderline
Gets/sets underline type for the current font.
Top
Methods
  NameDescription
Public methodDeleteRow
Deletes a row from a table.
Public methodCode exampleEndBookmark
Marks the current position in the document as a bookmark end.
Public methodEndEditableRange
Marks the current position in the document as an editable range end.
Public methodEndEditableRange(EditableRangeStart)
Marks the current position in the document as an editable range end.
Public methodCode exampleEndRow
Ends a table row in the document.
Public methodCode exampleEndTable
Ends a table in the document.
Public methodEquals
Determines whether the specified Object is equal to the current Object.
(Inherited from Object.)
Protected methodFinalize
Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.
(Inherited from Object.)
Public methodGetHashCode
Serves as a hash function for a particular type.
(Inherited from Object.)
Public methodGetType
Gets the type of the current instance.
(Inherited from Object.)
Public methodCode exampleInsertBreak
Inserts a break of the specified type into the document.
Public methodCode exampleInsertCell
Inserts a table cell into the document.
Public methodInsertChart(ChartType, Double, Double)
Inserts an chart object into the document and scales it to the specified size.
Public methodInsertChart(ChartType, RelativeHorizontalPosition, Double, RelativeVerticalPosition, Double, Double, Double, WrapType)
Inserts an chart object into the document and scales it to the specified size.
Public methodCode exampleInsertCheckBox(String, Boolean, Int32)
Inserts a checkbox form field at the current position.
Public methodInsertCheckBox(String, Boolean, Boolean, Int32)
Inserts a checkbox form field at the current position.
Public methodCode exampleInsertComboBox
Inserts a combobox form field at the current position.
Public methodInsertDocument
Inserts content of the document into the current position of DocumentBuilder's cursor.
Public methodCode exampleInsertField(String)
Inserts a Word field into a document and updates the field result.
Public methodCode exampleInsertField(String, String)
Inserts a Word field into a document without updating the field result.
Public methodInsertField(FieldType, Boolean)
Inserts a Word field into a document and optionally updates the field result.
Public methodCode exampleInsertFootnote(FootnoteType, String)
Inserts a footnote or endnote into the document.
Public methodInsertFootnote(FootnoteType, String, String)
Inserts a footnote or endnote into the document.
Public methodCode exampleInsertHtml(String)
Inserts an HTML string into the document.
Public methodInsertHtml(String, Boolean)
Inserts an HTML string into the document.
Public methodCode exampleInsertHyperlink
Inserts a hyperlink into the document.
Public methodInsertImage(Byte)
Inserts an image from a byte array into the document. The image is inserted inline and at 100% scale.
Public methodCode exampleInsertImage(Image)
Inserts an image from a .NET Image object into the document. The image is inserted inline and at 100% scale.
Public methodCode exampleInsertImage(Stream)
Inserts an image from a stream into the document. The image is inserted inline and at 100% scale.
Public methodCode exampleInsertImage(String)
Inserts an image from a file or URL into the document. The image is inserted inline and at 100% scale.
Public methodInsertImage(Byte, Double, Double)
Inserts an inline image from a byte array into the document and scales it to the specified size.
Public methodInsertImage(Image, Double, Double)
Inserts an inline image from a .NET Image object into the document and scales it to the specified size.
Public methodInsertImage(Stream, Double, Double)
Inserts an inline image from a stream into the document and scales it to the specified size.
Public methodInsertImage(String, Double, Double)
Inserts an inline image from a file or URL into the document and scales it to the specified size.
Public methodInsertImage(Byte, RelativeHorizontalPosition, Double, RelativeVerticalPosition, Double, Double, Double, WrapType)
Inserts an image from a byte array at the specified position and size.
Public methodInsertImage(Image, RelativeHorizontalPosition, Double, RelativeVerticalPosition, Double, Double, Double, WrapType)
Inserts an image from a .NET Image object at the specified position and size.
Public methodInsertImage(Stream, RelativeHorizontalPosition, Double, RelativeVerticalPosition, Double, Double, Double, WrapType)
Inserts an image from a stream at the specified position and size.
Public methodCode exampleInsertImage(String, RelativeHorizontalPosition, Double, RelativeVerticalPosition, Double, Double, Double, WrapType)
Inserts an image from a file or URL at the specified position and size.
Public methodCode exampleInsertNode
Inserts a text level node inside the current paragraph before the cursor.
Public methodInsertOleObject(Stream, String, Boolean, Image)
Inserts an embedded OLE object from a stream into the document.
Public methodInsertOleObject(String, Boolean, Boolean, Image)
Inserts an embedded or linked OLE object from a file into the document. Detects OLE object type using file extension.
Public methodInsertOleObject(String, String, Boolean, Boolean, Image)
Inserts an embedded or linked OLE object from a file into the document. Detects OLE object type using given progID parameter.
Public methodInsertOnlineVideo(String, Double, Double)
Inserts an online video object into the document and scales it to the specified size.
Public methodInsertOnlineVideo(String, String, Byte, Double, Double)
Inserts an online video object into the document and scales it to the specified size.
Public methodInsertOnlineVideo(String, RelativeHorizontalPosition, Double, RelativeVerticalPosition, Double, Double, Double, WrapType)
Inserts an online video object into the document and scales it to the specified size.
Public methodInsertOnlineVideo(String, String, Byte, RelativeHorizontalPosition, Double, RelativeVerticalPosition, Double, Double, Double, WrapType)
Inserts an online video object into the document and scales it to the specified size.
Public methodCode exampleInsertParagraph
Inserts a paragraph break into the document.
Public methodInsertSignatureLine(SignatureLineOptions)
Inserts a signature line at the current position.
Public methodInsertSignatureLine(SignatureLineOptions, RelativeHorizontalPosition, Double, RelativeVerticalPosition, Double, WrapType)
Inserts a signature line at the specified position.
Public methodCode exampleInsertTableOfContents
Inserts a TOC (table of contents) field into the document.
Public methodCode exampleInsertTextInput
Inserts a text form field at the current position.
Protected methodMemberwiseClone
Creates a shallow copy of the current Object.
(Inherited from Object.)
Public methodCode exampleMoveTo
Moves the cursor to an inline node or to the end of a paragraph.
Public methodCode exampleMoveToBookmark(String)
Moves the cursor to a bookmark.
Public methodCode exampleMoveToBookmark(String, Boolean, Boolean)
Moves the cursor to a bookmark with greater precision.
Public methodCode exampleMoveToCell
Moves the cursor to a table cell in the current section.
Public methodCode exampleMoveToDocumentEnd
Moves the cursor to the end of the document.
Public methodCode exampleMoveToDocumentStart
Moves the cursor to the beginning of the document.
Public methodMoveToField
Moves the cursor to a field in the document.
Public methodCode exampleMoveToHeaderFooter
Moves the cursor to the beginning of a header or footer in the current section.
Public methodCode exampleMoveToMergeField(String)
Moves the cursor to a position just beyond the specified merge field and removes the merge field.
Public methodCode exampleMoveToMergeField(String, Boolean, Boolean)
Moves the merge field to the specified merge field.
Public methodCode exampleMoveToParagraph
Moves the cursor to a paragraph in the current section.
Public methodCode exampleMoveToSection
Moves the cursor to the beginning of the body in a specified section.
Public methodCode examplePopFont
Retrieves character formatting previously saved on the stack.
Public methodCode examplePushFont
Saves current character formatting onto the stack.
Public methodCode exampleStartBookmark
Marks the current position in the document as a bookmark start.
Public methodStartEditableRange
Marks the current position in the document as an editable range start.
Public methodCode exampleStartTable
Starts a table in the document.
Public methodToString
Returns a string that represents the current object.
(Inherited from Object.)
Public methodCode exampleWrite
Inserts a string into the document at the current insert position.
Public methodCode exampleWriteln
Inserts a paragraph break into the document.
Public methodCode exampleWriteln(String)
Inserts a string and a paragraph break into the document.
Top
Remarks

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

Create a DocumentBuilder and associate it with a Document.

The DocumentBuilder has an internal cursor where the text will be inserted when you call Write(String), Writeln(String), InsertBreak(BreakType) 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
Adds some text into the document and encloses the text in a bookmark using DocumentBuilder.
[C#]

DocumentBuilder builder = new DocumentBuilder();

builder.StartBookmark("MyBookmark");
builder.Writeln("Text inside a bookmark.");
builder.EndBookmark("MyBookmark");
[Visual Basic]

Dim builder As New DocumentBuilder()

builder.StartBookmark("MyBookmark")
builder.Writeln("Text inside a bookmark.")
builder.EndBookmark("MyBookmark")
Examples
Inserts HTML into a document using DocumentBuilder.
[C#]

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

builder.InsertHtml(
    "<P align='right'>Paragraph right</P>" +
    "<b>Implicit paragraph left</b>" +
    "<div align='center'>Div center</div>" +
    "<h1 align='left'>Heading 1 left.</h1>");

doc.Save(MyDir + "DocumentBuilder.InsertHtml Out.doc");
[Visual Basic]

Dim doc As New Document()
Dim builder As New DocumentBuilder(doc)

builder.InsertHtml("<P align='right'>Paragraph right</P>" & "<b>Implicit paragraph left</b>" & "<div align='center'>Div center</div>" & "<h1 align='left'>Heading 1 left.</h1>")

doc.Save(MyDir & "DocumentBuilder.InsertHtml Out.doc")
Examples
Shows how to create a simple table using DocumentBuilder with default formatting.
[C#]

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// We call this method to start building the table.
builder.StartTable();
builder.InsertCell();
builder.Write("Row 1, Cell 1 Content.");

// Build the second cell
builder.InsertCell();
builder.Write("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("Row 2, Cell 1 Content");

// Build the second cell.
builder.InsertCell();
builder.Write("Row 2, Cell 2 Content.");
builder.EndRow();

// Signal that we have finished building the table.
builder.EndTable();

// Save the document to disk.
doc.Save(MyDir + "DocumentBuilder.CreateSimpleTable Out.doc");
[Visual Basic]

Dim doc As New Document()
Dim builder As New DocumentBuilder(doc)

' We call this method to start building the table.
builder.StartTable()
builder.InsertCell()
builder.Write("Row 1, Cell 1 Content.")

' Build the second cell
builder.InsertCell()
builder.Write("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("Row 2, Cell 1 Content")

' Build the second cell.
builder.InsertCell()
builder.Write("Row 2, Cell 2 Content.")
builder.EndRow()

' Signal that we have finished building the table.
builder.EndTable()

' Save the document to disk.
doc.Save(MyDir & "DocumentBuilder.CreateSimpleTable Out.doc")
Examples
Shows how to create a formatted table using DocumentBuilder
[C#]

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

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.LeftIndent = 20.0;

// Set height and define the height rule for the header row.
builder.RowFormat.Height = 40.0;
builder.RowFormat.HeightRule = HeightRule.AtLeast;

// Some special features for the header row.
builder.CellFormat.Shading.BackgroundPatternColor = Color.FromArgb(198, 217, 241);
builder.ParagraphFormat.Alignment = ParagraphAlignment.Center;
builder.Font.Size = 16;
builder.Font.Name = "Arial";
builder.Font.Bold = true;

builder.CellFormat.Width = 100.0;
builder.Write("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("Header Row,\n Cell 2");

builder.InsertCell();
builder.CellFormat.Width = 200.0;
builder.Write("Header Row,\n Cell 3");
builder.EndRow();

// Set features for the other rows and cells.
builder.CellFormat.Shading.BackgroundPatternColor = Color.White;
builder.CellFormat.Width = 100.0;
builder.CellFormat.VerticalAlignment = CellVerticalAlignment.Center;

// Reset height and define a different height rule for table body
builder.RowFormat.Height = 30.0;
builder.RowFormat.HeightRule = HeightRule.Auto;
builder.InsertCell();
// Reset font formatting.
builder.Font.Size = 12;
builder.Font.Bold = false;

// Build the other cells.
builder.Write("Row 1, Cell 1 Content");
builder.InsertCell();
builder.Write("Row 1, Cell 2 Content");

builder.InsertCell();
builder.CellFormat.Width = 200.0;
builder.Write("Row 1, Cell 3 Content");
builder.EndRow();

builder.InsertCell();
builder.CellFormat.Width = 100.0;
builder.Write("Row 2, Cell 1 Content");

builder.InsertCell();
builder.Write("Row 2, Cell 2 Content");

builder.InsertCell();
builder.CellFormat.Width = 200.0;
builder.Write("Row 2, Cell 3 Content.");
builder.EndRow();
builder.EndTable();

doc.Save(MyDir + "DocumentBuilder.CreateFormattedTable Out.doc");
[Visual Basic]

Dim doc As New Document()
Dim builder As New DocumentBuilder(doc)

Dim table As 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.LeftIndent = 20.0

' Set height and define the height rule for the header row.
builder.RowFormat.Height = 40.0
builder.RowFormat.HeightRule = HeightRule.AtLeast

' Some special features for the header row.
builder.CellFormat.Shading.BackgroundPatternColor = Color.FromArgb(198, 217, 241)
builder.ParagraphFormat.Alignment = ParagraphAlignment.Center
builder.Font.Size = 16
builder.Font.Name = "Arial"
builder.Font.Bold = True

builder.CellFormat.Width = 100.0
builder.Write("Header Row," & Constants.vbLf & " 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("Header Row," & Constants.vbLf & " Cell 2")

builder.InsertCell()
builder.CellFormat.Width = 200.0
builder.Write("Header Row," & Constants.vbLf & " Cell 3")
builder.EndRow()

' Set features for the other rows and cells.
builder.CellFormat.Shading.BackgroundPatternColor = Color.White
builder.CellFormat.Width = 100.0
builder.CellFormat.VerticalAlignment = CellVerticalAlignment.Center

' Reset height and define a different height rule for table body
builder.RowFormat.Height = 30.0
builder.RowFormat.HeightRule = HeightRule.Auto
builder.InsertCell()
' Reset font formatting.
builder.Font.Size = 12
builder.Font.Bold = False

' Build the other cells.
builder.Write("Row 1, Cell 1 Content")
builder.InsertCell()
builder.Write("Row 1, Cell 2 Content")

builder.InsertCell()
builder.CellFormat.Width = 200.0
builder.Write("Row 1, Cell 3 Content")
builder.EndRow()

builder.InsertCell()
builder.CellFormat.Width = 100.0
builder.Write("Row 2, Cell 1 Content")

builder.InsertCell()
builder.Write("Row 2, Cell 2 Content")

builder.InsertCell()
builder.CellFormat.Width = 200.0
builder.Write("Row 2, Cell 3 Content.")
builder.EndRow()
builder.EndTable()

doc.Save(MyDir & "DocumentBuilder.CreateFormattedTable Out.doc")
See Also