Show / Hide Table of Contents

# Class ElementBuilder

ElementBuilder is used to build new PDF.Elements (e.g. image, text, path, etc) from scratch. In conjunction with ElementWriter, ElementBuilder can be used to create new page content.

##### Inheritance

object
ElementBuilder

##### Implements

IDisposable

##### Inherited Members

object.ToString()
object.Equals(object)
object.Equals(object, object)
object.ReferenceEquals(object, object)
object.GetHashCode()
object.GetType()
object.MemberwiseClone()

###### Namespace: pdftron.PDF

###### Assembly: PDFNet.dll

##### Syntax

    public class ElementBuilder : IDisposable

##### Remarks

Analogous to ElementReader, every call to ElementBuilder.Create method destroys the Element currently associated with the builder and all previous Element pointers are invalidated.

### Constructors

#### ElementBuilder()

Instantiates a new element builder.

##### Declaration

    public ElementBuilder()

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

### Methods

#### ArcTo(double, double, double, bool, bool, double, double)

Draw an arc from the current point to the end point.

##### Declaration

    public void ArcTo(double xr, double yr, double rx, bool isLargeArc, bool sweep, double endX, double endY)

##### Parameters

Type | Name | Description
--- | --- | ---
double | xr | the xr
double | yr | the yr
double | rx | x-axis rotation in radians
bool | isLargeArc |
    	indicates if smaller or larger arc is chosen
1 - one of the two larger arc sweeps is chosen 0 - one of the two smaller arc sweeps is chosen
bool | sweep | direction in which arc is drawn (1 - clockwise, 0 - counterclockwise)
double | endX | the end x
double | endY | the end y

##### Remarks

The Arc is defined the same way as it is specified by SVG or XPS standards. For further questions please refer to the XPS or SVG standards.

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### ArcTo(double, double, double, double, double, double)

Draw an arc with the specified parameters (upper left corner, width, height and angles).

##### Declaration

    public void ArcTo(double x, double y, double width, double height, double start, double extent)

##### Parameters

Type | Name | Description
--- | --- | ---
double | x | the x
double | y | the y
double | width | the width
double | height | the height
double | start | starting angle of the arc in degrees
double | extent | angular extent of the arc in degrees

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### ClosePath()

Closes the current subpath.

##### Declaration

    public void ClosePath()

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateEllipse(double, double, double, double)

Create an ellipse (or circle, if rx == ry) path Element.

##### Declaration

    public Element CreateEllipse(double cx, double cy, double rx, double ry)

##### Parameters

Type | Name | Description
--- | --- | ---
double | cx | the cx
double | cy | the cy
double | rx | the rx
double | ry | the ry

##### Returns

Type | Description
--- | ---
Element | the element

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateForm(Page)

Create a Form XObject Element using the content of the existing page. This method assumes that the XObject will be used in the same document as the given page. If you need to create the Form XObject in a different document use CreateForm(Page, Doc) method.

##### Declaration

    public Element CreateForm(Page page)

##### Parameters

Type | Name | Description
--- | --- | ---
Page | page | A page used to create the Form XObject.

##### Returns

Type | Description
--- | ---
Element | the element

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateForm(Page, PDFDoc)

Create a Form XObject Element using the content of the existing page. Unlike CreateForm(Page) method, you can use this method to create form in another document.

##### Declaration

    public Element CreateForm(Page page, PDFDoc doc)

##### Parameters

Type | Name | Description
--- | --- | ---
Page | page | A page used to create the Form XObject.
PDFDoc | doc | Destination document for the Form XObject.

##### Returns

Type | Description
--- | ---
Element | the element

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateForm(Obj)

Create a Form XObject Element.

##### Declaration

    public Element CreateForm(Obj form)

##### Parameters

Type | Name | Description
--- | --- | ---
Obj | form | a Form XObject content stream

##### Returns

Type | Description
--- | ---
Element | the element

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateGroupBegin()

