Package org.faceless.pdf2

Class PDFPage

  • All Implemented Interfaces:
    Cloneable, PDFDrawable
    public final class PDFPage
extends Object
implements PDFDrawable
    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

    • 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

      • getUserUnit

        public float getUserUnit()
        Return the UserUnit, as set by setUserUnit(float)
        Since:
        2.22

      • setUserUnit

        public void setUserUnit​(float unit)

        Set the "User Unit" on the PDF. This is a new feature added in PDF 1.6 / Acrobat 5.0 to get around the self-imposed limitation in Acrobat on maximum page size, which is 14400x14400 units. By default a unit is a point, but this method can be used to change this - for example, setUserUnit(10) means a page size of 72x72 points is actually treated as 720x720 points by Acrobat.

        This scaling also applies to any PDFCanvas object drawn to the page, and any annotation or hyperlink coordinates. Moving an annotation from a page with UserUnits set to 2 to another page with UserUnits set to the default value of 1, will effectively halve the size of the annotation.

        This method is very similar to the setUnits(float, int) method, except that the user scale is stored with the PDF.

        Since:
        2.22

      • 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(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.

        Specified by:
        flush in interface PDFDrawable
        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 getBox(java.lang.String), 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()

      • getDefaultColorSpace

        public ColorSpace getDefaultColorSpace​(int components)

        Return the ColorSpace used by this page to anchor device-dependent colors to a profile. For example, the ColorSpace returned by getDefaultColorSpace(3) is used by all "Device RGB" colors on the page, effectively turning them into calibrated colors.

        The PDF API automatically sets a calibrated sRGB ColorSpace as the ColorSpace for all DeviceRGB content on the page. Unlike the use of "Output Intents" on the OutputProfile class, multiple ColorSpaces can be set, one each for Gray, RGB, and CMYK. This is a cheap way to convert pages containing both DeviceRGB and DeviceCMYK to using calibrated colors.

        Specified by:
        getDefaultColorSpace in interface PDFDrawable
        Parameters:
        components - identifies the Default ColorSpace we're requesting - valid values are 1 for Gray, 3 for RGB or 4 for CMYK.
        Returns:
        the Default ColorSpace requested, or null if none is set.
        Since:
        2.25

      • setDefaultColorSpace

        public void setDefaultColorSpace​(int components,
                                 ColorSpace cs)
        Set the ColorSpace to use to anchor device-dependent colors on this page, as described by getColorSpace(java.lang.String).
        Specified by:
        setDefaultColorSpace in interface PDFDrawable
        Parameters:
        components - identifies the Default ColorSpace to set - valid values are 1 for Gray, 3 for RGB or 4 for CMYK.
        cs - the ColorSpace to set, which must be either null (to delete the existing value) or a ColorSpace of a type that matches the "components" parameter.

      • setMetaData

        public void setMetaData​(String xmldata)
        Set the XML metadata associated with this object. Since 2.26 this method calls getXMP().read(new StringReader(xmldata == null ? "" : xmldata)). We strongly recommend using the getXMP() method and modifying the XMP directly rather than using this method.
        Specified by:
        setMetaData in interface PDFDrawable
        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
        See Also:
        getXMP()

      • getMetaData

        public Reader getMetaData()
                   throws IOException

        Return any XML metadata associated with this object.

        Since 2.26 this simply returns getXMP().isEmpty() ? null : new StringReader(getXMP().toString()). It is strongly recommended that any code migrates to using the getXMP() method.

        Since 2.24.3, the returned type is guaranteed to hava a toString() method that will return the Metadata as a String.

        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

      • getXMP

        public XMP getXMP()
        Return an XMP Metadata object representing any XML metadata associated with this object
        Returns:
        the XMP, which may be empty or invalid but will never be null
        Since:
        2.26

      • 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.
        Specified by:
        rawWrite in interface PDFDrawable
        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
        Specified by:
        setStyle in interface PDFDrawable
        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.
        Specified by:
        drawLine in interface PDFDrawable
        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).

        Specified by:
        drawRectangle in interface PDFDrawable
        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).

        Specified by:
        drawRoundedRectangle in interface PDFDrawable
        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.

        Specified by:
        drawPolygon in interface PDFDrawable
        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
        Specified by:
        drawCircle in interface PDFDrawable
        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).

        Specified by:
        drawEllipse in interface PDFDrawable
        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.

        Specified by:
        drawEllipseArc in interface PDFDrawable
        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.
        Specified by:
        drawCircleArc in interface PDFDrawable
        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.
        Specified by:
        drawShape in interface PDFDrawable
        Since:
        2.16

      • pathShape

        public boolean pathShape​(Shape shape)
        Add the path specified by a Shape to the Page
        Specified by:
        pathShape in interface PDFDrawable
        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.
        Specified by:
        pathMove in interface PDFDrawable
        Parameters:
        x - the X co-ordinate to move to
        y - the Y co-ordinate to move to
        Since:
        1.0

      • pathLine

        public boolean pathLine​(float x,
                        float y)
        Continue the open path in a straight line to the specified position.
        Specified by:
        pathLine in interface PDFDrawable
        Parameters:
        x - the X co-ordinate to move to
        y - the Y co-ordinate to move to
        Returns:
        true if any sections were drawn in the path
        Throws:
        IllegalStateException - if a path hasn't been started with pathMove(float, float)
        Since:
        1.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.
        Specified by:
        pathBezier in interface PDFDrawable
        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
        Returns:
        true if any sections were drawn in the path
        Throws:
        IllegalStateException - if a path hasn't been started with pathMove(float, float)
        Since:
        1.0

      • pathArc

        public boolean pathArc​(float width,
                       float height,
                       float start,
                       float end)
        Continue the open path in an arc to the specified position.
        Specified by:
        pathArc in interface PDFDrawable
        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
        Returns:
        true if any sections were drawn in the path
        Throws:
        IllegalStateException - if a path hasn't been started with pathMove(float, float)
        Since:
        1.1

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

        Specified by:
        pathClip in interface PDFDrawable
        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.
        Specified by:
        pathPaint in interface PDFDrawable
        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()
        Specified by:
        pathClipAndPaint in interface PDFDrawable
        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.

        Specified by:
        clipRoundedRectangle in interface PDFDrawable
        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.

        Specified by:
        clipPolygon in interface PDFDrawable
        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.

        Specified by:
        clipRectangle in interface PDFDrawable
        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.

        Specified by:
        clipEllipse in interface PDFDrawable
        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.
        Specified by:
        clipCircle in interface PDFDrawable
        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
        Specified by:
        drawLayoutBox in interface PDFDrawable
        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
        Specified by:
        drawImage in interface PDFDrawable
        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.
        Specified by:
        drawCanvas in interface PDFDrawable
        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.

        Specified by:
        save in interface PDFDrawable
        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()
        Specified by:
        restore in interface PDFDrawable
        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.

        Specified by:
        rotate in interface PDFDrawable
        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)
        Concatenate the specified AffineTransform to the page's current transform. All future actions, like drawing lines or text, will transformed with this matrix. Note that the results for this operation will be incorrect if the setUnits() method has been called with ORIGIN_PAGEBOTTOM or ORIGIN_PAGERIGHT
        Specified by:
        transform in interface PDFDrawable
        Since:
        2.16.1

      • transform

        public void transform​(double a,
                      double b,
                      double c,
                      double d,
                      double e,
                      double f)
        Concatenate the specified AffineTransform to the page's current transform. All future actions, like drawing lines or text, will transformed with this matrix. 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
        Specified by:
        transform in interface PDFDrawable
        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:
        NoneNo transition is used (the default)
        ReplaceThe current page is replaced with the new page. transitiontime is ignored
        SplitHorizOutTwo lines sweep horizontally across the screen outward from the center of the page
        SplitHorizInTwo lines sweep horizontally across the screen inwards from the edge of the page
        SplitVertOutTwo lines sweep vertically across the screen outward from the center of the page
        SplitVertInTwo lines sweep vertically across the screen inwards from the edge of the page
        BlindsHorizMultiple lines sweep down across the page
        BlindsVertMultiple lines sweep left-to-right across the page
        BoxInA box sweeps inwards from the edge of the page
        BoxOutA box sweeps outwards from the center of the page
        WipeLeftToRightA single line sweeps across the page from left to right
        WipeRightToLeftA single line sweeps across the page from right to left
        WipeTopToBottomA single line sweeps across the page from top to bottom
        WipeBottomToTopA single line sweeps across the page from bottom to top
        DissolveThe old page dissolves gradually to reveal the new one
        GlitterLeftToRightThe old page dissolves in a band running from left to right across the page
        GlitterTopToBottomThe old page dissolves in a band running from top to bottom across the page
        GlitterDiagonalThe old page dissolves in a band running from top-left to bottom-right across the page
        Parameters:
        style - the transition style as defined above
        displaytime - the amount of time in seconds to display the page before automatically moving to the next page, or 0 for manual page transitions only
        transitiontime - the amount of time to take over the transition, in seconds
        Since:
        2.0

      • drawText

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

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

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

      • drawTextLink

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

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

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

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

      • beginText

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

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

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

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

      • continueText

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

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

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

      • endText

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

      • discardText

        public float discardText()
        Discard the paragraph of text. This method is identical to endText in every way, except no text is actually rendered. Prior to the LayoutBox class, this was the only way to determine the height of a block of text without displaying it. It's nowhere near as efficient, and it's use for this purpose is strongly discouraged.
        Returns:
        the number of points that would have been rendered to clear the buffer
        Since:
        1.0.1
        See Also:
        LayoutBox

      • drawText

        public float drawText​(String text)

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

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

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

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

      • beginTextLink

        public void beginTextLink​(PDFAction action,
                          PDFStyle linkstyle)

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

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

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

      • endTextLink

        public PDFAnnotation[] endTextLink()

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

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

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

      • 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

      • 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

      • getMeasurements

        public List<Measurement> getMeasurements()
        Return a read-only list of Measurement object associated with this page, or an empty list if there are none.
        Returns:
        the list of measurements
        Since:
        2.29

      • putUserData

        public void putUserData​(String key,
                        Object value)
        Set a custom property on this object. The property will be saved with the file with the "BFOO_" prefix unless it already has a valid four-character prefix.
        Parameters:
        value - a CharSequence, Number, Date, Calendar, Boolean, byte[], or a List/Map of those values, or null to remove the property
        Since:
        2.24.2

      • getUserData

        public Object getUserData​(String key)
        Return a property previously set on this object with the putUserData() method
        Returns:
        a String, Boolean, Number, Calendar, byte[] or a Map/List of those values if found, or null if no such property exists.
        Since:
        2.24.2

      • getAssociatedFiles

        public Collection<EmbeddedFile> getAssociatedFiles()
        Return the list of embedded files assocatiated with this PDFAnnotation. The list is live and can be edited. The ability to associate files with a PDFAnnotation is new in PDF 2.0.
        Since:
        2.26
        See Also:
        AnnotationFile

      • createGraphics

        public Graphics2D createGraphics​(PDF pdf)
        Create a Graphics2D object which can be used to write to this page. See the PDFCanvas.createGraphics(org.faceless.pdf2.PDF) method for full documentation.
        Parameters:
        pdf - the PDF - required, although if its specified as null it will use the value of page.getPDF()
        Since:
        2.26.3

      • getDocumentPart

        public DocumentPart getDocumentPart()
        Return the DocumentPart this page belongs to, or null if it doesn't belong to any
        Since:
        2.28.3

      • toString

        public String toString()