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
From interface com.pdftron.pdf.__Delete
From interface java.lang.AutoCloseable

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