org.faceless.pdf2

## Class PDFPage

- java.lang.Object
- - 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.

  - `drawLine()`, `drawRectangle()`, `drawPolygon()`, `drawEllipse()`, `drawCircle()`, `drawCircleArc()`, `drawEllipseArc()`, `drawRoundedRectangle()`: These methods draw simple shapes onto the page with a single method call.

          PDFPage page = pdf.newPage(PAGESIZE_A4);
          PDFStyle linestyle = new PDFStyle();
          linestyle.setLineColor(java.awt.Color.red);

          // Draw a rectangle with two diagonal lines inside it.
          page.setStyle(linestyle);
          page.drawRectangle(100,100, 400, 300);      // Box
          page.drawLine(100,100, 400, 300);           // Diagonal 1
          page.drawLine(100,300, 400, 100);           // Diagonal 2

  - `pathMove()`, `pathLine()`, `pathBezier()`, `pathArc()` and `pathClose()`: These more primitive methods allow greater control over the creation of geometric shapes, by creating a "path" which can then be drawn with the `pathPaint()` method.

          PDFPage page = pdf.newPage(PAGESIZE_A4);
          PDFStyle linestyle = new PDFStyle();
          linestyle.setLineColor(java.awt.Color.red);

          // Draw the same rectangle with two diagonal lines inside it.
          page.setStyle(linestyle);
          page.pathMove(100,100);     // Start Box
          page.pathLine(100,300);
          page.pathLine(400,300);
          page.pathLine(400,100);
          page.pathLine(100,300);     // Diagonal 1
          page.pathMove(100,100);     // Start Diagonal 2
          page.pathLine(400,300);
          page.pathPaint();           // Paint everything since the first pathMove

  3. Drawing Text
  - A single lines of text can be drawn at a specified location by using the `drawText(String, float, float)` method.

            PDFPage page = pdf.newPage(PAGESIZE_A4);
            PDFStyle textstyle = new PDFStyle();
            textstyle.setFillColor(java.awt.Color.black);
            textstyle.setFont(new StandardFont(StandardFont.COURIER), 12);

            // Draw some text at the specified location
            page.setStyle(textstyle);
            page.drawText("This is some text", 100, 100);

  - Larger blocks of text can be drawn by calling `beginText()`, followed by one or more calls to `drawText(String)`, and closing with a call to `endText()`. Until version 1.2 of the library, this method was the only way to draw text over multiple lines, and while it is quite capable (allowing you to mix several styles in a single paragraph), it does not handle wrapping at the end of a page or column well, cannot wrap around images or other blocks and has problems with exact positioning and measurement of text. It's also a bit slower than the next method. Still, we'll demonstrate it here for completeness.

            PDFPage page = pdf.newPage(PAGESIZE_A4);  // 595 x 842 points

            // Create first style - 12pt black Helvetica
            PDFStyle style1 = new PDFStyle();
            style1.setFillColor(java.awt.Color.black);
            style1.setFont(new StandardFont(StandardFont.HELVETICA), 12);

            // Create second style - 12pt black Verdana (TrueType font)
            PDFStyle style2 = (PDFStyle)style1.clone();
            PDFFont ver = new OpenTypeFont(new FileInputStream("verdana.ttf"), 1);
            style2.setFont(ver, 12);

            // Draw some text. Use the whole page, less a 100 point margin.
            page.beginText(100,100, page.getWidth()-100, page.getHeight()-100);

            page.setStyle(style1);
            page.drawText("This text is in ");
            page.setStyle(style2);
            page.drawText("Verdana.\n");
            page.setStyle(style1);
            page.drawText("And this is Helvetica again.");
            page.endText(false);

  - The final way to draw text is to use a `LayoutBox` class and the `drawLayoutBox()` method. This is the most powerful way to add text to a page, and has a number of advantages. See the `LayoutBox` class API documentation for more details. Here is a quick example that achieves a similar result to the example above.

            PDFPage page = pdf.newPage(PAGESIZE_A4);  // 595 x 842 points

            // Create first style - 12pt black Helvetica
            PDFStyle style1 = new PDFStyle();
            style1.setFillColor(java.awt.Color.black);
            style1.setFont(new StandardFont(StandardFont.HELVETICA), 12);

            // Create second style - 12pt black Verdana (TrueType font)
            PDFStyle style2 = (PDFStyle)style1.clone();
            PDFFont ver = new OpenTypeFont(new FileInputStream("verdana.ttf"), 1);

            LayoutBox box = new LayoutBox(page.getWidth()-200);
            box.addText("This text is in ", style1, null);
            box.addText("Verdana.", style2, null);
            box.addLineBreak(style2);
            box.addText("And this is Helvetica again.", style1, null);

            page.drawLayoutBox(box, 100, page.getHeight()-100);

  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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `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

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

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addPropertyChangeListener(PropertyChangeListener listener)` Add a PropertyChangeListener to this PDFPage.
    `void` | `beginTag(String tag, Map<String,Object> 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`.
    `void` | `clipShape(Shape shape)` Clip a `Shape`
    `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`.
    `void` | `drawShape(Shape shape)` Draw a `Shape` If the fill color is specified the Shape will be closed automatically if it isn't already.
    `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<PDFAnnotation>` | `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.
    `boolean` | `pathShape(Shape shape)` Add the path specified by a `Shape` to the Page
    `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` | `setMeasurementUnits(float x1, float y1, float x2, float y2, String scale)` Set the natural scale for measurements in the specified area of the page.
    `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()`
    `void` | `transform(AffineTransform transform)` Apply an Affine Transformation to the page.
    `void` | `transform(float a, float b, float c, float d, float e, float f)` Apply an Affine Transformation to the page.

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

      Note that like `setBox(java.lang.String, float, float, float, float)`, box coordinates are relative to the MediaBox (so, for example, when setting the MediaBox then the CropBox, the CropBox should be relative to the new MediaBox rather than the original).

      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. Note the page number starts at one, which is not so useful. Given all this method does internally is call `pdf.getPages().indexOf(page) + 1` you might consider doing that instead.
      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

    - #### 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.16

    - #### clipShape

          public void clipShape(Shape shape)

      Clip a `Shape`
      Since:
        2.16

    - #### pathShape

          public boolean pathShape(Shape shape)

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

    - #### 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`
      - 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:
        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.

    - #### transform

          public void transform(AffineTransform transform)

      Apply an Affine Transformation to the page. Note that the results for this operation will be incorrect if the `setUnits()` method has been called with `ORIGIN_PAGEBOTTOM` or `ORIGIN_PAGERIGHT`
      Since:
        2.16.1

    - #### transform

          public void transform(float a,
                                float b,
                                float c,
                                float d,
                                float e,
                                float f)

      Apply an Affine Transformation to the page. The six arguments are the same 6 arguments passed in to the `AffineTransform` constructor, in the same same order.
      Note that the results for this operation will be incorrect if the `setUnits()` method has been called with `ORIGIN_PAGEBOTTOM` or `ORIGIN_PAGERIGHT`
      Since:
        2.16.1

    - #### getAnnotations

          public List<PDFAnnotation> 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:

      None | No transition is used (the default)
      Replace | The current page is replaced with the new page. `transitiontime` is ignored
      SplitHorizOut | Two lines sweep horizontally across the screen outward from the center of the page
      SplitHorizIn | Two lines sweep horizontally across the screen inwards from the edge of the page
      SplitVertOut | Two lines sweep vertically across the screen outward from the center of the page
      SplitVertIn | Two lines sweep vertically across the screen inwards from the edge of the page
      BlindsHoriz | Multiple lines sweep down across the page
      BlindsVert | Multiple lines sweep left-to-right across the page
      BoxIn | A box sweeps inwards from the edge of the page
      BoxOut | A box sweeps outwards from the center of the page
      WipeLeftToRight | A single line sweeps across the page from left to right
      WipeRightToLeft | A single line sweeps across the page from right to left
      WipeTopToBottom | A single line sweeps across the page from top to bottom
      WipeBottomToTop | A single line sweeps across the page from bottom to top
      Dissolve | The old page dissolves gradually to reveal the new one
      GlitterLeftToRight | The old page dissolves in a band running from left to right across the page
      GlitterTopToBottom | The old page dissolves in a band running from top to bottom across the page
      GlitterDiagonal | The 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<String,Object> atts)

      Open a structural tag on this page. This call must be matched by a later call to `endTag()`. See the `PDFCanvas` version of this method for the full documnentation.
      Since:
        2.11.9
      See Also:
        `PDFCanvas.beginTag(java.lang.String, java.util.Map<java.lang.String, java.lang.Object>)`

    - #### endTag

          public void endTag()

      Close a structural tag on this page. This call must match an earlier call to `beginTag()` See the `PDFCanvas` version of this method for the full documnentation.
      Since:
        2.11.9
      See Also:
        `PDFCanvas.beginTag(java.lang.String, java.util.Map<java.lang.String, java.lang.Object>)`

    - #### 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. `PropertyChangeEvent`s 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)`

    - #### setMeasurementUnits

          public void setMeasurementUnits(float x1,
                                          float y1,
                                          float x2,
                                          float y2,
                                          String scale)

      Set the natural scale for measurements in the specified area of the page. This value is used in Acrobat only for measuring distances or areas on the page, although it may be used elsewhere by other tools. It has no impact on any other coordinate systems used in the PDF API.
      Parameters:
        `x1` - the X value of the lower-left corner of the rectangle
        `y1` - the Y value of the lower-left corner of the rectangle
        `x2` - the X value of the upper-right corner of the rectangle
        `y2` - the Y value of the upper-right corner of the rectangle
        `scale` - the scale, of the format "1pt = 20mm" - eg "10mm = 300mm", "1pt = 2in", "1in = 1mi".
      Since:
        2.14

    - #### toString

          public String toString()

Copyright © 2001-2015 Big Faceless Organization