|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.faceless.pdf2.PDFCanvas
public class PDFCanvas
This class represents a the visible content of a page, annotation or similar. Basically everything which is displayed in a document - pages, annotations, form fields and so on - has a Canvas at it's heart. In the PDF spec this is known as a "Content Stream".
Using a Canvas is very similar to using a PDFPage
- it's created, it's
width is specified and content is drawn onto it. Once created, a Canvas can
be used as the basis for a PDFImage
or PDFPattern
and applied
to a page.
Constructor Summary | |
---|---|
PDFCanvas(float width,
float height)
Create a new blank canvas of the specified width and height |
|
PDFCanvas(float width,
float height,
float opacity)
Create a new blank canvas of the specified width and height and with the specified opacity. |
|
PDFCanvas(PDFCanvas canvas)
Create a new Canvas that's a clone of the specified PDFCanvas . |
|
PDFCanvas(PDFPage page)
Create a new Canvas that's a clone of the specified PDFPage . |
|
PDFCanvas(String pattern,
float opacity)
Load the specified resource as a canvas. |
Method Summary | |
---|---|
void |
beginTag(String tag,
Map atts)
Open a structural tag on this page. |
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 r)
Set the clipping area to a rectangle with rounded corners which runs through the two corners x1,y1 and x2,y2 . |
void |
clipShape(Shape shape)
Clip a Shape |
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 |
drawGlyphVector(PDFGlyphVector gv,
float x,
float y)
Draw a PDFGlyphVector onto the canvas. |
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 r)
Draw a rectangle with rounded corners through the two corners x1,y1 and x2,y2 . |
void |
drawShape(Shape shape)
Draw a Shape . |
void |
endTag()
Close a structural tag on this page. |
void |
flush()
This method flushes any operations that have been written to the canvas, and closes the stream for further writes. |
float |
getHeight()
Return the width of the canvas |
float |
getWidth()
Return the width of the canvas |
boolean |
pathArc(float width,
float height,
float start,
float end)
Continue the open path in an arc to the specified position. |
boolean |
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 its beginning. |
boolean |
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. |
boolean |
pathShape(Shape shape)
Add the path specified by a Shape to the Canvas |
void |
rawWrite(String data)
Write raw PDF commands to the canvas. |
void |
restore()
Restore the state that was saved with the last call to save() |
void |
rotate(float x,
float y,
double ang)
Rotate the canvas around the specified point by the specified number of degrees. |
void |
save()
Save the state of this page. |
void |
setMetaData(String xmldata)
Set the XML metadata associated with this object. |
void |
setStyle(PDFStyle style)
Set the style for this Canvas |
void |
setWatermarkOrBackground(boolean screen,
boolean print)
Mark the canvas as being part of the Background or Watermark Layer. |
String |
toString()
|
void |
transform(AffineTransform transform)
Apply an Affine Transformation to the canvas. |
void |
transform(double m00,
double m10,
double m01,
double m11,
double m02,
double m12)
Apply an Affine Transformation to the canvas. |
Methods inherited from class java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Constructor Detail |
---|
public PDFCanvas(float width, float height)
width
- the canvas width in pointsheight
- the canvas height in pointspublic PDFCanvas(float width, float height, float opacity)
width
- the canvas width in pointsheight
- the canvas height in pointsopacity
- the opacity of the canvas - from 1 (opaque) to 0 (transparent)public PDFCanvas(PDFPage page)
PDFPage
.
Since 2.2 the page must have had the PDFPage.flush()
method called on it first, otherwise an IllegalStateException is thrown.
If the page has a CropBox defined that will be used as the size of the
canvas, not the MediaBox (which is what is returned from
PDFPage.getWidth()
and PDFPage.getHeight()
). If this isn't
the intention you can reset the CropBox before creating the canvas using
the setBox
method.
PDFPage.setBox(java.lang.String, float, float, float, float)
public PDFCanvas(PDFCanvas canvas)
PDFCanvas
.
Since 2.2 the canvas passed in must have had flush()
called
on it first, otherwise an Exception is thrown.
public PDFCanvas(String pattern, float opacity) throws MissingResourceException
pattern
- the name of the resource to load, eg "stamp.stencil.Confidential"opacity
- the opacity to apply to the canvas
MissingResourceException
Method Detail |
---|
public void flush()
This method flushes any operations that have been written to the canvas, and closes
the stream for further writes. Canvases must be flushed before they can be cloned
(by calling the PDFCanvas(PDFCanvas)
constructor).
After a canvas is flushed, it can still be written to, but this will cause the canvas to be uncompressed and recompressed, which isn't a very efficient operation in terms of time or memory and is therefore best avoided.
It is a good idea to flush a PDFCanvas after you've finished modifying it, as the
library can manage them more efficiently if it knows you're not expecting to
write to them again. In particular once they're flushed they may be written to disk
(or similar) by a Cache
IllegalStateException
- if the canvas is incomplete - you have an open path
or a save()
without a matching restore()
.public void rawWrite(String data)
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.public float getWidth()
public float getHeight()
public void setStyle(PDFStyle style)
public void drawLine(float x1, float y1, float x2, float y2)
x1,y1
to x2,y2
.
x1
- the X co-ordinate of the start of the liney1
- the Y co-ordinate of the start of the linex2
- the X co-ordinate of the end of the liney2
- the Y co-ordinate of the end of the linepublic 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).
x1
- the X co-ordinate of the first corner of the rectangley1
- the Y co-ordinate of the first corner of the rectanglex2
- the X co-ordinate of the second corner of the rectangley2
- the Y co-ordinate of the second corner of the rectanglepublic void drawRoundedRectangle(float x1, float y1, float x2, float y2, float r)
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).
x1
- the X co-ordinate of the first corner of the rectangley1
- the Y co-ordinate of the first corner of the rectanglex2
- the X co-ordinate of the second corner of the rectangley2
- the Y co-ordinate of the second corner of the rectangler
- 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)
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.
x
- the X co-ordinates of the verticesy
- the Y co-ordinates of the verticespublic void drawCircle(float x, float y, float radius)
x
, y
with a radius of radius
. A more convenient way to
draw circles than drawEllipse
x
- the X co-ordinate of the center of the circley
- the Y co-ordinate of the center of the circleradius
- the radius of the circlepublic 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).
x1
- the X co-ordinate of the first corner of the rectangley1
- the Y co-ordinate of the first corner of the rectanglex2
- the X co-ordinate of the second corner of the rectangley2
- the Y co-ordinate of the second corner of the rectanglepublic 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.
x1
- the X co-ordinate of the first corner of the rectangley1
- the Y co-ordinate of the first corner of the rectanglex2
- the X co-ordinate of the second corner of the rectangley2
- the Y co-ordinate of the second corner of the rectanglestart
- the start angle of the arc, in degrees clockwise from 12 o'clockend
- the end angle of the arc, in degrees clockwise from 12 o'clockpublic void drawCircleArc(float x, float y, float radius, float start, float end)
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.
x
- the X co-ordinate of the center of the circley
- the Y co-ordinate of the center of the circleradius
- the radius of the circlestart
- the start angle of the arc, in degrees clockwise from 12 o'clockend
- the end angle of the arc, in degrees clockwise from 12 o'clockpublic void drawShape(Shape shape)
Shape
.
If the fill color is specified the Shape will be closed
automatically if it isn't already.
public void drawGlyphVector(PDFGlyphVector gv, float x, float y)
PDFGlyphVector
onto the canvas. See that class for
an example of how to use this method.
gv
- the PDFGlyphVector to drawx
- the X co-ordinate to position the left edge of the PDFGlyphVectory
- the Y co-ordinate to position the baseline of the PDFGlyphVector
FailedRecodeException
- if the glyph vector cannot be rendered in this fontPDFGlyphVector
,
PDFStyle.createGlyphVector(java.lang.String, java.util.Locale)
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
.
x1
- the X co-ordinate of the first corner of the rectangley1
- the Y co-ordinate of the first corner of the rectanglex2
- the X co-ordinate of the second corner of the rectangley2
- the Y co-ordinate of the second corner of the rectanglepublic void clipRoundedRectangle(float x1, float y1, float x2, float y2, float r)
Set the clipping area to a rectangle with rounded corners which runs through
the two corners x1,y1
and x2,y2
.
x1
- the X co-ordinate of the first corner of the rectangley1
- the Y co-ordinate of the first corner of the rectanglex2
- the X co-ordinate of the second corner of the rectangley2
- the Y co-ordinate of the second corner of the rectangler
- 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)
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.
x
- the X co-ordinates of the verticesy
- the Y co-ordinates of the verticespublic 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
.
x1
- the X co-ordinate of the first corner of the rectangley1
- the Y co-ordinate of the first corner of the rectanglex2
- the X co-ordinate of the second corner of the rectangley2
- the Y co-ordinate of the second corner of the rectanglepublic void clipCircle(float x, float y, float radius)
x
, y
with a radius of radius
.
x
- the X co-ordinate of the center of the circley
- the Y co-ordinate of the center of the circleradius
- the radius of the circlepublic void clipShape(Shape shape)
Shape
public void pathMove(float x, float y)
x
- the X co-ordinate to move toy
- the Y co-ordinate to move topublic boolean pathLine(float x, float y)
x
- the X co-ordinate to move toy
- the Y co-ordinate to move to
IllegalStateException
- if a path hasn't been started with pathMove(float, float)
public boolean pathBezier(float cx1, float cy1, float cx2, float cy2, float x, float y)
cx1
- the X co-ordinate of the first control point for the curvecy1
- the Y co-ordinate of the first control point for the curvecx2
- the X co-ordinate of the second control point for the curvecy2
- the Y co-ordinate of the second control point for the curvex
- the X co-ordinate to move toy
- the Y co-ordinate to move to
IllegalStateException
- if a path hasn't been started with pathMove(float, float)
public boolean pathArc(float width, float height, float start, float end)
width
- the width of the ellipse to take the arc fromheight
- the height of the ellipse to take the arc fromstart
- the start angle of the arc, in degrees clockwise from 12 o'clockend
- the end angle of the arc, in degrees clockwise from 12 o'clock
IllegalStateException
- if a path hasn't been started with pathMove(float, float)
public boolean pathShape(Shape shape)
Shape
to the Canvas
shape
- the shape
public void pathClose()
pathPaint()
or pathCancel()
IllegalStateException
- if a path hasn't been started with pathMove(float, float)
public void pathCancel()
IllegalStateException
- if a path hasn't been started with pathMove(float, float)
public void pathPaint()
PDFStyle
pathClose()
and "fill" the path with the current fill colorpathClose()
, "fill" the path with the current fill color then "stroke"
the path with the current line color.
IllegalStateException
- if a path hasn't been started with pathMove(float, float)
,
or if neither a fill nor line color has been specified.public void pathClipAndPaint()
pathPaint()
, then set the
clipping area to the same are as described in 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.
IllegalStateException
- if a path hasn't been started with pathMove(float, float)
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.
IllegalStateException
- if a save is performed with an open path or if
saves are nested more than 28 deep.public void restore()
save()
IllegalStateException
- if there is no previously saved statepublic void rotate(float x, float y, double ang)
save()
/restore()
block, eg.
canvas.save(); canvas.rotate(100,100,45); canvas.drawLayoutBox(rotatedtext, 100, 100); canvas.restore();
public void transform(AffineTransform transform)
public void transform(double m00, double m10, double m01, double m11, double m02, double m12)
AffineTransform
constructor, in the same same
order.
public void drawImage(PDFImage image, float x1, float y1, float x2, float y2)
PDFImage
at the specified position on the page
image
- the image to drawx1
- the X co-ordinate of the left hand side of the imagey1
- the Y co-ordinate of the bottom side of the imagex2
- the X co-ordinate of the right hand side of the imagey2
- the Y co-ordinate of the top side of the imagepublic void drawCanvas(PDFCanvas canvas, float x1, float y1, float x2, float y2)
PDFCanvas
at the specified position on the page.
canvas
- the canvas to drawx1
- the X co-ordinate of the left hand side of the imagey1
- the Y co-ordinate of the bottom side of the imagex2
- the X co-ordinate of the right hand side of the imagey2
- the Y co-ordinate of the top side of the image
IllegalArgumentException
- if the canvas being drawn is this canvas - recursion is not allowed.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()
.
Structural tags add a tree structure on top of the otherwise flat
structure of a PDF. They are primarily used to meet accesibility
requirements, and so may be required for certain subsets of PDF
such as PDF/A-1a. Using the beginTag
and endtag
methods is fairly simple and should be familiar to anytone that has used SAX:
PDFCanvas canvas = new PDFCanvas(width, height); canvas.beginTag("P", null); LayoutBox box = new LayoutBox(600); box.addText("Some ", style, null); box.beginTag("B", null); box.addText("emphasised", boldstyle, null); box.endTag(); box.addText(" text", style, null); canvas.drawLayoutBox(box, x, y); canvas.endTag();
Calls to beginTag must be matched to calls to endTag for each
object - the methods exist in PDFPage
, PDFCanvas
and LayoutBox
. There are a few restrictions which are a result
of the specification - mainly, that a PDFCanvas containining Structured
Tags cannot be used in a PDF more than once, and that when drawn onto
a Page, the page must belong to a PDF.
beginTag(java.lang.String, java.util.Map)
public void endTag()
beginTag()
beginTag(java.lang.String, java.util.Map)
public void drawLayoutBox(LayoutBox box, float x, float y)
LayoutBox
at the specified position on the page
box
- the LayoutBox to drawx
- the X co-ordinate of the left hand side of the boxy
- the Y co-ordinate of the top side of the boxpublic void setWatermarkOrBackground(boolean screen, boolean print)
Mark the canvas as being part of the Background or Watermark Layer. Layers (also known as Optional Content) were added in Acrobat 6, and although they have many possible uses the most common is to add a watermark or background to a document. In Acrobat 6, this is done using the "Add Watermark & Background" option under the "Document" menu.
This method can be used to achieve a similar effect. Your watermark or background should
be drawn to a Canvas, which is then applied to the page with the PDFPage.drawCanvas()
method - to create a background rather than a watermark, draw the canvas after
a call to PDFPage.seekStart()
. Then this method should be called to tell Acrobat
whether to print this canvas, display it on screen or both (or neither).
This sounds more complicated than it is. Here's the outline of an example which creates a "COPY" background on the page which is printed but not displayed on screen.
PDFCanvas canvas = new PDFCanvas(300, 100); LayoutBox box = new LayoutBox(300); box.addText("COPY", mystyle, null); canvas.drawLayoutBox(box, 0, 100); canvas.flush(); page.seekStart(); // Draw canvas under the page content page.drawCanvas(canvas, 200, 400, 500, 300); canvas.setWatermarkOrBackground(false, true); // Print but do not display
Note: Any flags set with this method will be ignored by viewers other than
Acrobat 6 or later - in other viewers, the example PDF created above would have
"COPY" displayed both on screen and in print. If backwards compatibilty is required, a
similar effect that works in older viewers can be achieved using Annotations
.
This flag also has no effect on canvases used in any way other than being added to a page
with the PDFPage.drawCanvas()
method.
screen
- whether to include the canvas when displayed on screenprint
- whether to include the canvas when printedpublic void setMetaData(String xmldata)
PDF.setMetaData(java.lang.String)
for more information.
xmldata
- the XML data to embed into the document, or null to clear any existing metadata. No validation is performed on this input.public String toString()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |