Summary: Ctors | Methods | Inherited Methods | [Expand All]
public class

# ElementBuilder

extends Object
implements __Delete AutoCloseable

java.lang.Object
↳ | com.pdftron.pdf.ElementBuilder

## Class Overview

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.

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

## Summary

Public Constructors
| ElementBuilder() Instantiates a new element builder.

Public Methods
void | arcTo(double x, double y, double width, double height, double start, double extent) Draw an arc with the specified parameters (upper left corner, width, height and angles).
void | arcTo(double xr, double yr, double rx, boolean isLargeArc, boolean sweep, double endX, double endY) Draw an arc from the current point to the end point.
void | close() Frees the native memory of the object.
void | closePath() Closes the current subpath.
Element | createEllipse(double cx, double cy, double rx, double ry) Create an ellipse (or circle, if rx == ry) path Element.
Element | createForm(Page page) Create a Form XObject Element using the content of the existing page.
Element | createForm(Obj form) Create a Form XObject Element.
Element | createForm(Page page, PDFDoc doc) Create a Form XObject Element using the content of the existing page.
Element | createGroupBegin() Create e_group_begin Element (i.e.
Element | createGroupEnd() Create e_group_end Element (i.e.
Element | createImage(Image img) Create a content image Element out of a given document Image.
Element | createImage(Image img, double x, double y, double hscale, double vscale) Create a content image Element out of a given document Image with the lower left corner at (x, y), and scale factors (hscale, vscale).
Element | createImage(Image img, Matrix2D mtx) Create a content image Element out of a given document Image.
Element | createMarkedContentBegin(String tag, Obj property_dict) Create e_marked_content_begin element with an associated property dictionary (i.e.
Element | createMarkedContentBeginInlineProperties(String tag) Create e_marked_content_begin element with an inline property dictionary (i.e.
Element | createMarkedContentEnd() Create e_marked_content_end element (i.e.
Element | createMarkedContentPoint(String tag, Obj property_dict) Create e_marked_content_point element with an associated property dictionary (i.e.
Element | createMarkedContentPointInlineProperties(String tag) Create e_marked_content_point element with an inline property dictionary (i.e.
Element | createPath(double[] points, byte[] seg_types) Create a path Element using given path segment data.
Element | createRect(double x, double y, double width, double height) Create a rectangle path Element.
Element | createShading(Shading sh) Create a shading Element.
Element | createShapedTextRun(ShapedText text_data) Create a new text run from shaped text.
Element | createTextBegin() Start a text block ('BT' operator in PDF content stream).
Element | createTextBegin(Font font, double font_sz) Start a text block ('BT' operator in PDF content stream).
Element | createTextEnd() Ends a text block.
Element | createTextNewLine(double dx, double dy) Create e_text_new_line Element (i.e.
Element | createTextNewLine() Create e_text_new_line Element (i.e.
Element | createTextRun(String text_data) Create a new text run.
Element | createTextRun(String text_data, Font font, double font_sz) Create a text run using the given font.
Element | createUnicodeTextRun(String text_data) Create a new Unicode text run.
void | curveTo(double cx1, double cy1, double cx2, double cy2, double x2, double y2) Draw a Bezier curve from the current point to the given point (x2, y2) using (cx1, cy1) and (cx2, cy2) as control points.
void | destroy() Frees the native memory of the object.
void | ellipse(double cx, double cy, double rx, double ry) Add an ellipse (or circle, if rx == ry) to the current path as a complete subpath.
void | lineTo(double x, double y) Draw a line from the current point to the given point.
void | moveTo(double x, double y) Set the current point.
void | pathBegin() Starts building a new path Element that can contain an arbitrary sequence of lines, curves, and rectangles.
Element | pathEnd() Finishes building of the path Element.
void | rect(double x, double y, double width, double height) Add a rectangle to the current path as a complete subpath.
void | reset(GState gs) The function sets the graphics state of this Element to the given value.
void | reset() Resets the graphics state of this Element to the default graphics state (i.e.

[Expand] Inherited Methods
From class java.lang.Object
boolean | equals(Object arg0)
final Class<?> | getClass()
int | hashCode()
final void | notify()
final void | notifyAll()
String | toString()
final void | wait(long arg0, int arg1)
final void | wait(long arg0)
final void | wait()
From interface com.pdftron.pdf.__Delete
abstract void | destroy()
From interface java.lang.AutoCloseable
abstract void | close()

## Public Constructors

#### public ElementBuilder ()

Instantiates a new element builder.

##### Throws

PDFNetException |

## Public Methods

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

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

##### Parameters

x | the x coordinates of the lower left corner of the ellipse encompassing rectangle
y | the y coordinates of the lower left corner of the ellipse encompassing rectangle
width | the width of the full ellipse (not considering the angular extents).
height | the height of the full ellipse (not considering the angular extents).
start | starting angle of the arc in degrees
extent | angular extent of the arc in degrees

##### Throws

PDFNetException |

#### public void arcTo (double xr, double yr, double rx, boolean isLargeArc, boolean sweep, double endX, double endY)

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

Note: 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.

##### Parameters

xr | the x radius for the arc
yr | the y radius for the arc
rx | x-axis rotation in radians
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
sweep | direction in which arc is drawn (1 - clockwise, 0 - counterclockwise)
endX | the x coordinate of the end point
endY | the y coordinate of the end point

##### Throws

PDFNetException |

#### public void close ()

Frees the native memory of the object. This can be explicity called to control the deallocation of native memory and avoid situations where the garbage collector does not free the object in a timely manner.

##### Throws

PDFNetException |

#### public void closePath ()

Closes the current subpath.

##### Throws

PDFNetException |

#### public Element createEllipse (double cx, double cy, double rx, double ry)

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

##### Parameters

cx | the x coordinate of the ellipse center
cy | the y coordinate of the ellipse center
rx | the width of rectangle containing the ellipse
ry | the height of rectangle containing the ellipse

##### Returns

- the created ellipse element

##### Throws

PDFNetException |

#### public Element createForm (Page 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.

##### Parameters

page | A page used to create the Form XObject.

##### Returns

- the created Form XObject Element

##### Throws

PDFNetException |

#### public Element createForm (Obj form)

Create a Form XObject Element.

##### Parameters

form | a Form XObject content stream

##### Returns

- the created XObject element

##### Throws

PDFNetException |

#### public Element createForm (Page page, PDFDoc doc)

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.

##### Parameters

page | A page used to create the Form XObject.
doc | Destination document for the Form XObject.

##### Returns

- the created Form XObject Element

##### Throws

PDFNetException |

#### public Element createGroupBegin ()

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

##### Returns

- the e_group_begin element

##### Throws

PDFNetException |

#### public Element createGroupEnd ()

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

##### Returns

- the e_group_end element

##### Throws

PDFNetException |

#### public Element createImage (Image img)

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

##### Parameters

img | the given documen image

##### Returns

- the created content element

##### Throws

PDFNetException |

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

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

##### Parameters

img | the give document image
x | the x coordinate of the lower left corner of the image
y | the y coordinate of the lower left corner of the image
hscale | the horizontal scale factor
vscale | the vertical scale factor

##### Returns

- the created image element

##### Throws

PDFNetException |

#### public Element createImage (Image img, Matrix2D mtx)

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

##### Parameters

img | the given document image
mtx | the image transformation matrix.

##### Returns

- the created content element

##### Throws

PDFNetException |

#### public Element createMarkedContentBegin (String tag, Obj property_dict)

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

##### Parameters

tag | the marked content tag
property_dict | the property dictionary

##### Returns

- the marked content begin element.

##### Throws

PDFNetException |

#### public Element createMarkedContentBeginInlineProperties (String tag)

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

##### Parameters

tag | the marked content tag

##### Returns

- the marked content begin element.

##### Throws

PDFNetException |

#### public Element createMarkedContentEnd ()

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

##### Returns

- the marked content end element.

##### Throws

PDFNetException |

#### public Element createMarkedContentPoint (String tag, Obj property_dict)

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

##### Parameters

tag | the marked content tag
property_dict | the property dictionary

##### Returns

- the marked content point element.

##### Throws

PDFNetException |

#### public Element createMarkedContentPointInlineProperties (String tag)

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

##### Parameters

tag | the marked content tag

##### Returns

- the marked content point element.

##### Throws

PDFNetException |

#### public Element createPath (double[] points, byte[] seg_types)

Create a path Element using given path segment data.

##### Parameters

points | the points consists of the path
seg_types | the segment type

##### Returns

- the created path element

##### Throws

PDFNetException |

#### public Element createRect (double x, double y, double width, double height)

Create a rectangle path Element.

##### Parameters

x | the x coordinate of the lower left corner
y | the y coordinate of the lower left corner
width | the width of the rectangle
height | the height of the rectangle

##### Returns

- the created rectangle path element

##### Throws

PDFNetException |

#### public Element createShading (Shading sh)

Create a shading Element.

##### Parameters

sh | the sh

##### Returns

- the element

##### Throws

PDFNetException |

#### public Element createShapedTextRun (ShapedText text_data)

Create a new text run from shaped text.

Shaped Text can be created with an approriate Font, using the Font.getShapedText() method. Note: you must set the current Font and font size before calling this function and the font must be created using Font::CreateCIDTrueTypeFont() method, and should be the same font used to generate the shaped text content.

Note: For best results, the font should be encoded using the e_Indices encoding scheme.

Note: a text run can be created only within a text block

##### Parameters

text_data | the shaped text data

##### Returns

- the created text run element

##### Throws

PDFNetException |

#### public Element createTextBegin ()

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

##### Returns

- the created element

##### Throws

PDFNetException |

#### public Element createTextBegin (Font font, double font_sz)

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

##### Parameters

font | the font to use
font_sz | the font size

##### Returns

- the created text block

##### Throws

PDFNetException |

#### public Element createTextEnd ()

Ends a text block.

##### Returns

- the created element

##### Throws

PDFNetException |

#### public Element createTextNewLine (double dx, double dy)

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.

##### Parameters

dx | the x coordinate of the new line
dy | the y coordinate of the new line

##### Returns

- the created element

##### Throws

PDFNetException |

#### public Element createTextNewLine ()

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

##### Returns

- the created element

##### Throws

PDFNetException |

#### public Element createTextRun (String text_data)

Create a new text run.

Note: a text run can be created only within a text block

Note: you must set the current Font and font size before calling this function.

##### Parameters

text_data | the text content

##### Returns

- the new text run element

##### Throws

PDFNetException |

#### public Element createTextRun (String text_data, Font font, double font_sz)

Create a text run using the given font.

Note: a text run can be created only within a text block

##### Parameters

text_data | the text content
font | the given font
font_sz | the font size

##### Returns

- the created element

##### Throws

PDFNetException |

#### public Element createUnicodeTextRun (String text_data)

Create a new Unicode text run.

Note: you must set the current Font and font size before calling this function and the font must be created using Font::CreateCIDTrueTypeFont() method.

Note: a text run can be created only within a text block

##### Parameters

text_data | the text content

##### Returns

- the created text run element

##### Throws

PDFNetException |

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

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

##### Parameters

cx1 | the x coordinate of the control point 1
cy1 | the y coordinate of the control point 1
cx2 | the x coordinate of the control point 2
cy2 | the y coordinate of the control point 2
x2 | the x coordinate of the end point
y2 | the y coordinate of the end point

##### Throws

PDFNetException |

#### public void destroy ()

Frees the native memory of the object. This can be explicity called to control the deallocation of native memory and avoid situations where the garbage collector does not free the object in a timely manner.

##### Throws

PDFNetException |

#### public void ellipse (double cx, double cy, double rx, double ry)

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.

##### Parameters

cx | the x coordinate of the center of the ellipse
cy | the y coordinate of the center of the ellipse
rx | the x radii of the ellipse
ry | the y radii of the ellipse

##### Throws

PDFNetException |

#### public void lineTo (double x, double y)

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

##### Parameters

x | the x coordinate of the given point
y | the y coordinate of the given point

##### Throws

PDFNetException |

#### public void moveTo (double x, double y)

Set the current point.

##### Parameters

x | the x coordinate of the current point
y | the y coordinate of the current point

##### Throws

PDFNetException |

#### public void pathBegin ()

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

##### Throws

PDFNetException |

#### public Element pathEnd ()

Finishes building of the path Element.

##### Returns

- the created path Element

##### Throws

PDFNetException |

#### public void rect (double x, double y, double width, double height)

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

##### Parameters

x | the x coordinate of the rectangle
y | the y coordinate of the rectangle
width | the width of the rectangle
height | the height of the rectangle

##### Throws

PDFNetException |

#### public void reset (GState gs)

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.

##### Parameters

gs | the given graphics state

##### Throws

PDFNetException |

#### public void reset ()

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 same graphics state.

##### Throws

PDFNetException |