org.faceless.pdf2
Class PDFPage

java.lang.Object
  extended by org.faceless.pdf2.PDFPage
All Implemented Interfaces:
Cloneable

public final class PDFPage
extends Object

Represents a Page in a PDF document.

1. Geometry

By default, the geometry of a PDF page is measured in points (defined in PostScript as 1/72 of an inch), from the bottom-left hand corner of the page. This can be altered by calling the setUnits() method, which can be used to set the page to measure in CM, MM, inches and so on, or change the origin (0,0) point from the bottom left of the page to the top left.

2. Drawing Shapes

Geometric shapes are drawn using either the simple "draw" methods or the more powerful "path" methods. Whether the shape is filled or just drawn as an outline depends on the FillColor and LineColor of the current style.

3. Drawing Text 4. Drawing Images and Canvases

Bitmap images (represented by the PDFImage class) are drawn using the drawImage() method.

   PDFImage img = new PDFImage(new FileInputStream("mypicture.jpg"));
   page.drawImage(img, 100, 100, 200, 200);
 

A PDFCanvas can be drawn almost exactly the same way, using the drawCanvas() method. A canvas can be created from another page, loaded from a file or created from scratch. A typical use of a canvas would be to draw a pattern created elsewhere, or perhaps a copy of an existing page, onto another page.

   PDFCanvas canvas = new PDFCanvas(template.getPage(0));
   newpdf.getPage(0).drawCanvas(0,0,pagewidth, pageheight);
 
5. Rotate and Save/Restore

At any point the page can be rotated around a point, using the rotate() method. This affects any further graphics operations to the page - drawing lines, text, images and so on. For example, to draw text at a 45° angle, you could do something like this:

   page.rotate(x, y, 45);
   page.drawText("Rotated", x, y);
 

However, due to the vagaries of floating point arithmatic, if you want to rotate the page back to where it was, the results may not be identical. A much better way to do this is to wrap your rotation in a save()/restore() block. These methods save the current page state to a stack and then restore it. It's a very good idea to save the state and restore it before applying a rotation, like so:

   page.save();
   page.rotate(x, y, 45);
   page.drawText("Rotated", x, y);
   page.restore();
 
7. Clipping

Similar to the drawRectangle, drawCircle etc. methods above, the clipRectangle(), clipRoundedRectangle(), clipCircle(), clipEllipse() and clipPolygon() methods can be used to set the current clipping area on the page. Any future graphics or text operations will only take place inside that clipping area, which defaults to the entire page. For finer control, a path can be drawn using the path methods demonstrated above, and the pathClip() method used to set the clipping area.

There is no way to enlarge the current clipping area, or to set a new clipping area without reference to the current one. However, as the current clipping area is part of the graphics state, it can (and should) be nested inside calls to save() and restore() to limit its effect.

Here's an example which draws an image on the page, clipped to a circle.

   page.save();               // Save the current clipping path - the whole page

   PDFImage img = new PDFImage(new FileInputStream("mypicture.jpg"));
   page.clipEllipse(100,100,300,300);
   page.drawImage(img, 100, 100, 300, 300);

   page.restore();            // Restore the previous clipping path
 
8. Annotations

In addition to all the methods above, which directly affect the contents of the page, Annotations can be added above the page via the getAnnotations() method to provide additional visual effects. This distinction is very important. As annotations are not part of the page, they are not affected by any calls to setUnits, rotate and similar methods, are not copied to a canvas when a new canvas is made using the PDFCanvas(PDFPage) constructor and so on. Annotations would typically be used to add a popup note, a hyperlink, a stamp or a form-field to a page. For example, here's how to add a hyperlink to a page:

   AnnotationLink link = new AnnotationLink();
   link.setRectangle(100, 100, 200, 200);
   link.setAction(PDFAction.goToURL("http://bfo.com"));

   page.getAnnotations().add(link);
 

Since:
1.0
See Also:
PDFStyle, LayoutBox, PDFCanvas, PDF

Field Summary
static int ORIGIN_PAGEBOTTOM
          Argument to setUnits(float, int) to measure the page from the bottom
static int ORIGIN_PAGELEFT
          Argument to setUnits(float, int) to measure the page from the left
static int ORIGIN_PAGERIGHT
          Argument to setUnits(float, int) to measure the page from the right
static int ORIGIN_PAGETOP
          Argument to setUnits(float, int) to measure the page from the top
static float UNITS_CM
          Argument to setUnits(float, int) to measure the page in centimeters. 1cm = 28.346457 points.
static float UNITS_INCHES
          Argument to setUnits(float, int) to measure the page in inches. 1" = 72 points
static float UNITS_MM
          Argument to setUnits(float, int) to measure the page in millimeters. 1mm = 2.8346457 points.
static float UNITS_PERCENT
          Argument to setUnits(float, int) to measure the page in percent.
static float UNITS_PICAS
          Argument to setUnits(float, int) to measure the page in picas. 1 pica = 12 points.
static float UNITS_POINTS
          Argument to setUnits(float, int) to measure the page in points (the default).
 
Constructor Summary
PDFPage(int width, int height)
           Create a new PDFPage object that's not connected to any document.
PDFPage(PDFPage page)
          Create a new PDFPage object that's a clone of the specified page but is not connected to any document.
PDFPage(String pagesize)
           Create a new page of the specified page size that is not connected to any document.
 