Create e_group_begin Element (i.e. 'q' operator in PDF content stream). The function saves the current graphics state.

##### Declaration

    public Element CreateGroupBegin()

##### Returns

Type | Description
--- | ---
Element | the element

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateGroupEnd()

Create e_group_end Element (i.e. 'Q' operator in PDF content stream). The function restores the previous graphics state.

##### Declaration

    public Element CreateGroupEnd()

##### Returns

Type | Description
--- | ---
Element | the element

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateImage(Image)

Create a content image Element out of a given document Image.

##### Declaration

    public Element CreateImage(Image img)

##### Parameters

Type | Name | Description
--- | --- | ---
Image | img | the img

##### Returns

Type | Description
--- | ---
Element | the element

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateImage(Image, double, double, double, double)

Create a content image Element out of a given document Image with the lower left corner at (x, y), and scale factors (hscale, vscale).

##### Declaration

    public Element CreateImage(Image img, double x, double y, double hscale, double vscale)

##### Parameters

Type | Name | Description
--- | --- | ---
Image | img | the img
double | x | the x
double | y | the y
double | hscale | the hscale
double | vscale | the vscale

##### Returns

Type | Description
--- | ---
Element | the element

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateImage(Image, Matrix2D)

Create a content image Element out of a given document Image.

##### Declaration

    public Element CreateImage(Image img, Matrix2D mtx)

##### Parameters

Type | Name | Description
--- | --- | ---
Image | img | the img
Matrix2D | mtx | the image transformation matrix.

##### Returns

Type | Description
--- | ---
Element | the element

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateMarkedContentBegin(string, Obj)

Create e_marked_content_begin element with an associated property dictionary (i.e. BMC or BDC operator in PDF content stream).

##### Declaration

    public Element CreateMarkedContentBegin(string tag, Obj property_dict)

##### Parameters

Type | Name | Description
--- | --- | ---
string | tag | the marked content tag
Obj | property_dict | the property dictionary

##### Returns

Type | Description
--- | ---
Element | the marked content begin element

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateMarkedContentBeginInlineProperties(string)

Create e_marked_content_begin element with an inline property dictionary (i.e. BDC operator in PDF content stream).

##### Declaration

    public Element CreateMarkedContentBeginInlineProperties(string tag)

##### Parameters

Type | Name | Description
--- | --- | ---
string | tag | the marked content tag

##### Returns

Type | Description
--- | ---
Element | the marked content begin element

##### Remarks

The inline property dictionary can be accessed and edited using element.GetMCPropertyDict().

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateMarkedContentEnd()

Create e_marked_content_end element (i.e. EMC operator in PDF content stream).

##### Declaration

    public Element CreateMarkedContentEnd()

##### Returns

Type | Description
--- | ---
Element | the marked content end element

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateMarkedContentPoint(string, Obj)

Create e_marked_content_point element with an associated property dictionary (i.e. MP or DP operator in PDF content stream).

##### Declaration

    public Element CreateMarkedContentPoint(string tag, Obj property_dict)

##### Parameters

Type | Name | Description
--- | --- | ---
string | tag | the marked content tag
Obj | property_dict | the property dictionary

##### Returns

Type | Description
--- | ---
Element | the marked content point element

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateMarkedContentPointInlineProperties(string)

Create e_marked_content_point element with an inline property dictionary (i.e. DP operator in PDF content stream).

##### Declaration

    public Element CreateMarkedContentPointInlineProperties(string tag)

##### Parameters

Type | Name | Description
--- | --- | ---
string | tag | the marked content tag

##### Returns

Type | Description
--- | ---
Element | the marked content point element

##### Remarks

The inline property dictionary can be accessed and edited using element.GetMCPropertyDict().

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreatePath(double[], int, byte[], int)

Create a path Element using given path segment data.

##### Declaration

    public Element CreatePath(double[] points, int point_count, byte[] seg_types, int seg_types_count)

##### Parameters

