pdftron.PDF
Class ElementBuilder

java.lang.Object
  pdftron.PDF.ElementBuilder

public class ElementBuilder
extends java.lang.Object

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.

Constructor Summary

ElementBuilder()
Instantiates a new element builder.

Method Summary

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	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	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(Obj form) Create a Form XObject Element.
Element	createForm(Page page) Create a Form XObject Element using the content of the existing page.
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	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	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() Create e_text_new_line Element (i.e.
Element	createTextNewLine(double dx, double dy) Create e_text_new_line Element (i.e.
Element	createTextRun(java.lang.String text_data) Create a new text run.
Element	createTextRun(java.lang.String text_data, Font font, double font_sz) Create a text run using the given font.
Element	createUnicodeTextRun(java.lang.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() Resets the graphics state of this Element to the default graphics state (i.e.
void	reset(GState gs) The function sets the graphics state of this Element to the given value.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ElementBuilder

public ElementBuilder()
               throws PDFNetException

Instantiates a new element builder.

Throws:

PDFNetException

Method Detail

destroy

public void destroy()
             throws PDFNetException

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

reset

public void reset()
           throws PDFNetException

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

reset

public void reset(GState gs)
           throws PDFNetException

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

createImage

public Element createImage(Image img)
                    throws PDFNetException

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

Parameters:

img - the given documen image

Returns:

the created content element

Throws:

PDFNetException

createImage

public Element createImage(Image img,
                           Matrix2D mtx)
                    throws PDFNetException

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

createImage

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

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

createGroupBegin

public Element createGroupBegin()
                         throws PDFNetException

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

createGroupEnd

public Element createGroupEnd()
                       throws PDFNetException

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

createShading

public Element createShading(Shading sh)
                      throws PDFNetException

Create a shading Element.

Parameters:

sh - the sh

Returns:

the element

Throws:

PDFNetException

createForm

public Element createForm(Obj form)
                   throws PDFNetException

Create a Form XObject Element.

Parameters:

form - a Form XObject content stream

Returns:

the created XObject element

Throws:

PDFNetException

createForm

public Element createForm(Page page)
                   throws PDFNetException

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

createForm

public Element createForm(Page page,
                          PDFDoc doc)
                   throws PDFNetException

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

createTextBegin

public Element createTextBegin(Font font,
                               double font_sz)
                        throws PDFNetException

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

createTextBegin

public Element createTextBegin()
                        throws PDFNetException

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

Returns:

the created element

Throws:

PDFNetException

createTextEnd

public Element createTextEnd()
                      throws PDFNetException

Ends a text block.

Returns:

the created element

Throws:

PDFNetException

createTextRun

public Element createTextRun(java.lang.String text_data,
                             Font font,
                             double font_sz)
                      throws PDFNetException

Create a text run using the given font.

Parameters:

text_data - the text content

font - the given font

font_sz - the font size

Returns:

the created element

Throws:

PDFNetException

Note:

a text run can be created only within a text block

createTextRun

public Element createTextRun(java.lang.String text_data)
                      throws PDFNetException

Create a new text run.

Parameters:

text_data - the text content

Returns:

the new text run element

Throws:

PDFNetException

Note:

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

createUnicodeTextRun

public Element createUnicodeTextRun(java.lang.String text_data)
                             throws PDFNetException

Create a new Unicode text run.

Parameters:

text_data - the text content

Returns:

the created text run element

Throws:

PDFNetException

Note:

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

createTextNewLine

public Element createTextNewLine(double dx,
                                 double dy)
                          throws PDFNetException

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

createTextNewLine

public Element createTextNewLine()
                          throws PDFNetException

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

Returns:

the created element

Throws:

PDFNetException

createPath

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

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

createRect

public Element createRect(double x,
                          double y,
                          double width,
                          double height)
                   throws PDFNetException

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

createEllipse

public Element createEllipse(double cx,
                             double cy,
                             double rx,
                             double ry)
                      throws PDFNetException

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

pathBegin

public void pathBegin()
               throws PDFNetException

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

Throws:

PDFNetException

pathEnd

public Element pathEnd()
                throws PDFNetException

Finishes building of the path Element.

Returns:

the created path Element

Throws:

PDFNetException

rect

public void rect(double x,
                 double y,
                 double width,
                 double height)
          throws PDFNetException

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

moveTo

public void moveTo(double x,
                   double y)
            throws PDFNetException

Set the current point.

Parameters:

x - the x coordinate of the current point

y - the y coordinate of the current point

Throws:

PDFNetException

lineTo

public void lineTo(double x,
                   double y)
            throws PDFNetException

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

curveTo

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

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

arcTo

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

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

arcTo

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

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

Parameters:

xr - the x radius for the arc

yr - the y radius for the arc

rx - x-axis rotation in degrees

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

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.

ellipse

public void ellipse(double cx,
                    double cy,
                    double rx,
                    double ry)
             throws PDFNetException

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

closePath

public void closePath()
               throws PDFNetException

Closes the current subpath.

Throws:

PDFNetException