Method Summary
 void addPropertyChangeListener(PropertyChangeListener listener)
          Add a PropertyChangeListener to this PDFPage.
 void beginTag(String tag, Map atts)
          Open a structural tag on this page.
 void beginText(float x1, float y1, float x2, float y2)
           Begin a paragraph of text.
 void beginTextLink(PDFAction action, PDFStyle linkstyle)
           Start a "link" section in the text.
 void clipCircle(float x, float y, float radius)
          Set the clipping area to a circle centered on x, y with a radius of radius.
 void clipEllipse(float x1, float y1, float x2, float y2)
           Set the clipping area to the ellipse inside the specified rectangle.
 void clipPolygon(float[] x, float[] y)
           Set the clipping area to a polygon.
 void clipRectangle(float x1, float y1, float x2, float y2)
           Set the clipping area to the rectangle which runs through the two corners x1,y1 and x2,y2.
 void clipRoundedRectangle(float x1, float y1, float x2, float y2, float radius)
           Set the clipping area to a rectangle with rounded corners which runs through the two corners x1,y1 and x2,y2.
 float continueText(float x1, float y1, float x2, float y2, PDFPage page)
           As for beginText, but continue any text that overflowed from the specified page.
 float discardText()
          Discard the paragraph of text.
 void drawCanvas(PDFCanvas canvas, float x1, float y1, float x2, float y2)
          Draw a PDFCanvas at the specified position on the page.
 void drawCircle(float x, float y, float radius)
          Draw a circle centered on x, y with a radius of radius.
 void drawCircleArc(float x, float y, float radius, float start, float end)
          Draw an arc of the circle centered on x,y with the specified radius.
 void drawEllipse(float x1, float y1, float x2, float y2)
           Draw an ellipse inside the specified rectangle.
 void drawEllipseArc(float x1, float y1, float x2, float y2, float start, float end)
           Draw an ellipse arc inside the specified rectangle.
 void drawImage(PDFImage image, float x1, float y1, float x2, float y2)
          Draw a PDFImage at the specified position on the page
 void drawLayoutBox(LayoutBox box, float x, float y)
          Draw a LayoutBox at the specified position on the page
 void drawLine(float x1, float y1, float x2, float y2)
          Draw a line from x1,y1 to x2,y2.
 void drawPolygon(float[] x, float[] y)
           Draw a polygon.
 void drawRectangle(float x1, float y1, float x2, float y2)
           Draw a rectangle through the two corners x1,y1 and x2,y2.
 void drawRoundedRectangle(float x1, float y1, float x2, float y2, float radius)
           Draw a rectangle with rounded corners through the two corners x1,y1 and x2,y2.
 float drawText(String text)
           Draw a paragraph of text in the current style.
 void drawText(String text, float x, float y)
           Draw a line of text at the specified position.
 void drawTextLink(String text, float x, float y, PDFAction action)
           Draw a line of text at a the specified position, and set it to link to the specified action.
 void endTag()
          Close a structural tag on this page.
 float endText(boolean justifylast)
          End the paragraph of text.
 PDFAnnotation[] endTextLink()
           End the "link" section in the text, analogous to the </A> tag in HTML.
 void flush()
           Flush any operations that have been written to the page.
 PDFAction getAction(Event type)
           Get the action that's perform when this page is displayed.
 List getAnnotations()
          Return a List of the PDFAnnotation objects on this page.
 float[] getBox(String name)
           Return the specified Page Box - see the setBox method for a description of Page Boxes.
 int getHeight()
          Return the height of this page in points.
 Reader getMetaData()
          Return any XML metadata associated with this object.
 int getPageNumber()
          Return the page number of this page in it's PDF, or zero if the page is not part of a PDF document
 int getPageOrientation()
          Get the current page orientation.
 PDF getPDF()
          Return the PDF this page is part of, or null if it hasn't been attached to a PDF yet.
 PDFStyle getStyle()
          Return the style used on the page
 PDFImage getThumbnail()
          Return the thumbnail image on the page, as set by setThumbnail(org.faceless.pdf2.PDFImage).
 int getWidth()
          Return the width of this page in points.
 void pathArc(float width, float height, float start, float end)
          Continue the open path in an arc to the specified position.
 void pathBezier(float cx1, float cy1, float cx2, float cy2, float x, float y)
          Continue the open path in a bezier curve to the specified position.
 void pathCancel()
          Cancel the current path
 void pathClip()
           Close the path and set the "clipping area" of the page to be the intersection of the current clipping area and the shape defined by this path.
 void pathClipAndPaint()
          Close and paint the path as described in pathPaint(), then set the clipping area to the same are as described in pathClip()
 void pathClose()
          Close the path by drawing a straight line back to it's beginning
 void pathLine(float x, float y)
          Continue the open path in a straight line to the specified position.
 void pathMove(float x, float y)
          Start a new path at the specified position.
 void pathPaint()
          Close and paint the path.
 void rawWrite(String data)
          Write raw PDF commands to the page.
 void removePropertyChangeListener(PropertyChangeListener listener)
          Remove a previously added PropertyChangeListener from this PDFPage.
 void restore()
          Restore the state that was saved with the last call to save()
 void rotate(float x, float y, double angle)
           Rotate the page.
 void save()
           Save the state of this page.
 void seekEnd()
           Seek to the end of the page.
 void seekStart()
           Seek to the start of the page.
 void setAction(Event event, PDFAction action)
           Set the action to perform when the specified event occurs.
 void setBox(String name, float x1, float y1, float x2, float y2)
          Set one of the various Page Boxes that control how the page is printed and displayed.
 void setMetaData(String xmldata)
          Set the XML metadata associated with this object.
 void setPageOrientation(int degrees)
          Set the orientation of the page.
 void setStyle(PDFStyle style)
          Set the style to use for future drawing operations on this page
 void setThumbnail(PDFImage image)
          Set the embedded page thumbnail.
 void setTransition(String style, float displaytime, float transitiontime)
          Set a transition from this page to the next page, to allow the pages to be displayed as part of a presentation.
 void setUnits(float units, int origin)
          Set the coordinates of the current page.
 String toString()
           
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