Type | Name | Description
--- | --- | ---
double[] | points | the points
int | point_count | number of points in points array
byte[] | seg_types | the seg_types
int | seg_types_count | number of segment types in seg_types array

##### Returns

Type | Description
--- | ---
Element | the element

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateRect(double, double, double, double)

Create a rectangle path Element.

##### Declaration

    public Element CreateRect(double x, double y, double width, double height)

##### Parameters

Type | Name | Description
--- | --- | ---
double | x | the x
double | y | the y
double | width | the width
double | height | the height

##### Returns

Type | Description
--- | ---
Element | the element

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateShading(Shading)

Create a shading Element.

##### Declaration

    public Element CreateShading(Shading sh)

##### Parameters

Type | Name | Description
--- | --- | ---
Shading | sh | the sh

##### Returns

Type | Description
--- | ---
Element | the element

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateShapedTextRun(ShapedText)

Create a new text run from shaped text. Shaped Text can be created with an approriate Font, using the Font.GetShapedText() method.

##### Declaration

    public Element CreateShapedTextRun(ShapedText shaped_text)

##### Parameters

Type | Name | Description
--- | --- | ---
ShapedText | shaped_text | the shaped text data

##### Returns

Type | Description
--- | ---
Element | the element

##### Remarks

You must set the current Font and font size before calling this function. The font must be created using Font::CreateCIDTrueTypeFont() method, and should be the same font used to generate the shaped text content. For best results, the font should be encoded using the e_Indices encoding scheme. A text run can be created only within a text block

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateTextBegin()

Start a text block ('BT' operator in PDF content stream).

##### Declaration

    public Element CreateTextBegin()

##### Returns

Type | Description
--- | ---
Element | the element

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateTextBegin(Font, double)

Start a text block ('BT' operator in PDF content stream). The function installs the given font in the current graphics state.

##### Declaration

    public Element CreateTextBegin(Font font, double font_sz)

##### Parameters

Type | Name | Description
--- | --- | ---
Font | font | the font
double | font_sz | the font_sz

##### Returns

Type | Description
--- | ---
Element | the element

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateTextEnd()

Ends a text block.

##### Declaration

    public Element CreateTextEnd()

##### Returns

Type | Description
--- | ---
Element | the element

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateTextNewLine()

Create e_text_new_line Element (i.e. a T* operator in PDF content stream).

##### Declaration

    public Element CreateTextNewLine()

##### Returns

Type | Description
--- | ---
Element | the element

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateTextNewLine(double, double)

Create e_text_new_line Element (i.e. a Td operator in PDF content stream). Move to the start of the next line, offset from the start of the current line by (dx , dy). dx and dy are numbers expressed in unscaled text space units.

##### Declaration

    public Element CreateTextNewLine(double dx, double dy)

##### Parameters

Type | Name | Description
--- | --- | ---
double | dx | the dx
double | dy | the dy

##### Returns

Type | Description
--- | ---
Element | the element

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateTextRun(string)

Create a new text run.

##### Declaration

    public Element CreateTextRun(string text_data)

##### Parameters

Type | Name | Description
--- | --- | ---
string | text_data | the text_data

##### Returns

Type | Description
--- | ---
Element | the element

##### Remarks

a text run can be created only within a text block you must set the current Font and font size before calling this function.

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateTextRun(string, Font, double)

Create a text run using the given font.

##### Declaration

    public Element CreateTextRun(string text_data, Font font, double font_sz)

##### Parameters

Type | Name | Description
--- | --- | ---
string | text_data | the text_data
Font | font | the font
double | font_sz | the font_sz

##### Returns

Type | Description
--- | ---
Element | the element

##### Remarks

a text run can be created only within a text block

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateUnicodeTextRun(string)

Create a new Unicode text run.

##### Declaration

    public Element CreateUnicodeTextRun(string text_data)

##### Parameters

Type | Name | Description
--- | --- | ---
string | text_data | the text_data

##### Returns

Type | Description
--- | ---
Element | the element

##### Remarks

