org.faceless.pdf2

## Class PDFCanvas

- java.lang.Object
- - org.faceless.pdf2.PDFCanvas

- All Implemented Interfaces:
    Cloneable

      public class PDFCanvas
      extends Object

  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.

  Since:
    2.0

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `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

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `beginTag(String tag, Map<String,Object> 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

    - #### PDFCanvas

          public PDFCanvas(float width,
                           float height)

      Create a new blank canvas of the specified width and height
      Parameters:
        `width` - the canvas width in points
        `height` - the canvas height in points

    - #### PDFCanvas

          public PDFCanvas(float width,
                           float height,
                           float opacity)

      Create a new blank canvas of the specified width and height and with the specified opacity. The Canvas will form a transparency group of the specified opacity.
      Parameters:
        `width` - the canvas width in points
        `height` - the canvas height in points
        `opacity` - the opacity of the canvas - from 1 (opaque) to 0 (transparent)
      Since:
        2.7.2

    - #### PDFCanvas

          public PDFCanvas(PDFPage page)

      Create a new Canvas that's a clone of the specified `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.
      Since:
        2.0
      See Also:
        `PDFPage.setBox(java.lang.String, float, float, float, float)`

    - #### PDFCanvas

          public PDFCanvas(PDFCanvas canvas)

      Create a new Canvas that's a clone of the specified `PDFCanvas`. Since 2.2 the `canvas` passed in must have had `flush()` called on it first, otherwise an Exception is thrown.
      Since:
        2.0

    - #### PDFCanvas

          public PDFCanvas(String pattern,
                           float opacity)
                    throws MissingResourceException

      Load the specified resource as a canvas.
      Parameters:
        `pattern` - the name of the resource to load, eg "stamp.stencil.Confidential"
        `opacity` - the opacity to apply to the canvas
      Throws:
        `MissingResourceException`
      Since:
        2.0

  - ### Method Detail

    - #### flush

          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`

      Throws:
        `IllegalStateException` - if the canvas is incomplete - you have an open path or a `save()` without a matching `restore()`.
      Since:
        2.2

    - #### rawWrite

          public void rawWrite(String data)

      Write raw PDF commands to the canvas. 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 float getWidth()

      Return the width of the canvas
      Since:
        2.0

    - #### getHeight

          public float getHeight()

      Return the width of the canvas
      Since:
        2.0

    - #### setStyle

          public void setStyle(PDFStyle style)

      Set the style for this Canvas

    - #### 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:
        2.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:
        2.0

    - #### drawRoundedRectangle

          public 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).

      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
        `r` - 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:
        2.0

    - #### 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:
        2.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:
        2.0

    - #### 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:
        2.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:
        2.0

    - #### 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:
        2.0

    - #### drawShape

          public void drawShape(Shape shape)

      Draw a `Shape`. If the fill color is specified the Shape will be closed automatically if it isn't already.
      Since:
        2.11.7

    - #### drawGlyphVector

          public void drawGlyphVector(PDFGlyphVector gv,
                                      float x,
                                      float y)

      Draw a `PDFGlyphVector` onto the canvas. See that class for an example of how to use this method.
      Parameters:
        `gv` - the PDFGlyphVector to draw
        `x` - the X co-ordinate to position the left edge of the PDFGlyphVector
        `y` - the Y co-ordinate to position the baseline of the PDFGlyphVector
      Since:
        2.11.22
      See Also:
        `PDFGlyphVector`, `PDFStyle.createGlyphVector(java.lang.String, java.util.Locale)`

    - #### 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:
        2.0

    - #### clipRoundedRectangle

          public 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`.

      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
        `r` - 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:
        2.0

    - #### 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:
        2.0

    - #### 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:
        2.0

    - #### 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:
        2.0

    - #### clipShape

          public void clipShape(Shape shape)

      Clip a `Shape`
      Since:
        2.11.7

    - #### 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:
        2.0

    - #### pathLine

          public boolean 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:
        2.0

    - #### pathBezier

          public 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.
      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:
        2.0

    - #### pathArc

          public boolean 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:
        2.0

    - #### pathShape

          public boolean pathShape(Shape shape)

      Add the path specified by a `Shape` to the Canvas
      Parameters:
        `shape` - the shape
      Returns:
        true if any sections were drawn on the path
      Since:
        2.11.7

    - #### pathClose

          public void pathClose()

      Close the path by drawing a straight line back to its beginning. This does not complete the path, you still need to complete it with `pathPaint()` or `pathCancel()`
      Throws:
        `IllegalStateException` - if a path hasn't been started with `pathMove(float, float)`
      Since:
        2.0

    - #### pathCancel

          public void pathCancel()

      Cancel the current path
      Throws:
        `IllegalStateException` - if a path hasn't been started with `pathMove(float, float)`
      Since:
        2.0

    - #### pathPaint

          public void pathPaint()

      Close and paint the path. What this actually does depends on the currently applied `PDFStyle`
      - If the style has a LineColor specified but no FillColor, "stroke" the path by drawing it as an outline in the current line color
      - If the style has a FillColor specified but no LineColor, call `pathClose()` and "fill" the path with the current fill color
      - If the style has both a FillColor and a LineColor, call `pathClose()`, "fill" the path with the current fill color then "stroke" the path with the current line color.
      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:
        2.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:
        2.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:
        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:
        2.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:
        2.0

    - #### rotate

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

      Rotate the canvas around the specified point by the specified number of degrees. All further draw/path/clip actions on this canvas will be adjusted accordingly. The best way to get back to normal after a rotate is to wrap the rotate inside a `save()`/`restore()` block, eg.

             canvas.save();
             canvas.rotate(100,100,45);
             canvas.drawLayoutBox(rotatedtext, 100, 100);
             canvas.restore();

      Since:
        2.0

    - #### transform

          public void transform(AffineTransform transform)

      Apply an Affine Transformation to the canvas.
      Since:
        2.11.7

    - #### transform

          public void transform(double m00,
                                double m10,
                                double m01,
                                double m11,
                                double m02,
                                double m12)

      Apply an Affine Transformation to the canvas. The six arguments are the same 6 arguments passed in to the `AffineTransform` constructor, in the same same order.
      Since:
        2.7.7

    - #### 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:
        2.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
      Throws:
        `IllegalArgumentException` - if the canvas being drawn is this canvas - recursion is not allowed.
      Since:
        2.0

    - #### beginTag

          public void beginTag(String tag,
                               Map<String,Object> 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 or HTML:

           PDFCanvas canvas = new PDFCanvas(width, height);
           canvas.beginTag("Sect", null);
           LayoutBox box = new LayoutBox(600);
           box.addText("He said '", style, null);
           Map<String,Object> atts = new HashMap<String,Object>();
           atts.put("id", "quote1");
           box.beginTag("Quote", atts);
           box.addText("This is a contrived example", boldstyle, null);
           box.endTag();
           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`. A PDFCanvas with structural tags can only be drawn onto a page or another canvas once - an `IllegalStateException` will be thrown on a second attempt, or if it's drawn with an unclosed structural tag.

      While in general any values for tag are allowed, the following are suggested by the PDF specification

      Part | Part - A large-scale division of a document. This type of element is appropriate for grouping articles or sections.
      Art | Article - A relatively self-contained body of text constituting a single narrative or exposition. Articles should be disjoint; that is, they should not contain other articles as constituent elements.
      Sect | Section - A container for grouping related content elements. For example, a section might contain a heading, several introductory paragraphs, and two or more other sections nested within it as subsections.
      Div | Division A generic block-level element or group of elements.
      BlockQuote | Block quotation - A portion of text consisting of one or more paragraphs attributed to someone other than the author of the surrounding text.
      Caption | Caption - A brief portion of text describing a table or figure.
      TOC | Table Of Contents - A list made up of table of contents item entries (structure type TOCI) and/or other nested table of contents entries (TOC). A TOC entry that includes only TOCI entries represents a flat hierarchy. A TOC entry that includes other nested TOC entries (and possibly TOCI entries) represents a more complex hierarchy. Ideally, the hierarchy of a top level TOC entry reflects the structure of the main body of the document. Lists of figures and tables, as well as bibliographies, can be treated as tables of contents for purposes of the standard structure types.
      TOCI | Table of Contents Item - This entry’s children may be any of the following structure types: Lbl, Reference, NonStruct, P or TOC
      Index | A sequence of entries containing identifying text accompanied by Reference elements that point out occurrences of the specified text in the main body of a document.
      NonStruct | Nonstructural element - A grouping element having no inherent structural significance; it serves solely for grouping purposes. This type of element differs from a Div in that it shall not be interpreted or exported to other document formats; however, its descendants shall be processed normally.
      Private | Private Element - A grouping element containing private content belonging to the application producing it. The structural significance of this type of element is unspecified and shall be determined entirely by the conforming writer. Neither the Private element nor any of its descendants shall be interpreted or exported to other document formats.
      H | Heading - A label for a subdivision of a document’s content. It should be the first child of the Div that it heads.
      H1, H2, H3, H4, H5, H6 | Heading with specific levels - For use in conforming writers that cannot hierarchically nest their sections and thus cannot determine the level of a heading from its level of nesting.
      P | Paragraph - A low-level division of text.
      L | List - A sequence of items of like meaning and importance. Its immediate children should be an optional Caption followed by one or more LI
      LI | List Item - An individual member of a list. Its children may be one or more combinations of Lbl or LBody
      Lbl | Label - A name or number that distinguishes a given item from others in the same list or other group of like items. In a dictionary list, for example, it contains the term being defined; in a bulleted or numbered list, it contains the bullet character or the number of the list item and associated punctuation.
      LBody | List Body - The descriptive content of a list item. In a dictionary list, for example, it contains the definition of the term. It may either contain the content directly or have other block-level items, perhaps including nested lists, as children.
      Table | Table - A two-dimensional layout of rectangular data cells, possibly having a complex substructure. It contains either one or more TR as children; or an optional THead followed by one or more TBody and an optional TFoot. In addition, a table may have a Caption as its first or last child.
      TR | Table Row - A row of headings or data in a table. It may contain TH and TD
      TH | Table Header Cell - A table cell containing header text describing one or more rows or columns of the table.
      TD | Table Data Cell - A table cell containing data that is part of the table’s content.
      THead | Table header row group - A group of rows that constitute the header of a table. If the table is split across multiple pages, these rows may be redrawn at the top of each table fragment (although there is only one THead element).
      TBody | Table body row group - A group of rows that constitute the main body portion of a table. If the table is split across multiple pages, the body area may be broken apart on a row boundary. A table may have multiple TBody elements to allow for the drawing of a border or background for a set of rows.
      TFoot | Table footer row group - A group of rows that constitute the footer of a table. If the table is split across multiple pages, these rows may be redrawn at the bottom of each table fragment (although there is only one TFoot element.)
      Span | Span - A generic inline portion of text having no particular inherent characteristics. It can be used, for example, to delimit a range of text with a given set of styling attributes, although it's not necessary to identify italic or bold text with a Span (as in HTML), as this can be derived from the text.
      Quote | Quotation - An inline portion of text attributed to someone other than the author of the surrounding text. The quoted text should be contained inline within a single paragraph. This differs from the block-level element BlockQuote, which consists of one or more complete paragraphs (or other elements presented as if they were complete paragraphs).
      Note | Note - An item of explanatory text, such as a footnote or an endnote, that is referred to from within the body of the document. It may have a Lbl as a child. The note may be included as a child of the structure element in the body text that refers to it, or it may be included elsewhere (such as in an endnotes section) and accessed by means of a Reference.
      Reference | Reference - A citation to content elsewhere in the document.
      BibEntry | Bibliographic entry - A reference identifying the external source of some cited content. It may contain a Lbl as a child. Although a bibliography entry is likely to include component parts identifying the cited content’s author, work, publisher, and so forth, no standard structure types are defined at this level of detail.
      Code | Code entry - A fragment of computer program text
      Link | Link - An association between a portion of the inline items’s content and a corresponding `AnnotationLink`. Its children should be one or more content items or child inline items and one or more object references identifying the associated annotations.
      Annot | Annotation - An association between a portion of the inline items’s content and a corresponding `PDFAnnotation`. Its children should be one or more content items or child inline items and one or more object references identifying the associated annotations.
      Artifact | Artifact - Used to mark a section of text as a rendering artifact only. Artifacts are not considered part of the logical document structure. They take no attributes.

      Attributes for structural tags are unfortunately somewhat overengineered in the specification. For now we will handle the following attributes, with others being ignored:

      id | The ID for this node - should be unique across the PDF (the "ID" attribute)
      class or C | One or more class names for this node, separated by spaces (the "C" attribute)
      title or T | The optional human-readable description for the tag, eg "Chapter 1" (the "T" attribute)
      lang | The optional language code for the tag and its childen, can be a String or a `Locale`. An alternative to setting a `Locale` on the text, it is recommended not to mix the two approaches - if you're using `beginTag/endTag`, leave the locale in any calls to `LayoutBox.addText()` as `null` (the "Lang" attribute)
      alt | The alternate description for the structure element and its childen in human readable form (the "Alt" attribute).
      text or ActualText | Text that is an exact replacement for the structure element and its children. This can be used when the actual PDF text is being added in a font without a correct Unicode mapping, when text is being added as an image, or when text is known to be broken over several lines (for example) (the "ActualText" attribute)
      abbr or E | When an abbreviation is used, this attribute can be set to the unabbreviated version (the "E" attribute)
      annotation | For Link or Annot tags, the `PDFAnnotation` they refer to

      Parameters:
        `tag` - name of the tag
        `atts` - user defined attributes for this tag, or `null`
      Since:
        2.11.9
      See Also:
        `PDFPage.beginTag(java.lang.String, java.util.Map<java.lang.String, java.lang.Object>)`, `LayoutBox.beginTag(java.lang.String, java.util.Map<java.lang.String, java.lang.Object>)`, `endTag()`, `PDFPage.endTag()`, `LayoutBox.endTag()`

    - #### 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:
        `beginTag(java.lang.String, java.util.Map<java.lang.String, java.lang.Object>)`

    - #### 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:
        2.0

    - #### setWatermarkOrBackground

          public 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.

      Finally, if you are trying to create a watermark or background that is both displayed on screen and printed, there is no reason to call this method at all - you can simply draw the Canvas to the page in the normal fashion.

      Parameters:
        `screen` - whether to include the canvas when displayed on screen
        `print` - whether to include the canvas when printed
      Since:
        2.2.2

    - #### 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:
        2.11.18

    - #### toString

          public String toString()

Copyright © 2001-2015 Big Faceless Organization