UNITS_INCHES

public static final float UNITS_INCHES
Argument to setUnits(float, int) to measure the page in inches. 1" = 72 points

See Also:
Constant Field Values

UNITS_CM

public static final float UNITS_CM
Argument to setUnits(float, int) to measure the page in centimeters. 1cm = 28.346457 points.

See Also:
Constant Field Values

UNITS_MM

public static final float UNITS_MM
Argument to setUnits(float, int) to measure the page in millimeters. 1mm = 2.8346457 points.

See Also:
Constant Field Values

UNITS_PICAS

public static final float UNITS_PICAS
Argument to setUnits(float, int) to measure the page in picas. 1 pica = 12 points.

See Also:
Constant Field Values

UNITS_PERCENT

public static final float UNITS_PERCENT
Argument to setUnits(float, int) to measure the page in percent. Unlike the other measurements, this can result in changes to the aspect ratio. (10% of the page width is usually less than 10% of the page height).

See Also:
Constant Field Values

UNITS_POINTS

public static final float UNITS_POINTS
Argument to setUnits(float, int) to measure the page in points (the default). One point is 1/72nd of an inch.

See Also:
Constant Field Values

ORIGIN_PAGEBOTTOM

public static final int ORIGIN_PAGEBOTTOM
Argument to setUnits(float, int) to measure the page from the bottom

See Also:
Constant Field Values

ORIGIN_PAGETOP

public static final int ORIGIN_PAGETOP
Argument to setUnits(float, int) to measure the page from the top

See Also:
Constant Field Values

ORIGIN_PAGELEFT

public static final int ORIGIN_PAGELEFT
Argument to setUnits(float, int) to measure the page from the left

See Also:
Constant Field Values

ORIGIN_PAGERIGHT

public static final int ORIGIN_PAGERIGHT
Argument to setUnits(float, int) to measure the page from the right

See Also:
Constant Field Values
Constructor Detail

PDFPage

public PDFPage(int width,
               int height)

Create a new PDFPage object that's not connected to any document. In most cases it will be more convenient to call the PDF.newPage(int,int) method, which creates a new page and adds it to a PDF.

The parameters are integers for API compatibility only. If required you can create pages sized to a fraction of a point with the PDFPage(String) constructor.

Since:
2.0

PDFPage

public PDFPage(String pagesize)

Create a new page of the specified page size that is not connected to any document. In most cases it will be more convenient to call PDF.newPage(String), which create the page and links it to the PDF.

The size is specified as a string of the form "WxHU", where W is the width of the page, H is the height of the page, and U is an optional units specifier - it may be "mm", "cm" or "in", and if it's not specified it's assumed to be points. The resulting page size is rounded to the nearest integer unless the units are specified as points (eg. 595.5x842 - fractional sizes added in 2.2.3)

For convenience we've defined several standard sizes that you can pass in, like PDF.PAGESIZE_A4, PDF.PAGESIZE_A4_LANDSCAPE, PDF.PAGESIZE_LETTER, PDF.PAGESIZE_LETTER_LANDSCAPE and so on.

Since 2.2.3 you can also pass in a String containing the common name of the paper size, optionally with a "-landscape" suffix, eg "A4", "Letter", "A2-landscape", "DL" and so on. All ISO sizes and most US and JIS paper (and some envelope) sizes are recognised.

Example values include "210x297mm", "595x842" or "A4", which would both produce an A4 page, and "8.5x11in", "612x792" or "Letter", which would both produce a US Letter page.

Parameters:
pagesize - the size of the page to create
Throws:
IllegalArgumentException - if the specified page size cannot be parsed

PDFPage

public PDFPage(PDFPage page)
Create a new PDFPage object that's a clone of the specified page but is not connected to any document. In most cases it will be more convenient to call the PDF.newPage(PDFPage) method, which creates a new page and adds it to a PDF.

Since:
2.0
Method Detail

setPageOrientation

public void setPageOrientation(int degrees)
Set the orientation of the page. This method can be used to rotate the page clockwise or counter-clockwise by 90 degrees. Typically the value passed in will be getPageOrientation() +/- 90, to rotate the page 90 degrees clockwise or anti-clockwise.

Parameters:
degrees - one of 0, 90, 180 or 270
Since:
2.8.3

getPageOrientation

public int getPageOrientation()
Get the current page orientation. Although this value can give some indication of whether the page is portrait, landscape or reverse-landscape, it's not the only way to determine if a page is in that position. Typically the value for this method is used as a base for the parameter to setPageOrientation(int).

Returns:
the page orientation - 0, 90, 180 or 270
Since:
2.8.3

getPDF

public PDF getPDF()
Return the PDF this page is part of, or null if it hasn't been attached to a PDF yet.

Since:
2.8

flush

public void flush()

Flush any operations that have been written to the page. Pages must be flushed before they can be cloned (by calling the PDFCanvas.PDFCanvas(PDFPage) or PDFPage(PDFPage) constructors).

Pages are considered "flushed" when they are loaded, and only require flushing after an action is performed on its contents, such as calling any of the draw... methods. Adding or removing annotations is not considered to alter the page contents.

