PDFFactory (Apache FOP 2.7 API)
Date: 2022-01-12

org.apache.fop.pdf

## Class PDFFactory

- java.lang.Object
- - org.apache.fop.pdf.PDFFactory

-     public class PDFFactory
      extends java.lang.Object

  This class provides method to create and register PDF objects.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DEFAULT_PDF_RESOLUTION` Resolution of the User Space coordinate system (72dpi).

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PDFFactory(PDFDocument document)` Creates a new PDFFactory.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.Object` | `createPDFEncoding(SingleByteEncoding encoding, java.lang.String fontName)` Creates a PDFEncoding instance from a CodePointMapping instance.
    `PDFDocument` | `getDocument()` Returns the parent PDFDocument associated with this factory.
    `PDFAction` | `getExternalAction(java.lang.String target, boolean newWindow)` Create/find and return the appropriate external PDFAction according to the target
    `java.lang.String` | `getGoToReference(java.lang.String pdfPageRef, float yoffset)` Create or find a PDF GoTo with the given page reference string and Y offset, and return its PDF object reference
    `PDFGoTo` | `getPDFGoTo(java.lang.String pdfPageRef, java.awt.geom.Point2D position)` Finds and returns a PDFGoTo to the given page and position.
    `protected PDFDestination` | `getUniqueDestination(PDFDestination newdest)` Registers and returns newdest if it is unique.
    `PDFAnnotList` | `makeAnnotList()` Make an annotation list object
    `PDFArray` | `makeArray(int[] values)` Make an Array object (ex.
    `PDFDestination` | `makeDestination(java.lang.String idRef, java.lang.Object goToRef)` Make a named destination.
    `PDFDests` | `makeDests(java.util.List destinationList)` Make a the head object of the name dictionary (the /Dests object).
    `void` | `makeDPart(PDFPage page, java.lang.String pageMasterName)`
    `PDFDPartRoot` | `makeDPartRoot()`
    `PDFEncoding` | `makeEncoding(java.lang.String encodingName)` make a /Encoding object
    `PDFFont` | `makeFont(java.lang.String fontname, java.lang.String basefont, java.lang.String encoding, FontMetrics metrics, FontDescriptor descriptor)` Make a Type1 /Font object.
    `AbstractPDFStream` | `makeFontFile(FontDescriptor desc, java.lang.String fontPrefix)` Embeds a font.
    `PDFFunction` | `makeFunction(java.util.List domain, java.util.List range, float[] cZero, float[] cOne, double interpolationExponentN)` make a type Exponential interpolation function (for shading usually)
    `PDFGState` | `makeGState(java.util.Map settings, PDFGState current)` make an ExtGState for extra graphics options This tries to find a GState that will setup the correct values for the current context.
    `PDFICCBasedColorSpace` | `makeICCBasedColorSpace(PDFResourceContext res, java.lang.String explicitName, PDFICCStream iccStream)` Makes a new ICCBased color space and registers it in the resource context.
    `protected PDFInfo` | `makeInfo(java.lang.String prod)` make an /Info object
    `PDFLayer` | `makeLayer(java.lang.String id)`
    `PDFLink` | `makeLink(java.awt.geom.Rectangle2D rect, PDFAction pdfAction)` Create a PDF link to an existing PDFAction object
    `PDFLink` | `makeLink(java.awt.geom.Rectangle2D rect, java.lang.String dest, boolean isNamedDestination)` Make an internal link.
    `PDFLink` | `makeLink(java.awt.geom.Rectangle2D rect, java.lang.String destination, int linkType, float yoffset)` Make a `PDFLink` object
    `PDFLink` | `makeLink(java.awt.geom.Rectangle2D rect, java.lang.String page, java.lang.String dest)` Make an internal link.
    `PDFMetadata` | `makeMetadata(org.apache.xmlgraphics.xmp.Metadata meta, boolean readOnly)` Make a Metadata object.
    `PDFNames` | `makeNames()` Make a names dictionary (the /Names object).
    `PDFNameTreeNode` | `makeNameTreeNode()` Make a name tree node.
    `PDFNavigator` | `makeNavigator(java.lang.String id)`
    `PDFOutline` | `makeOutline(PDFOutline parent, java.lang.String label, PDFAction pdfAction, boolean showSubItems)` Make an outline object and add it to the given parent
    `PDFOutline` | `makeOutline(PDFOutline parent, java.lang.String label, PDFReference actionRef, boolean showSubItems)` Make an outline object and add it to the given parent
    `PDFOutline` | `makeOutline(PDFOutline parent, java.lang.String label, java.lang.String destination, float yoffset, boolean showSubItems)` Make an outline object and add it to the given outline
    `PDFOutputIntent` | `makeOutputIntent()` Make a OutputIntent dictionary.
    `PDFPage` | `makePage(PDFResources resources, int pageWidth, int pageHeight)` Make a /Page object.
    `PDFPage` | `makePage(PDFResources resources, int pageWidth, int pageHeight, int pageIndex)` Make a /Page object.
    `PDFPage` | `makePage(PDFResources resources, int pageIndex, java.awt.geom.Rectangle2D mediaBox, java.awt.geom.Rectangle2D cropBox, java.awt.geom.Rectangle2D bleedBox, java.awt.geom.Rectangle2D trimBox)` Make a /Page object.
    `PDFPageLabels` | `makePageLabels()` Make a names dictionary (the /PageLabels object).
    `PDFPages` | `makePages()` Make a /Pages object.
    `PDFPattern` | `makePattern(PDFResourceContext res, int thePatternType, PDFResources theResources, int thePaintType, int theTilingType, java.util.List theBBox, double theXStep, double theYStep, java.util.List theMatrix, java.util.List theXUID, java.lang.StringBuffer thePatternDataStream)` Make a tiling pattern
    `PDFICCStream` | `makePDFICCStream()` Create a PDFICCStream
    `PDFResources` | `makeResources()` Make a /Resources object.
    `PDFRoot` | `makeRoot(PDFPages pages)` Make a /Catalog (Root) object.
    `PDFSeparationColorSpace` | `makeSeparationColorSpace(PDFResourceContext res, org.apache.xmlgraphics.java2d.color.NamedColorSpace ncs)` Create a new Separation color space.
    `PDFSetOCGStateAction` | `makeSetOCGStateAction(java.lang.String id)`
    `PDFStream` | `makeStream(java.lang.String type, boolean add)` Make a stream object
    `PDFTransitionAction` | `makeTransitionAction(java.lang.String id)`
    `PDFFunction` | `registerFunction(PDFFunction function)` Registers a function against the document
    `PDFPattern` | `registerPattern(PDFResourceContext res, PDFPattern pattern)`
    `PDFShading` | `registerShading(PDFResourceContext res, PDFShading shading)` Registers a shading object against the document

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### DEFAULT_PDF_RESOLUTION

          public static final int DEFAULT_PDF_RESOLUTION

      Resolution of the User Space coordinate system (72dpi).
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### PDFFactory

          public PDFFactory(PDFDocument document)

      Creates a new PDFFactory.
      Parameters:
        `document` - the parent PDFDocument needed to register the generated objects

  - ### Method Detail

    - #### getDocument

          public final PDFDocument getDocument()

      Returns the parent PDFDocument associated with this factory.
      Returns:
        PDFDocument the parent PDFDocument

    - #### makeRoot

          public PDFRoot makeRoot(PDFPages pages)

      Make a /Catalog (Root) object. This object is written in the trailer.
      Parameters:
        `pages` - the pages pdf object that the root points to
      Returns:
        the new pdf root object for this document

    - #### makePages

          public PDFPages makePages()

      Make a /Pages object. This object is written in the trailer.
      Returns:
        a new PDF Pages object for adding pages to

    - #### makeResources

          public PDFResources makeResources()

      Make a /Resources object. This object is written in the trailer.
      Returns:
        a new PDF resources object

    - #### makeInfo

          protected PDFInfo makeInfo(java.lang.String prod)

      make an /Info object
      Parameters:
        `prod` - string indicating application producing the PDF
      Returns:
        the created /Info object

    - #### makeMetadata

          public PDFMetadata makeMetadata(org.apache.xmlgraphics.xmp.Metadata meta,
                                          boolean readOnly)

      Make a Metadata object.
      Parameters:
        `meta` - the DOM Document containing the XMP metadata.
        `readOnly` - true if the metadata packet should be marked read-only
      Returns:
        the newly created Metadata object

    - #### makeOutputIntent

          public PDFOutputIntent makeOutputIntent()

      Make a OutputIntent dictionary.
      Returns:
        the newly created OutputIntent dictionary

    - #### makePage

          public PDFPage makePage(PDFResources resources,
                                  int pageIndex,
                                  java.awt.geom.Rectangle2D mediaBox,
                                  java.awt.geom.Rectangle2D cropBox,
                                  java.awt.geom.Rectangle2D bleedBox,
                                  java.awt.geom.Rectangle2D trimBox)

      Make a /Page object. The page is assigned an object number immediately so references can already be made. The page must be added to the PDFDocument later using addObject().
      Parameters:
        `resources` - resources object to use
        `pageIndex` - index of the page (zero-based)
        `mediaBox` - the MediaBox area
        `cropBox` - the CropBox area
        `bleedBox` - the BleedBox area
        `trimBox` - the TrimBox area
      Returns:
        the created /Page object

    - #### makePage

          public PDFPage makePage(PDFResources resources,
                                  int pageWidth,
                                  int pageHeight,
                                  int pageIndex)

      Make a /Page object. The page is assigned an object number immediately so references can already be made. The page must be added to the PDFDocument later using addObject().
      Parameters:
        `resources` - resources object to use
        `pageWidth` - width of the page in points
        `pageHeight` - height of the page in points
        `pageIndex` - index of the page (zero-based)
      Returns:
        the created /Page object

    - #### makePage

          public PDFPage makePage(PDFResources resources,
                                  int pageWidth,
                                  int pageHeight)

      Make a /Page object. The page is assigned an object number immediately so references can already be made. The page must be added to the PDFDocument later using addObject().
      Parameters:
        `resources` - resources object to use
        `pageWidth` - width of the page in points
        `pageHeight` - height of the page in points
      Returns:
        the created /Page object

    - #### makeFunction

          public PDFFunction makeFunction(java.util.List domain,
                                          java.util.List range,
                                          float[] cZero,
                                          float[] cOne,
                                          double interpolationExponentN)

      make a type Exponential interpolation function (for shading usually)
      Parameters:
        `domain` - List objects of Double objects. This is the domain of the function. See page 264 of the PDF 1.3 Spec.
        `range` - List of Doubles that is the Range of the function. See page 264 of the PDF 1.3 Spec.
        `cZero` - This is a vector of Double objects which defines the function result when x=0. This attribute is optional. It's described on page 268 of the PDF 1.3 spec.
        `cOne` - This is a vector of Double objects which defines the function result when x=1. This attribute is optional. It's described on page 268 of the PDF 1.3 spec.
        `interpolationExponentN` - This is the inerpolation exponent. This attribute is required. PDF Spec page 268
      Returns:
        the PDF function that was created

    - #### registerFunction

          public PDFFunction registerFunction(PDFFunction function)

      Registers a function against the document
      Parameters:
        `function` - The function to register

    - #### registerShading

          public PDFShading registerShading(PDFResourceContext res,
                                            PDFShading shading)

      Registers a shading object against the document
      Parameters:
        `res` - The PDF resource context
        `shading` - The shading object to be registered

    - #### makePattern

          public PDFPattern makePattern(PDFResourceContext res,
                                        int thePatternType,
                                        PDFResources theResources,
                                        int thePaintType,
                                        int theTilingType,
                                        java.util.List theBBox,
                                        double theXStep,
                                        double theYStep,
                                        java.util.List theMatrix,
                                        java.util.List theXUID,
                                        java.lang.StringBuffer thePatternDataStream)

      Make a tiling pattern
      Parameters:
        `res` - the PDF resource context to add the shading, may be null
        `thePatternType` - the type of pattern, which is 1 for tiling.
        `theResources` - the resources associated with this pattern
        `thePaintType` - 1 or 2, colored or uncolored.
        `theTilingType` - 1, 2, or 3, constant spacing, no distortion, or faster tiling
        `theBBox` - List of Doubles: The pattern cell bounding box
        `theXStep` - horizontal spacing
        `theYStep` - vertical spacing
        `theMatrix` - Optional List of Doubles transformation matrix
        `theXUID` - Optional vector of Integers that uniquely identify the pattern
        `thePatternDataStream` - The stream of pattern data to be tiled.
      Returns:
        the PDF pattern that was created

    - #### registerPattern

          public PDFPattern registerPattern(PDFResourceContext res,
                                            PDFPattern pattern)

    - #### getUniqueDestination

          protected PDFDestination getUniqueDestination(PDFDestination newdest)

      Registers and returns newdest if it is unique. Otherwise, returns the equal destination already present in the document.
      Parameters:
        `newdest` - a new, as yet unregistered destination
      Returns:
        newdest if unique, else the already registered instance

    - #### makeDestination

          public PDFDestination makeDestination(java.lang.String idRef,
                                                java.lang.Object goToRef)

      Make a named destination.
      Parameters:
        `idRef` - ID Reference for this destination (the name of the destination)
        `goToRef` - Object reference to the GoTo Action
      Returns:
        the newly created destrination

    - #### makeNames

          public PDFNames makeNames()

      Make a names dictionary (the /Names object).
      Returns:
        the new PDFNames object

    - #### makePageLabels

          public PDFPageLabels makePageLabels()

      Make a names dictionary (the /PageLabels object).
      Returns:
        the new PDFPageLabels object

    - #### makeDests

          public PDFDests makeDests(java.util.List destinationList)

      Make a the head object of the name dictionary (the /Dests object).
      Parameters:
        `destinationList` - a list of PDFDestination instances
      Returns:
        the new PDFDests object

    - #### makeNameTreeNode

          public PDFNameTreeNode makeNameTreeNode()

      Make a name tree node.
      Returns:
        the new name tree node

    - #### makeLink

          public PDFLink makeLink(java.awt.geom.Rectangle2D rect,
                                  PDFAction pdfAction)

      Create a PDF link to an existing PDFAction object
      Parameters:
        `rect` - the hotspot position in absolute coordinates
        `pdfAction` - the PDFAction that this link refers to
      Returns:
        the new PDFLink object, or null if either rect or pdfAction is null

    - #### makeLink

          public PDFLink makeLink(java.awt.geom.Rectangle2D rect,
                                  java.lang.String page,
                                  java.lang.String dest)

      Make an internal link.
      Parameters:
        `rect` - the hotspot position in absolute coordinates
        `page` - the target page reference value
        `dest` - the position destination
      Returns:
        the new PDF link object

    - #### makeLink

          public PDFLink makeLink(java.awt.geom.Rectangle2D rect,
                                  java.lang.String dest,
                                  boolean isNamedDestination)

      Make an internal link.
      Parameters:
        `rect` - the hotspot position in absolute coordinates
        `dest` - the position destination
        `isNamedDestination` - set to true if dest param is a named destination
      Returns:
        the new PDF link object

    - #### makeLink

          public PDFLink makeLink(java.awt.geom.Rectangle2D rect,
                                  java.lang.String destination,
                                  int linkType,
                                  float yoffset)

      Make a `PDFLink` object
      Parameters:
        `rect` - the clickable rectangle
        `destination` - the destination file
        `linkType` - the link type
        `yoffset` - the yoffset on the page for an internal link
      Returns:
        the PDFLink object created

    - #### getExternalAction

          public PDFAction getExternalAction(java.lang.String target,
                                             boolean newWindow)

      Create/find and return the appropriate external PDFAction according to the target
      Parameters:
        `target` - The external target. This may be a PDF file name (optionally with internal page number or destination) or any type of URI.
        `newWindow` - boolean indicating whether the target should be displayed in a new window
      Returns:
        the PDFAction thus created or found

    - #### getGoToReference

          public java.lang.String getGoToReference(java.lang.String pdfPageRef,
                                                   float yoffset)

      Create or find a PDF GoTo with the given page reference string and Y offset, and return its PDF object reference
      Parameters:
        `pdfPageRef` - the PDF page reference, e.g. "23 0 R"
        `yoffset` - the distance from the bottom of the page in points
      Returns:
        the GoTo's object reference

    - #### getPDFGoTo

          public PDFGoTo getPDFGoTo(java.lang.String pdfPageRef,
                                    java.awt.geom.Point2D position)

      Finds and returns a PDFGoTo to the given page and position. Creates the PDFGoTo if not found.
      Parameters:
        `pdfPageRef` - the PDF page reference
        `position` - the (X,Y) position in points
      Returns:
        the new or existing PDFGoTo object

    - #### makeOutline

          public PDFOutline makeOutline(PDFOutline parent,
                                        java.lang.String label,
                                        PDFReference actionRef,
                                        boolean showSubItems)

      Make an outline object and add it to the given parent
      Parameters:
        `parent` - the parent PDFOutline object (may be null)
        `label` - the title for the new outline object
        `actionRef` - the action reference string to be placed after the /A
        `showSubItems` - whether to initially display child outline items
      Returns:
        the new PDF outline object

    - #### makeOutline

          public PDFOutline makeOutline(PDFOutline parent,
                                        java.lang.String label,
                                        PDFAction pdfAction,
                                        boolean showSubItems)

      Make an outline object and add it to the given parent
      Parameters:
        `parent` - the parent PDFOutline object (may be null)
        `label` - the title for the new outline object
        `pdfAction` - the action that this outline item points to - must not be null!
        `showSubItems` - whether to initially display child outline items
      Returns:
        the new PDFOutline object, or null if pdfAction is null

    - #### makeOutline

          public PDFOutline makeOutline(PDFOutline parent,
                                        java.lang.String label,
                                        java.lang.String destination,
                                        float yoffset,
                                        boolean showSubItems)

      Make an outline object and add it to the given outline
      Parameters:
        `parent` - parent PDFOutline object which may be null
        `label` - the title for the new outline object
        `destination` - the reference string for the action to go to
        `yoffset` - the yoffset on the destination page
        `showSubItems` - whether to initially display child outline items
      Returns:
        the new PDF outline object

    - #### makeEncoding

          public PDFEncoding makeEncoding(java.lang.String encodingName)

      make a /Encoding object
      Parameters:
        `encodingName` - character encoding scheme name
      Returns:
        the created /Encoding object

    - #### makeFont

          public PDFFont makeFont(java.lang.String fontname,
                                  java.lang.String basefont,
                                  java.lang.String encoding,
                                  FontMetrics metrics,
                                  FontDescriptor descriptor)

      Make a Type1 /Font object.
      Parameters:
        `fontname` - internal name to use for this font (eg "F1")
        `basefont` - name of the base font (eg "Helvetica")
        `encoding` - character encoding scheme used by the font
        `metrics` - additional information about the font
        `descriptor` - additional information about the font
      Returns:
        the created /Font object

    - #### createPDFEncoding

          public java.lang.Object createPDFEncoding(SingleByteEncoding encoding,
                                                    java.lang.String fontName)

      Creates a PDFEncoding instance from a CodePointMapping instance.
      Parameters:
        `encoding` - the code point mapping (encoding)
        `fontName` - ...
      Returns:
        the PDF Encoding dictionary (or a String with the predefined encoding)

    - #### makeFontFile

          public AbstractPDFStream makeFontFile(FontDescriptor desc,
                                                java.lang.String fontPrefix)

      Embeds a font.
      Parameters:
        `desc` - FontDescriptor of the font.
      Returns:
        PDFStream The embedded font file

    - #### makeStream

          public PDFStream makeStream(java.lang.String type,
                                      boolean add)

      Make a stream object
      Parameters:
        `type` - the type of stream to be created
        `add` - if true then the stream will be added immediately
      Returns:
        the stream object created

    - #### makePDFICCStream

          public PDFICCStream makePDFICCStream()

      Create a PDFICCStream
      Returns:
        the new PDF ICC stream object
      See Also:
        `PDFImageXObject`, `PDFDeviceColorSpace`

    - #### makeICCBasedColorSpace

          public PDFICCBasedColorSpace makeICCBasedColorSpace(PDFResourceContext res,
                                                              java.lang.String explicitName,
                                                              PDFICCStream iccStream)

      Makes a new ICCBased color space and registers it in the resource context.
      Parameters:
        `res` - the PDF resource context to add the shading, may be null
        `explicitName` - the explicit name for the color space, may be null
        `iccStream` - the ICC stream to associate with this color space
      Returns:
        the newly instantiated color space

    - #### makeSeparationColorSpace

          public PDFSeparationColorSpace makeSeparationColorSpace(PDFResourceContext res,
                                                                  org.apache.xmlgraphics.java2d.color.NamedColorSpace ncs)

      Create a new Separation color space.
      Parameters:
        `res` - the resource context (may be null)
        `ncs` - the named color space to map to a separation color space
      Returns:
        the newly created Separation color space

    - #### makeArray

          public PDFArray makeArray(int[] values)

      Make an Array object (ex. Widths array for a font).
      Parameters:
        `values` - the int array values
      Returns:
        the PDF Array with the int values

    - #### makeGState

          public PDFGState makeGState(java.util.Map settings,
                                      PDFGState current)

      make an ExtGState for extra graphics options This tries to find a GState that will setup the correct values for the current context. If there is no suitable GState it will create a new one.
      Parameters:
        `settings` - the settings required by the caller
        `current` - the current GState of the current PDF context
      Returns:
        a PDF GState, either an existing GState or a new one

    - #### makeAnnotList

          public PDFAnnotList makeAnnotList()

      Make an annotation list object
      Returns:
        the annotation list object created

    - #### makeLayer

          public PDFLayer makeLayer(java.lang.String id)

    - #### makeSetOCGStateAction

          public PDFSetOCGStateAction makeSetOCGStateAction(java.lang.String id)

    - #### makeTransitionAction

          public PDFTransitionAction makeTransitionAction(java.lang.String id)

    - #### makeNavigator

          public PDFNavigator makeNavigator(java.lang.String id)

    - #### makeDPart

          public void makeDPart(PDFPage page,
                                java.lang.String pageMasterName)

    - #### makeDPartRoot

          public PDFDPartRoot makeDPartRoot()

Copyright 1999-2022 The Apache Software Foundation. All Rights Reserved.