you must set the current Font and font size before calling this function and the font must be created using Font::CreateCIDTrueTypeFont() method. a text run can be created only within a text block

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CreateUnicodeTextRun(string, Font, double)

Create a new Unicode text run.

##### Declaration

    public Element CreateUnicodeTextRun(string text_data, Font font, double font_sz)

##### Parameters

Type | Name | Description
--- | --- | ---
string | text_data | the text_data
Font | font | font for the text run
double | font_sz | size of the font

##### Returns

Type | Description
--- | ---
Element | the element

##### Remarks

you must set the current Font and font size before calling this function and the font must be created using Font::CreateCIDTrueTypeFont() method. a text run can be created only within a text block

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### CurveTo(double, double, double, double, double, double)

Draw a Bezier curve from the current point to the given point (x2, y2) using (cx1, cy1) and (cx2, cy2) as control points.

##### Declaration

    public void CurveTo(double cx1, double cy1, double cx2, double cy2, double x2, double y2)

##### Parameters

Type | Name | Description
--- | --- | ---
double | cx1 | the cx1
double | cy1 | the cy1
double | cx2 | the cx2
double | cy2 | the cy2
double | x2 | the x2
double | y2 | the y2

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### Dispose()

Releases all resources used by the ElementBuilder

##### Declaration

    public override sealed void Dispose()

#### Dispose(bool)

##### Declaration

    [HandleProcessCorruptedStateExceptions]
    protected virtual void Dispose(bool A_0)

##### Parameters

Type | Name | Description
--- | --- | ---
bool | A_0 |

#### Ellipse(double, double, double, double)

Add an ellipse (or circle, if rx == ry) to the current path as a complete subpath. Setting the current point is not required before using this function.

##### Declaration

    public void Ellipse(double cx, double cy, double rx, double ry)

##### Parameters

Type | Name | Description
--- | --- | ---
double | cx | the cx
double | cy | the cy
double | rx | the rx
double | ry | the ry

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### ~ElementBuilder()

##### Declaration

    protected ~ElementBuilder()

#### LineTo(double, double)

Draw a line from the current point to the given point.

##### Declaration

    public void LineTo(double x, double y)

##### Parameters

Type | Name | Description
--- | --- | ---
double | x | the x
double | y | the y

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### MoveTo(double, double)

Set the current point.

##### Declaration

    public void MoveTo(double x, double y)

##### Parameters

Type | Name | Description
--- | --- | ---
double | x | the x
double | y | the y

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### PathBegin()

Starts building a new path Element that can contain an arbitrary sequence of lines, curves, and rectangles.

##### Declaration

    public void PathBegin()

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### PathEnd()

Finishes building of the path Element.

##### Declaration

    public Element PathEnd()

##### Returns

Type | Description
--- | ---
Element | the path Element

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### Rect(double, double, double, double)

Add a rectangle to the current path as a complete subpath. Setting the current point is not required before using this function.

##### Declaration

    public void Rect(double x, double y, double width, double height)

##### Parameters

Type | Name | Description
--- | --- | ---
double | x | the x
double | y | the y
double | width | the width
double | height | the height

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### Reset()

The function sets the graphics state of this Element to the given value. If 'gs' parameter is not specified or is NULL the function resets the graphics state of this Element to the default graphics state (i.e. the graphics state at the begining of the display list).

The function can be used in situations where the same ElementBuilder is used to create content on several pages, XObjects, etc. If the graphics state is not Reset() when moving to a new display list, the new Element will have the same graphics state as the last Element in the previous display list (and this may or may not be your intent).

Another use of Reset(gs) is to make sure that two Elements have the graphics state.

##### Declaration

    public void Reset()

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

#### Reset(GState)

Reset.

##### Declaration

    public void Reset(GState gs)

##### Parameters

Type | Name | Description
--- | --- | ---
GState | gs | the gs

##### Exceptions

Type | Condition
--- | ---
PDFNetException | PDFNetException the PDFNet exception

### Implements

IDisposable