After a page has been flushed, it can still be written to without any performance penalty (although calling flush too often will result in larger files, so don't overdo it).

It is a good idea to flush a PDFPage after you've finished modifying it, as the library can manage it more efficiently if it knows you're not expecting to write to it again. In particular, a flushed page may be temporarily written to disk by a Cache to free up memory.

Throws:
IllegalStateException - if the page is incomplete - you have an open path, a save() without a matching restore(), or a beginText without an endText
Since:
2.2

seekStart

public void seekStart()

Seek to the start of the page. Any items drawn after this call will be drawn before any content already existing on the page, so appearing under the current content.

Note that if the document clears the page before writing, it will overwrite any content written after a seekStart

Since:
1.1.12

seekEnd

public void seekEnd()

Seek to the end of the page. Any items drawn after this call will be drawn after any content already existing on the page, so appearing on top of the current content. This is the default position.

Since:
1.1.12

setBox

public void setBox(String name,
                   float x1,
                   float y1,
                   float x2,
                   float y2)
Set one of the various Page Boxes that control how the page is printed and displayed. The "name" parameter specifies the box, and may be one of "Media", "Crop", "Art", "Bleed" or "Trim". The MediaBox relates to the size of the physical page, and is set in the PDFPage constructor. Consequently you really don't want to set this unless you know exactly what you're doing. The other boxes can be set and reset as many times as required. To remove a previously defined box, set all four values to 0.

Parameters:
name - the name of the page box to set
x1 - the left-most X co-ordinate of the box
y1 - the bottom-most Y co-ordinate of the box
x2 - the right-most X co-ordinate of the box
y2 - the top-most Y co-ordinate of the box
Since:
2.0.7

getBox

public float[] getBox(String name)

Return the specified Page Box - see the setBox method for a description of Page Boxes. If the requested box isn't specified by the page object, this method returns null. Note that since 2.7.3, values are always relative to the MediaBox, which is always anchored at (0,0). The raw box values can be retrieved by prefixing the argument with "Raw", eg "RawMediaBox".

Since 2.8 this method accepts "ViewBox" or "PrintBox" as arguments as well. The method will then return the appropriate box for viewing or printing the PDF, which is typically the CropBox if specified or the MediaBox if not - although this can be changed with the view.area and print.area settings in PDF.setOption().

Parameters:
name - the name of the page box to return.
Returns:
an array of floats [x1,y1,x2,y2] describing the corners of the requested page box, or null if no such box is defined
Since:
2.0.7

getPageNumber

public int getPageNumber()
Return the page number of this page in it's PDF, or zero if the page is not part of a PDF document

Returns:
the page number of this page, from 1 to PDF.getNumberOfPages()

setUnits

public void setUnits(float units,
                     int origin)
Set the coordinates of the current page. When a new page is created it's measured in points from the bottom-left of the page. This can be changed as many times as necessary by calling this method.

Parameters:
units - the units to measure it in. Can be UNITS_POINTS (the default), UNITS_INCHES, UNITS_CM, UNITS_MM, UNITS_PICAS or UNITS_PERCENT
origin - which corner of the page is nearest to (0,0). A logical-or of ORIGIN_PAGETOP, ORIGIN_PAGELEFT, ORIGIN_PAGERIGHT and ORIGIN_PAGEBOTTOM
Since:
2.0 - this method replaces the setCanvas method in versions prior to 2.0

setMetaData

public void setMetaData(String xmldata)
Set the XML metadata associated with this object. See PDF.setMetaData(java.lang.String) for more information.

Parameters:
xmldata - the XML data to embed into the document, or null to clear any existing metadata. No validation is performed on this input.
Since:
1.1.12

getMetaData

public Reader getMetaData()
                   throws IOException
Return any XML metadata associated with this object. See the PDF.getMetaData() for more information

Returns:
a Reader containing the source of the XML or null if no metadata is available.
Throws:
IOException - if the metadata can't be extracted
Since:
1.1.12

setAction

public void setAction(Event event,
                      PDFAction action)

Set the action to perform when the specified event occurs. Events that occur on a page are limited to open and close, which are run everytime the page is displayed on screen.

Parameters:
event - one of Event.OPEN or Event.CLOSE.
action - the action to run each time this page is displayed, or null to clear the action
Since:
2.0
See Also:
getAction(org.faceless.pdf2.Event), PDF.setAction(org.faceless.pdf2.Event, org.faceless.pdf2.PDFAction), AnnotationLink.setAction(org.faceless.pdf2.PDFAction), FormElement.setAction(org.faceless.pdf2.Event, org.faceless.pdf2.PDFAction)

getAction

public PDFAction getAction(Event type)

Get the action that's perform when this page is displayed. This is the value set by the setAction(org.faceless.pdf2.Event, org.faceless.pdf2.PDFAction) method.

Returns:
the action performed whenever the specified event occurs, or null if no action is performed for this event.
Since:
2.0
See Also:
setAction(org.faceless.pdf2.Event, org.faceless.pdf2.PDFAction), PDF.getAction(org.faceless.pdf2.Event), AnnotationLink.getAction(), FormElement.getAction(org.faceless.pdf2.Event)

rawWrite

public void rawWrite(String data)
Write raw PDF commands to the page. This is for advanced users only, but does allow those intimately familiar with the PDF specification to perform some of the more esoteric actions that aren't directly supported by the PDF library. Using this method it is easy to create invalid PDF documents, so use with caution.

Parameters:
data - the PDF operations to write to the stream, for instance "/Perceptual ri" to set the RenderingIntent. Line breaks will be added before and after the specified string.
Since:
2.1.2

getWidth

public int getWidth()
Return the width of this page in points. For API compatibility reasons only these are rounded to the nearest point, although it is possible to have pages sized to a fraction of a point. If more accuracy is needed you can get the exact page dimensions by calling the getBox(java.lang.String) method to get the MediaBox.

Since:
1.0

getHeight

public int getHeight()
Return the height of this page in points. For API compatibility reasons only these are rounded to the nearest point, although it is possible to have pages sized to a fraction of a point. If more accuracy is needed you can get the exact page dimensions by calling the getBox(java.lang.String) method to get the MediaBox.

Since:
1.0

setStyle

public void setStyle(PDFStyle style)
Set the style to use for future drawing operations on this page

Since:
1.0

getStyle

public PDFStyle getStyle()
Return the style used on the page

Since:
1.0

drawLine

public void drawLine(float x1,
                     float y1,
                     float x2,
                     float y2)
Draw a line from x1,y1 to x2,y2.

Parameters:
x1 - the X co-ordinate of the start of the line
y1 - the Y co-ordinate of the start of the line
x2 - the X co-ordinate of the end of the line
y2 - the Y co-ordinate of the end of the line
Since:
1.0

drawRectangle

public void drawRectangle(float x1,
                          float y1,
                          float x2,
                          float y2)

Draw a rectangle through the two corners x1,y1 and x2,y2. Whether the rectangle is drawn as an outline or filled depends on the LineColor and FillColor of the current style (see the pathPaint() method for more information).

Parameters:
x1 - the X co-ordinate of the first corner of the rectangle
y1 - the Y co-ordinate of the first corner of the rectangle
x2 - the X co-ordinate of the second corner of the rectangle
y2 - the Y co-ordinate of the second corner of the rectangle
Since:
1.0

drawRoundedRectangle

public void drawRoundedRectangle(float x1,
                                 float y1,
                                 float x2,
                                 float y2,
                                 float radius)

Draw a rectangle with rounded corners through the two corners x1,y1 and x2,y2. Whether the rectangle is drawn as an outline or filled depends on the LineColor and FillColor of the current style (see the pathPaint() method for more information).

Parameters:
x1 - the X co-ordinate of the first corner of the rectangle
y1 - the Y co-ordinate of the first corner of the rectangle
x2 - the X co-ordinate of the second corner of the rectangle
y2 - the Y co-ordinate of the second corner of the rectangle
radius - The radius of the circle that is used to round the corners. A value of zero give identical results to drawRectangle(float, float, float, float)
Since:
1.1

drawPolygon

public void drawPolygon(float[] x,
                        float[] y)

Draw a polygon. The X and Y co-ordinates of the vertices are in the supplied arrays. Whether the polygon is drawn as an outline or filled depends on the LineColor and FillColor of the current style (see the pathPaint() method for more information).

If the fill color is specified the polygon will be closed automatically if it isn't already.

Parameters:
x - the X co-ordinates of the vertices
y - the Y co-ordinates of the vertices
Since:
1.0

drawCircle

public void drawCircle(float x,
                       float y,
                       float radius)
Draw a circle centered on x, y with a radius of radius. A more convenient way to draw circles than drawEllipse

Parameters:
x - the X co-ordinate of the center of the circle
y - the Y co-ordinate of the center of the circle
radius - the radius of the circle
Since:
1.1

drawEllipse

public void drawEllipse(float x1,
                        float y1,
                        float x2,
                        float y2)

Draw an ellipse inside the specified rectangle. The top and sides of the ellipse will touch the edges of the rectangle drawn between x1,y1 and x2,y2.

Whether the ellipse is drawn as an outline or filled depends on the LineColor and FillColor of the current style (see the pathPaint() method for more information).

Parameters:
x1 - the X co-ordinate of the first corner of the rectangle
y1 - the Y co-ordinate of the first corner of the rectangle
x2 - the X co-ordinate of the second corner of the rectangle
y2 - the Y co-ordinate of the second corner of the rectangle
Since:
1.0

drawEllipseArc

public void drawEllipseArc(float x1,
                           float y1,
                           float x2,
                           float y2,
                           float start,
                           float end)

Draw an ellipse arc inside the specified rectangle. The same as drawEllipse, but allows you to specify a start and end angle. If a FillColor is specified, the arc will be closed with a straight line.

Parameters:
x1 - the X co-ordinate of the first corner of the rectangle
y1 - the Y co-ordinate of the first corner of the rectangle
x2 - the X co-ordinate of the second corner of the rectangle
y2 - the Y co-ordinate of the second corner of the rectangle
start - the start angle of the arc, in degrees clockwise from 12 o'clock
end - the end angle of the arc, in degrees clockwise from 12 o'clock
Since:
1.1

drawCircleArc

public void drawCircleArc(float x,
                          float y,
                          float radius,
                          float start,
                          float end)
Draw an arc of the circle centered on x,y with the specified radius. A more convenient way to draw circular arcs than drawEllipseArc If a FillColor is specified, the arc will be closed with a straight line.

Parameters:
x - the X co-ordinate of the center of the circle
y - the Y co-ordinate of the center of the circle
radius - the radius of the circle
start - the start angle of the arc, in degrees clockwise from 12 o'clock
end - the end angle of the arc, in degrees clockwise from 12 o'clock
Since:
1.1

pathMove

public void pathMove(float x,
                     float y)
Start a new path at the specified position. If a path has already been started, move the cursor without drawing a line.

Parameters:
x - the X co-ordinate to move to
y - the Y co-ordinate to move to
Since:
1.0

pathLine

public void pathLine(float x,
                     float y)
Continue the open path in a straight line to the specified position.

Parameters:
x - the X co-ordinate to move to
y - the Y co-ordinate to move to
Throws:
IllegalStateException - if a path hasn't been started with pathMove(float, float)
Since:
1.0

pathBezier

public void pathBezier(float cx1,
                       float cy1,
                       float cx2,
                       float cy2,
                       float x,
                       float y)
Continue the open path in a bezier curve to the specified position.

Parameters:
cx1 - the X co-ordinate of the first control point for the curve
cy1 - the Y co-ordinate of the first control point for the curve
cx2 - the X co-ordinate of the second control point for the curve
cy2 - the Y co-ordinate of the second control point for the curve
x - the X co-ordinate to move to
y - the Y co-ordinate to move to
Throws:
IllegalStateException - if a path hasn't been started with pathMove(float, float)
Since:
1.0

pathArc

public void pathArc(float width,
                    float height,
                    float start,
                    float end)
Continue the open path in an arc to the specified position.

Parameters:
width - the width of the ellipse to take the arc from
height - the height of the ellipse to take the arc from
start - the start angle of the arc, in degrees clockwise from 12 o'clock
end - the end angle of the arc, in degrees clockwise from 12 o'clock
Throws:
IllegalStateException - if a path hasn't been started with pathMove(float, float)
Since:
1.1

pathClose

public void pathClose()
Close the path by drawing a straight line back to it's beginning

Throws:
IllegalStateException - if a path hasn't been started with pathMove(float, float)
Since:
1.0

pathCancel

public void pathCancel()
Cancel the current path

Throws:
IllegalStateException - if a path hasn't been started with pathMove(float, float)
Since:
1.0

pathClip

public void pathClip()

Close the path and set the "clipping area" of the page to be the intersection of the current clipping area and the shape defined by this path. Any future graphics or text operations on the page are only applied within this area.

There is no way to enlarge the current clipping area, or to set a new clipping area without reference to the current one. However, as the current clipping area is part of the graphics state, it can and should be nested inside calls to save() and restore() to limit its effect.

Throws:
IllegalStateException - if a path hasn't been started with pathMove(float, float)
Since:
1.1.5

pathPaint

public void pathPaint()
Close and paint the path. What this actually does depends on the currently applied PDFStyle

Throws:
IllegalStateException - if a path hasn't been started with pathMove(float, float), or if neither a fill nor line color has been specified.
Since:
1.0

pathClipAndPaint

public void pathClipAndPaint()
Close and paint the path as described in pathPaint(), then set the clipping area to the same are as described in pathClip()

Since:
1.1.10

clipRoundedRectangle

public void clipRoundedRectangle(float x1,
                                 float y1,
                                 float x2,
                                 float y2,
                                 float radius)

Set the clipping area to a rectangle with rounded corners which runs through the two corners x1,y1 and x2,y2.

Parameters:
x1 - the X co-ordinate of the first corner of the rectangle
y1 - the Y co-ordinate of the first corner of the rectangle
x2 - the X co-ordinate of the second corner of the rectangle
y2 - the Y co-ordinate of the second corner of the rectangle
radius - The radius of the circle that is used to round the corners. A value of zero give identical results to drawRectangle(float, float, float, float)
Since:
1.1.5

clipPolygon

public void clipPolygon(float[] x,
                        float[] y)

Set the clipping area to a polygon. The X and Y co-ordinates of the vertices are in the supplied arrays.

Parameters:
x - the X co-ordinates of the vertices
y - the Y co-ordinates of the vertices
Since:
1.1.5

clipRectangle

public void clipRectangle(float x1,
                          float y1,
                          float x2,
                          float y2)

Set the clipping area to the rectangle which runs through the two corners x1,y1 and x2,y2.

Parameters:
x1 - the X co-ordinate of the first corner of the rectangle
y1 - the Y co-ordinate of the first corner of the rectangle
x2 - the X co-ordinate of the second corner of the rectangle
y2 - the Y co-ordinate of the second corner of the rectangle
Since:
1.1.5

clipEllipse

public void clipEllipse(float x1,
                        float y1,
                        float x2,
                        float y2)

Set the clipping area to the ellipse inside the specified rectangle. The top and sides of the ellipse will touch the edges of the rectangle drawn between x1,y1 and x2,y2.

Parameters:
x1 - the X co-ordinate of the first corner of the rectangle
y1 - the Y co-ordinate of the first corner of the rectangle
x2 - the X co-ordinate of the second corner of the rectangle
y2 - the Y co-ordinate of the second corner of the rectangle
Since:
1.1.5

clipCircle

public void clipCircle(float x,
                       float y,
                       float radius)
Set the clipping area to a circle centered on x, y with a radius of radius.

Parameters:
x - the X co-ordinate of the center of the circle
y - the Y co-ordinate of the center of the circle
radius - the radius of the circle
Since:
1.1.5

drawLayoutBox

public void drawLayoutBox(LayoutBox box,
                          float x,
                          float y)
Draw a LayoutBox at the specified position on the page

Parameters:
box - the LayoutBox to draw
x - the X co-ordinate of the left hand side of the box
y - the Y co-ordinate of the top side of the box
Since:
1.2

drawImage

public void drawImage(PDFImage image,
                      float x1,
                      float y1,
                      float x2,
                      float y2)
Draw a PDFImage at the specified position on the page

Parameters:
image - the image to draw
x1 - the X co-ordinate of the left hand side of the image
y1 - the Y co-ordinate of the bottom side of the image
x2 - the X co-ordinate of the right hand side of the image
y2 - the Y co-ordinate of the top side of the image
Since:
1.0

drawCanvas

public void drawCanvas(PDFCanvas canvas,
                       float x1,
                       float y1,
                       float x2,
                       float y2)
Draw a PDFCanvas at the specified position on the page.

Parameters:
canvas - the canvas to draw
x1 - the X co-ordinate of the left hand side of the image
y1 - the Y co-ordinate of the bottom side of the image
x2 - the X co-ordinate of the right hand side of the image
y2 - the Y co-ordinate of the top side of the image
Since:
2.0

save

public void save()

Save the state of this page. This takes a snapshot of the currently applied style, position, clipping area and any rotation/translation/scaling that has been applied, which can be later restored with a call to restore().

Calls to save can be nested, but note that for most PDF viewers it is an error to save the page state but not restore it.

Throws:
IllegalStateException - if a save is performed with an open path or if saves are nested more than 28 deep.
Since:
1.0

restore

public void restore()
Restore the state that was saved with the last call to save()

Throws:
IllegalStateException - if there is no previously saved state
Since:
1.0

rotate

public void rotate(float x,
                   float y,
                   double angle)

Rotate the page. All future actions, like drawing lines or text, will be rotated around the specified point by the specified angle.

Parameters:
x - the X co-ordinate to rotate the page around
y - the Y co-ordinate to rotate the page around
angle - The number of degrees clockwise to rotate the page.

getAnnotations

public List getAnnotations()
Return a List of the PDFAnnotation objects on this page. The list may be manipulated using the standard List methods such as List.add(E), List.remove(java.lang.Object) and so on. If the page has no annotations an empty list is returned.

Since:
2.0 (although this method existed in prior versions, it returned an Array)

setTransition

public void setTransition(String style,
                          float displaytime,
                          float transitiontime)
Set a transition from this page to the next page, to allow the pages to be displayed as part of a presentation. Valid values for style are:
NoneNo transition is used (the default)
ReplaceThe current page is replaced with the new page. transitiontime is ignored
SplitHorizOutTwo lines sweep horizontally across the screen outward from the center of the page
SplitHorizInTwo lines sweep horizontally across the screen inwards from the edge of the page
SplitVertOutTwo lines sweep vertically across the screen outward from the center of the page
SplitVertInTwo lines sweep vertically across the screen inwards from the edge of the page
BlindsHorizMultiple lines sweep down across the page
BlindsVertMultiple lines sweep left-to-right across the page
BoxInA box sweeps inwards from the edge of the page
BoxOutA box sweeps outwards from the center of the page
WipeLeftToRightA single line sweeps across the page from left to right
WipeRightToLeftA single line sweeps across the page from right to left
WipeTopToBottomA single line sweeps across the page from top to bottom
WipeBottomToTopA single line sweeps across the page from bottom to top
DissolveThe old page dissolves gradually to reveal the new one
GlitterLeftToRightThe old page dissolves in a band running from left to right across the page
GlitterTopToBottomThe old page dissolves in a band running from top to bottom across the page
GlitterDiagonalThe old page dissolves in a band running from top-left to bottom-right across the page

Parameters:
style - the transition style as defined above
displaytime - the amount of time in seconds to display the page before automatically moving to the next page, or 0 for manual page transitions only
transitiontime - the amount of time to take over the transition, in seconds
Since:
2.0

drawText

public void drawText(String text,
                     float x,
                     float y)

Draw a line of text at the specified position. A simple way to draw a single line of text. The co-ordinates specify the position of the baseline of the first character - for other positions (e.g. to align the top of the text), adjust the co-ordinates by the return value from PDFStyle.getTextTop(java.lang.String) and friends.

Parameters:
text - the line of text to draw
x - the X co-ordinate to draw the text at
y - the Y co-ordinate to draw the text at
Since:
1.0

drawTextLink

public void drawTextLink(String text,
                         float x,
                         float y,
                         PDFAction action)

Draw a line of text at a the specified position, and set it to link to the specified action. A shorthand combination of drawText and beginTextLink.

Note that this method will not work as advertised if the position of the text has been modified via the rotate(float, float, double) method. This is a shortcoming inherent in the PDF document specification

Parameters:
text - the line of text to draw
x - the X co-ordinate to draw the text at
y - the Y co-ordinate to draw the text at
action - the action to perform when the text is clicked on
Since:
1.1

beginText

public void beginText(float x1,
                      float y1,
                      float x2,
                      float y2)

Begin a paragraph of text. The parameters specify the rectangle measured in the current canvas units that will fully contain the text. Left-to-right text will wrap when it reaches the right margin and continue being rendered until the bottom margin is reached, after which the text will not be rendered and all calls to drawText will return -1. This "overflowed" text can be rendered in a new block by calling continueText

Note: Although suitable for layout of simple text paragraphs, the beginText/drawText/continueText methods are not suitable for complicated text layout involving either precise measurement, such as is required when a paragraph is required to wrap at the end of a section or page. In this situation a LayoutBox should be used instead.

Parameters:
x1 - the X co-ordinate of the first corner of the text rectangle.
y1 - the Y co-ordinate of the first corner of the text rectangle.
x2 - the X co-ordinate of the second corner of the text rectangle.
y2 - the Y co-ordinate of the second corner of the text rectangle.
Throws:
IllegalStateException - if beginText has already been called (beginText-endText pairs can't be nested).
See Also:
LayoutBox

continueText

public float continueText(float x1,
                          float y1,
                          float x2,
                          float y2,
                          PDFPage page)

As for beginText, but continue any text that overflowed from the specified page. This method is a legacy method kept here for the large install base of 1.0 and 1.1 users. We do not recommend it for new development. If your text is going to be wrapping from one rectangle to another, we strongly recommend you use the LayoutBox class.

Parameters:
x1 - the X co-ordinate of the first corner of the text rectangle
y1 - the Y co-ordinate of the first corner of the text rectangle
x2 - the X co-ordinate of the second corner of the text rectangle
y2 - the Y co-ordinate of the second corner of the text rectangle
page - the page to take the overflowed text from
See Also:
LayoutBox

endText

public float endText(boolean justifylast)
End the paragraph of text.

Parameters:
justifylast - if the current text style is justified, whether to justify the last line of text. If the current style is not justified, this has no effect.
Returns:
the number of points that needed to be rendered to clear the buffer
Throws:
IllegalStateException - if beginText wasn't called first
See Also:
LayoutBox

discardText

public float discardText()
Discard the paragraph of text. This method is identical to endText in every way, except no text is actually rendered. Prior to the LayoutBox class, this was the only way to determine the height of a block of text without displaying it. It's nowhere near as efficient, and it's use for this purpose is strongly discouraged.

Returns:
the number of points that would have been rendered to clear the buffer
Since:
1.0.1
See Also:
LayoutBox

drawText

public float drawText(String text)

Draw a paragraph of text in the current style. The text is automatically wrapped at the edge of the box specified in the call to beginText, and is aligned according to the alignment of the current style.

If any characters in the string aren't available in the current font, they are ignored and a warning message is printed to System.err. The text to be drawn may contain newline characters, which have the predictable effect.

This method returns -1 if the text can't be displayed in the box specified by beginText. Use of this return value to measure and position text is discouraged, as it is inaccurate when mixing different font sizes on a line and can be plain wrong when the text box is nearly full. If exact sizing and positioning are a concern, please use the LayoutBox class instead.

Parameters:
text - the line of text to be drawn
Returns:
the number of points required to render the lines to the document (zero or more), or -1 if the text box is full.
Throws:
IllegalStateException - if no font or color is specified, or if beginText hasn't been called first.
See Also:
LayoutBox, PDFFont

beginTextLink

public void beginTextLink(PDFAction action,
                          PDFStyle linkstyle)

Start a "link" section in the text. Any text displayed between here and the corresponding endTextLink() method call will act as a AnnotationLink annotation, in the same way as the <A> tag does in HTML: When the user clicks on the text, the specified action is performed.

Note that this method will not work as advertised if the position of the text has been modified via the rotate(float, float, double) method. This is a shortcoming inherent in the PDF document specification.

Parameters:
action - the action to perform when the text is clicked on
linkstyle - the style to apply to any text within the link area, or null if the current style is to be used. For an underlined link, use PDFStyle.LINKSTYLE
Throws:
IllegalStateException - if a link has already been begun (links can't be nested)
Since:
1.1
See Also:
AnnotationLink, PDFStyle.LINKSTYLE

endTextLink

public PDFAnnotation[] endTextLink()

End the "link" section in the text, analogous to the </A> tag in HTML.

This method returns the list of annotations that were added - it's a list because if the link wrapped over several lines or pages, several annotations would have been added. The idea behind this is that you can add annotations to the text, and then set the actions they refer to (via the AnnotationLink.setAction(org.faceless.pdf2.PDFAction) method) after they've been added - for example, to link to a page that hasn't been created yet.

Throws:
IllegalStateException - if a link has not been begun
Since:
1.1

beginTag

public void beginTag(String tag,
                     Map atts)
Open a structural tag on this page. This call must be matched by a later call to endTag()

Since:
2.11.9
See Also:
PDFCanvas.beginTag(java.lang.String, java.util.Map)

endTag

public void endTag()
Close a structural tag on this page. This call must match an earlier call to beginTag()

Since:
2.11.9
See Also:
PDFCanvas.beginTag(java.lang.String, java.util.Map)

setThumbnail

public void setThumbnail(PDFImage image)
Set the embedded page thumbnail. Page thumbnails are not required, rarely used in modern PDFs and are ignore by many viewers (including Acrobat 9 or later). In most cases it's better to leave them unset as the viewer application will regenerate them. The exception is when pages are very large or complex, and a small file-size is not a consideration.

Parameters:
image - the thumbmail image, which ideally should have a longest dimension <= 105px
Since:
2.11.18

getThumbnail

public PDFImage getThumbnail()
Return the thumbnail image on the page, as set by setThumbnail(org.faceless.pdf2.PDFImage). May be null

Since:
2.11.18

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)
Add a PropertyChangeListener to this PDFPage. PropertyChangeEvents will be raised when various aspects of this annotation are changed

Since:
2.11.19
See Also:
FormElement.addPropertyChangeListener(java.beans.PropertyChangeListener), PDFAnnotation.addPropertyChangeListener(java.beans.PropertyChangeListener)

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)
Remove a previously added PropertyChangeListener from this PDFPage.

Since:
2.11.19
See Also:
addPropertyChangeListener(java.beans.PropertyChangeListener)

toString

public String toString()


Copyright © 2001-2013 Big Faceless Organization