Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.faceless.pdf2
Class PDF

    java.lang.Object
      org.faceless.pdf2.PDF

All Implemented Interfaces:
  Cloneable

    public class PDF

extends Object

A `PDF` describes a single document in Adobe's Portable Document Format. It is the highest-level object in the package.

The life-cycle of a PDF generally consists of being created, adding new pages, optionally adding information about the document structure (e.g. bookmarks), and finally rendering to an `OutputStream`.

This class only deals with the structure of the document. To actually create some content see the `PDFPage` class.

Here's the ubiquitous example:

       import org.faceless.pdf2.*;

       // Create a new PDF
       PDF p = new PDF();

       // Create a new page
       PDFPage page = p.newPage(PDF.PAGESIZE_A4);

       // Create a new "style" to write in - Black 24pt Times Roman.
       PDFStyle mystyle = new PDFStyle();
       mystyle.setFont(new StandardFont(StandardFont.TIMES), 24);
       mystyle.setFillColor(java.awt.Color.black);

       // Put something on the page
       page.setStyle(mystyle);
       page.drawText("Hello, PDF-viewing World!", 100, 100);

       // Automatically go to this page when the document is opened.
       p.setAction(Event.OPEN, PDFAction.goTo(page));

       // Add some document info
       p.setInfo("Author", "Joe Bloggs");
       p.setInfo("Title", "My Document");

       // Add a bookmark
       java.util.List bookmarks = p.getBookmarks();
       bookmarks.add(new PDFBookmark("Hello World page", PDFAction.goTo(page)));

       // Write the document to a file
       OutputStream out = new FileOutputStream("test.pdf");
       p.render(out);
       out.close();

Since:
  1.0
See Also:
  `PDFPage`, `PDFReader`

Field Summary
`static String` | `PAGESIZE_A4` A parameter to `newPage(String)` to create a new A4 page - 210x297mm
`static String` | `PAGESIZE_A4_LANDSCAPE` A parameter to `newPage(String)` to create a new landscape A4 page - 297x210mm
`static String` | `PAGESIZE_A5` A parameter to `newPage(String)` to create a new A5 page - 148x210mm
`static String` | `PAGESIZE_A5_LANDSCAPE` A parameter to `newPage(String)` to create a new landscape A5 page - 210x148mm
`static String` | `PAGESIZE_LETTER` A parameter to `newPage(String)` to create a new US Letter page - 8.5x11in
`static String` | `PAGESIZE_LETTER_LANDSCAPE` A parameter to `newPage(String)` to create a new landscape US Letter page - 11x8.5in
`static String` | `VERSION` This variable contains the version number of the current build.

Constructor Summary
`PDF()` Create a new, empty PDF document
`PDF(PDF pdf)` Create a PDF that's a clone of the specified PDF.
`PDF(PDFReader reader)` Create a PDF from the specified `PDFReader`.
`PDF(PDFReader reader, int revision)` Create a PDF from the specified `PDFReader`, using the specified revision of the document.

Method Summary
`void` | `addPropertyChangeListener(PropertyChangeListener listener)` Add a `PropertyChangeListener` to this object
`void` | `close()` Close any file resources the PDF may be holding on to.
`PDFAction` | `getAction(Event event)` Return the action that's performed when the specified event occurs on the document, as set by `setAction`.
`OutputProfile` | `getBasicOutputProfile()` Return a basic OutputProfile for this PDF.
`List` | `getBookmarks()` Return the List of bookmarks at the top level of the document.
`String` | `getDocumentID(boolean primary)` Returns a String representing this documents unique ID.
`Map` | `getEmbeddedFiles()` Return a Map containing all the Embedded Files associated with this document.
`EncryptionHandler` | `getEncryptionHandler()` Return the `EncryptionHandler` used to encrypt the document, or `null` if no encryption handler is in use.
`Form` | `getForm()` Return the Interactive `Form` or "AcroForm" object which is part of each PDF document.
`OutputProfile` | `getFullOutputProfile()` Return a full OutputProfile for this PDF.
`Map` | `getInfo()` Return the PDF meta information, as set by `setInfo()`.
`String` | `getInfo(String key)` Return document meta data as set by `setInfo()` as a String.
`String` | `getJavaScript()` Return the document-wide JavaScript, as set by `setJavaScript(java.lang.String)`, or `null` if no JavaScript is defined for this document.
`PDFPage` | `getLastPage()` Return the last page of this PDF.
`Locale` | `getLocale()` Return the PDF's Locale, as set by `setLocale` or (since 2.6.1) as loaded from the PDFs "Lang" tag.
`Reader` | `getMetaData()` Return any XML metadata associated with the document.
`Map` | `getNamedActions()` Return a Map containing all the named actions in the PDF.
`int` | `getNumberOfPages()` Return the number of pages in this PDF.
`int` | `getNumberOfRevisions()` Return the number of revisions made to the document.
`Object` | `getOption(String key)` Returns the current value of an option, as set by `setOption()`.
`PDFPage` | `getPage(int pagenumber)` Return the specified page.
`PDFPage` | `getPage(String name)` Get a "Named Page" from the PDF.
`String` | `getPageLabel(int num)` Get the "Page Label" for the specified page number, or null if none is specified.
`List` | `getPages()` Returns a List of the documents pages which may be manipulated to reorder, delete or append pages to the document.
`int` | `getPDFVersion()` Get the version of the PDF.
`static PropertyManager` | `getPropertyManager()` Get the `PropertyManager` currently being used by the PDF library
`float` | `getRenderProgress()` Get the progress of the `render()` method running in a different thread.
`boolean` | `getViewerPreference(String key)` Deprecated. since 2.7.6 replaced by the `setOption()` method - the key is the same as is passed in to this method but with a prefix of `view.`, eg. `FullScreen` becomes `view.FullScreen`.
`void` | `importFDF(FDF fdf)` Import the contents of the specified `FDF` into the PDF document.
`static boolean` | `isLicensed()` Return true if the PDF is licensed, false if it's running as a demo
`PDFPage` | `newPage(int w, int h)` Create a new `PDFPage` object of the specified size and add it to this PDF.
`PDFPage` | `newPage(PDFPage page)` Create a new `PDFPage` object that is a clone of the specified page, and add it to this PDF.
`PDFPage` | `newPage(String pagesize)` Create a new page of the specified page size and add it to this PDF.
`void` | `removePropertyChangeListener(PropertyChangeListener listener)` Remove a `PropertyChangeListener` to this object
`void` | `render(OutputStream out)` This method renders the completed PDF to an `OutputStream`.
`void` | `setAction(Event event, PDFAction action)` Specify an action to perform when the specified event occurs on the document.
`static void` | `setCache(Cache cache)` Set the `Cache` to be used by the library.
`void` | `setEncryptionHandler(EncryptionHandler encrypt)` Set the `EncryptionHandler` to encrypt this document with.
`void` | `setInfo(String key, Object val)` Set an item of PDF meta-information, such as author or title.
`void` | `setJavaScript(String javascript)` Set the document-wide JavaScript.
`void` | `setLayout(String layout, String mode)` Deprecated. since 2.7.6 this method has been replaced with the "pagelayout" and "pagemode" keys to the `setOption()` method.
`static void` | `setLicenseKey(String key)` Set the license key for the library.
`void` | `setLocale(Locale locale)` Set the default locale for this document.
`void` | `setMetaData(String xmldata)` Set the XMP Metadata associated with this document.
`void` | `setOption(String key, Object value)` Set various options and on the PDF, which largely (but not necessarily) follows the options available in the "Document Properties" dialog of Acrobat.
`void` | `setOutputProfile(OutputProfile targetprofile)` Set the Output Profile to use when rendering this PDF document.
`void` | `setPageLabel(int startpage, int displaystart, String prefix, char type)` Set the "Page Label" for a range of pages in the PDF - the way the page number is presented.
`static void` | `setPropertyManager(PropertyManager manager)` Set the `PropertyManager` to be used by the PDF library
`void` | `setViewerPreference(String key, boolean val)` Deprecated. since 2.7.6 this method has been replaced with the `setOption()` method - they key is the same but with a prefix of `view.`, eg. `view.fitWindow`.
`String` | `toString()`

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### VERSION

    public static final String VERSION

  This variable contains the version number of the current build. A typical values would be "2.0". Please be sure to include this information with any bug reports

### PAGESIZE_A4

    public static final String PAGESIZE_A4

  A parameter to `newPage(String)` to create a new A4 page - 210x297mm

  See Also:
    Constant Field Values

### PAGESIZE_A4_LANDSCAPE

    public static final String PAGESIZE_A4_LANDSCAPE

  A parameter to `newPage(String)` to create a new landscape A4 page - 297x210mm

  See Also:
    Constant Field Values

### PAGESIZE_LETTER

    public static final String PAGESIZE_LETTER

  A parameter to `newPage(String)` to create a new US Letter page - 8.5x11in

  See Also:
    Constant Field Values

### PAGESIZE_LETTER_LANDSCAPE

    public static final String PAGESIZE_LETTER_LANDSCAPE

  A parameter to `newPage(String)` to create a new landscape US Letter page - 11x8.5in

  See Also:
    Constant Field Values

### PAGESIZE_A5

    public static final String PAGESIZE_A5

  A parameter to `newPage(String)` to create a new A5 page - 148x210mm

  See Also:
    Constant Field Values

### PAGESIZE_A5_LANDSCAPE

    public static final String PAGESIZE_A5_LANDSCAPE

  A parameter to `newPage(String)` to create a new landscape A5 page - 210x148mm

  See Also:
    Constant Field Values

Constructor Detail

### PDF

    public PDF()

  Create a new, empty PDF document

  Since:
    1.0

### PDF

    public PDF(PDF pdf)

  Create a PDF that's a clone of the specified PDF. When creating multiple copies of a single PDF, it's much faster to use this method than to re-read the PDF using a new `PDFReader`

  Since:
    2.0

### PDF

    public PDF(PDFReader reader)

  Create a PDF from the specified `PDFReader`. The `PDFReader` class is available as part of the "Extended Edition" of the PDF library, and is included with this package. If the document contains multiple revisions, the latest revision is loaded.

  Since:
    1.1.12

### PDF

    public PDF(PDFReader reader,
               int revision)

  Create a PDF from the specified `PDFReader`, using the specified revision of the document. The `PDFReader` class is available as part of the "Extended Edition" of the PDF library, and is included with this package. The revision number must be between 1 and `PDFReader.getNumberOfRevisions()`, otherwise an `IllegalArgumentException` is thrown.

  Parameters:
    `reader` - the `PDFReader` to use
    `revision` - the revision number to use - between `PDFReader.getNumberOfRevisions()` to load the latest or 1 to load the original document.
  Throws:
    `IllegalArgumentException` - if the revision is outside the specified range
  Since:
    1.2.1

Method Detail

### isLicensed

    public static boolean isLicensed()

  Return true if the PDF is licensed, false if it's running as a demo

  Since:
    2.11.22

### setPropertyManager

    public static final void setPropertyManager(PropertyManager manager)

  Set the `PropertyManager` to be used by the PDF library

  Since:
    2.8.5

### getPropertyManager

    public static final PropertyManager getPropertyManager()

  Get the `PropertyManager` currently being used by the PDF library

  Since:
    2.8.5

### close

    public void close()

  Close any file resources the PDF may be holding on to. These will be automatically closed during garbage collection, but this method may be called earlier if necessary to speed disposal of those resources.

  Since:
    2.11.2 - prior to that no resources were held and this method wasn't necessary

### getPDFVersion

    public int getPDFVersion()

  Get the version of the PDF. The version provides an indication of which version of Acrobat the file can be loaded in, although it is quite normal for a 1.4 document to be loaded correctly by a 1.3 viewer (for example). Since Acrobat 9 and ISO 32000, version numbering has become more complicated, so to interpret the value from this method you will need the following table. Note the earliest version of PDF supported by this API is 1.3, so any documents from earlier revisions will be automatically upgraded.

  3 | PDF 1.3 (as created by Acrobat 4.x)
  4 | PDF 1.4 (as created by Acrobat 5.x)
  5 | PDF 1.5 (as created by Acrobat 6.x)
  6 | PDF 1.6 (as created by Acrobat 7.x)
  7 | PDF 1.7 / ISO 32000-1:2008 (as created by Acrobat 8.x)
  8 | PDF 1.7 / ISO 32000-1:2008 Extension Level 3 (as created by Acrobat 9.x)
  9 | PDF 1.7 / ISO 32000-1:2008 Extension Level 5 (as created by Acrobat 9.1)
  10 | PDF 1.7 / ISO 32000-1:2008 Extension Level 8 (as created by Acrobat X)
  11 | PDF 2.0 / ISO 32000-2:2012

  Returns:
    the version of the PDF document
  Since:
    2.0
  See Also:
    `setOutputProfile(org.faceless.pdf2.OutputProfile)`

### setOutputProfile

    public void setOutputProfile(OutputProfile targetprofile)

  Set the Output Profile to use when rendering this PDF document. Output Profiles allow you to limit the features used in a document to a specified subset - for example, Acrobat 4 compatible, PDF/X-1 compatible and so on. See the `OutputProfile` class for more information.

  Throws:
    `IllegalStateException` - if the current profile doesn't match and can't be altered to match the specified profile, or if the current profile isn't known (because it's an existing PDF document that hasn't been scanned with `getFullOutputProfile()`).
  Since:
    2.0
  See Also:
    `getPDFVersion()`, `getBasicOutputProfile()`, `getFullOutputProfile()`

### getBasicOutputProfile

    public OutputProfile getBasicOutputProfile()

  Return a basic OutputProfile for this PDF. The "Basic" profile consists of information which be easily determined without having to traverse the PDF or parse the page streams. It takes no time to run, and as it doesn't parse the page content it requires only the basic License to run. See the `OutputProfile.Feature` class to see which features are returned in the basic profile.

  Since:
    2.6.1

### getFullOutputProfile

    public OutputProfile getFullOutputProfile()

  Return a full OutputProfile for this PDF. This routine parses the entire document to determine it's contents - this can be a very lengthy operation, so calling the `getBasicOutputProfile()` method is generally prefereable unless the `Feature` you're querying is not tested by that method.

  This method cycles through every object in the PDF structure in a process very similar to rendering the entire PDF to a bitmap, and updates the OutputProfile returned by `getBasicOutputProfile()` with the complete list of features used in this PDF - which may cause an `IllegalStateException` if it's set to something other than `OutputProfile.Default`.

  This method requires an "Extended Edition plus Viewer" license to run.

  Since:
    2.6.1

### getNumberOfRevisions

    public int getNumberOfRevisions()

  Return the number of revisions made to the document. This will only be useful for documents read in using a `PDFReader` - all other PDFs will return zero. See the `PDFReader` class for more information on revisions.

  Note that in 2.7 the return value of this method was modified slightly so that the original version of a PDF is revision 1, not revision 0. New documents created with this library will still have a revision 0 before they're saved.

  Since:
    1.2.1
  See Also:
    `PDFReader`, `FormSignature.getNumberOfRevisionsCovered()`

### newPage

    public PDFPage newPage(String pagesize)

  Create a new page of the specified page size and add it to this PDF. The page 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 `PAGESIZE_A4`, `PAGESIZE_A4_LANDSCAPE`, `PAGESIZE_LETTER`, `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.

  This method is identical to calling:

         PDFPage page = new PDFPage(pagesize);
         pdf.getPages().add(page);

  Parameters:
    `pagesize` - the size of the page to create
  Throws:
    `IllegalArgumentException` - if the specified page size cannot be parsed

### newPage

    public PDFPage newPage(int w,
                           int h)

  Create a new `PDFPage` object of the specified size and add it to this PDF. The size is specified in points. This method is identical to calling:

         PDFPage page = new PDFPage(w, h);
         pdf.getPages().add(page);

  The arguments are integers for API compatibilty reasons only. If required you can create pages sized to a fraction of a point using the `newPage(String)` method.

  Parameters:
    `w` - the width of the page, in points
    `h` - the height of the page, in points
  Returns:
    a new `PDFPage` object
  Since:
    1.0
  See Also:
    `getPages()`

### newPage

    public PDFPage newPage(PDFPage page)

  Create a new `PDFPage` object that is a clone of the specified page, and add it to this PDF. This method is identical to calling:

         PDFPage page = new PDFPage(originalpage);
         pdf.getPages().add(page);

  Parameters:
    `page` - the PDFPage object to clone
  Returns:
    a new `PDFPage` object which is a clone of the specified page
  Since:
    2.0
  See Also:
    `getPages()`

### getPages

    public List getPages()

  Returns a List of the documents pages which may be manipulated to reorder, delete or append pages to the document. This is done using the standard `List` methods. For example, to reverse the pages in the document, you could do something like this:

         List pages = pdf.getPages();
         List temp = new ArrayList(pages);
         pages.clear();
         for (int i=temp.size()-1;i>=0;i--) {
            pages.add(temp.get(i));
         }

  or to move (not copy) all the pages from one PDF to another, try

         pdf1.getPages().addAll(pdf2.getPages());

  Since:
    1.1.12

### getNumberOfPages

    public int getNumberOfPages()

  Return the number of pages in this PDF. Identical to `pdf.getPages().size()`

  Returns:
    the number of pages in the document
  Since:
    1.1
  See Also:
    `getPages()`

### getPage

    public PDFPage getPage(int pagenumber)

  Return the specified page. Identical to `pdf.getPages().get(pagenumber)`

  Parameters:
    `pagenumber` - the page number, between 0 and `getNumberOfPages()`-1
  Returns:
    the specified page
  Throws:
    `ArrayIndexOutOfBoundsException` - if the page number is not in range
  Since:
    1.1
  See Also:
    `getPages()`

### getPage

    public PDFPage getPage(String name)

  Get a "Named Page" from the PDF. If a Template with the specified name is found in the PDF it will be returned, and may be cloned via the `PDFPage.PDFPage(PDFPage)` constructor.

  Since:
    2.10.5

### getLastPage

    public PDFPage getLastPage()

  Return the last page of this PDF. Identical to `pdf.getPage(pdf.getNumberOfPages()-1)`

  Since:
    1.0
  See Also:
    `getPages()`

### setEncryptionHandler

    public void setEncryptionHandler(EncryptionHandler encrypt)

  Set the `EncryptionHandler` to encrypt this document with. This method allows you to limit access to the document, either by requiring a password to open it, preventing the document from being printed and so on, or more.

  Changing encryption will destroy any digital signatures in the document, which is why Acrobat won't allow you to do lt. Prior to version 2.4, this library didn't preserve previously applied signatures when writing a file, so this wasn't an issue - a warning was displayed and the signature was removed. Now, however, signatures can be preserved, and this method will throw an `IllegalStateException` if called on a previously signed document. This will also occur if the encryption settings (like password, permission flags etc.) are changed. If you want to re-encrypt a signed document, you have to delete any existing signatures first.

  Parameters:
    `encrypt` - the EncryptionHandler to be used to encrypt and limit access to the document
  Since:
    2.0
  See Also:
    `EncryptionHandler`, `StandardEncryptionHandler`

### getEncryptionHandler

    public EncryptionHandler getEncryptionHandler()

  Return the `EncryptionHandler` used to encrypt the document, or `null` if no encryption handler is in use.

  Since:
    2.0
  See Also:
    `EncryptionHandler`, `StandardEncryptionHandler`

### setInfo

    public void setInfo(String key,
                        Object val)

  Set an item of PDF meta-information, such as author or title. Prior to version 2.6.2 this method only updated the original "Info" dictionary, used by PDFs since the early days to store metadata. Since 2.6.2 this method can now be used to update both the original Info dictionary and the XMP Metadata.

  Most people won't need to worry about the details. To set the metadata in the PDF, just specify an appropriate key to set the Title, Author etc. of the document. The list of known keys is below, although any key can be used - if it's not on the list it will appear in the "Custom" pane in Acrobat's "Document Properties" window.

  Title | The document's title. This value must be set for PDF/X documents
  Author | The name of the person who created the document.
  Subject | The subject of the document.
  Keywords | Comma separated list of keywords associated with the document.
  Creator | If the document was converted to PDF from another format, the name of the application that created the original document from which it was converted.
  Trapped | The document's trapping status. Must be "True", "False" or "Unknown". This has to be set to "True" or "False" for PDF/X documents

  Note that "Producer", "CreationDate" and "ModDate" are set by the library internally and cannot be changed.

  Since 2.6.2, updating one of the fields listed above will also update the XMP metadata to match. It's also possible to update fields in the XMP metadata that aren't listed above. This can be done be specifying the key name as `xmp:ns:attribute`, where ns is the recommended namespace prefix (as specified in the XMP specification) and attribute is the attribute to set. For instance, to set the "rights" attribute in the Dublin Core schema, you could call `setInfo("xmp:dc:rights", "Copyright (C) Whoever");`.

  No validation is done on these fields or the data, although fields listed as bags, sequences or language alternates in the XMP specificaiton will be automatically wrapped in the appropriate structure. If more complex fields need to be set then the `setMetaData(java.lang.String)` method can be used to pass in an entire RDF object.

  The `value` parameter may be `String`, `Date`, `Boolean` or `Float`, or `null` to remove that item of meta-information.

  Parameters:
    `key` - the meta-information field to set
    `val` - the value to set it to - a `String`, `Date`, `Boolean`, `Float` or `null`
  Since:
    1.0

### getInfo

    public String getInfo(String key)

  Return document meta data as set by `setInfo()` as a String. If the key name begins with `xmp:` then the appropriate field will be extracted from the XMP metadata stream - see the `setInfo` for more information

  For example, to get the author of the document from the PDF Info dictionary:

      String author = pdf.getInfo("Author");

  and to extract the "rights" attribute of the Dublin Core Schema from the XMP metadata:

      String copyright = pdf.getInfo("xmp:dc:rights");

  If a type of object requested from the XMP metadata cannot obviosuly be turned into a String, the value returned from this method is undefined.

  Parameters:
    `key` - the field to get
  Returns:
    the value of the specified field, or `null` if the field is not set
  Since:
    1.0

### getInfo

    public Map getInfo()

  Return the PDF meta information, as set by `setInfo()`. This is in the form of an unmodifable `Map`, where the keys are `String` objects, and values may be `String`, `Date`, `Boolean`, `Calendar` or `Float` objects. If no meta information is available, returns an empty Map.

  Since version 2.1.2, any keys representing Dates (such as "ModDate" or "CreationDate") will also have an equivalent entry with a leading underscore, eg. "_ModDate". These give the same information but as a `Calendar` rather than a `Date`. This is to allow extraction of TimeZone information, sadly lacking from the `Date` class.

  Note this map doesn't include any of the XMP metadata - only data from the original Info dictionary.

  Returns:
    an unmodifiable Map containing any meta information specified in the document.
  Since:
    1.1.12

### setLocale

    public void setLocale(Locale locale)

  Set the default locale for this document. This is mainly useful in right-to-left locales like arabic, as it sets the default text alignment. The locale may be set and reset as many times as required. The locale in use when the document is rendered is considered to be the locale of the document as a whole.

  Since:
    1.1

### getLocale

    public Locale getLocale()

  Return the PDF's Locale, as set by `setLocale` or (since 2.6.1) as loaded from the PDFs "Lang" tag. If no locale is specified this method returns `null`.

  Since:
    1.1

### setAction

    public void setAction(Event event,
                          PDFAction action)

  Specify an action to perform when the specified event occurs on the document. Valid events are `Event.OPEN` and `Event.CLOSE`, which occur within every version Acrobat, and `Event.PRE_SAVE`, `Event.POST_SAVE`, `Event.PRE_PRINT` and `Event.POST_PRINT`, which only occur in Acrobat 5.0 or newer viewers.

  Parameters:
    `event` - the event on which to perform the action
    `action` - the action to perform, or `null` to remove any current action
  Since:
    2.0

### getAction

    public PDFAction getAction(Event event)

  Return the action that's performed when the specified event occurs on the document, as set by `setAction`. If no action is specified for that event, return `null`

  Since:
    2.0

### setJavaScript

    public void setJavaScript(String javascript)

  Set the document-wide JavaScript. This JavaScript is executed when the document is first loaded - this is normally used to define functions and the like, in the same way as JavaScript defined in the `<HEAD>` of an HTML document.

  Parameters:
    `javascript` - the JavaScript to use for the entire document
  Since:
    1.1.23
  See Also:
    `getJavaScript()`, `PDFAction.formJavaScript(java.lang.String)`

### getJavaScript

    public String getJavaScript()

  Return the document-wide JavaScript, as set by `setJavaScript(java.lang.String)`, or `null` if no JavaScript is defined for this document.

  Since:
    1.1.23
  See Also:
    `setJavaScript(java.lang.String)`, `PDFAction.formJavaScript(java.lang.String)`

### getNamedActions

    public Map getNamedActions()

  Return a Map containing all the named actions in the PDF. Named actions (which must always be "GoTo" type actions) can be referenced from outside the PDF, which allows the document to be opened at a specific location. Here's how to do this:

  In the PDF, add the following code:

         pdf.getNamedActions().put("Myaction", PDFAction.goTo(somepage));

  Then in your HTML document, add the following code:

         <a href="http://www.mycompany.com/mypdf.pdf#Myaction">

  The Map returned from this method can be manipulated using the normal `Map` methods to add or delete actions. The only restrictions is that keys must always be `String` objects and values must always be `PDFAction` objects that jump to a location in the document, like those returned from one of the `PDFAction.goTo...` methods.

  Since:
    1.1.12

### getEmbeddedFiles

    public Map getEmbeddedFiles()

  Return a Map containing all the Embedded Files associated with this document. Note this method does not return files embedded by way of a `AnnotationFile` method - they must be accessed via that class in the usual way.

  The Map returned from this method can be manipulated using the normal `Map` methods to add or delete actions. The only restrictions is that keys must always be `String` objects and values must always be `EmbeddedFile` objects. As with any map, the keys must be unique - we recommend adding files using their filenames as keys, like so:

        EmbeddedFile file = new EmbeddedFile(new File("Attachment.txt"));
        pdf.getEmbeddedFiles().put(file.getName(), file);

  Since:
    2.6

### setMetaData

    public void setMetaData(String xmldata)

  Set the XMP Metadata associated with this document. This is a PDF1.4 feature, so it will only be used by Acrobat 5.0 or later and will be ignored by earlier viewers.

  Since 2.6.2 the XMP Metadata is updated by `setInfo()`, but this method still has a role to play when more control over the RDF object is required. The data passed into this method is now parsed and used to update the Info dictionary so the two sources of Metadata are kept in sync. If the XMP data supplied to this method cannot be parsed, a warning will be displayed.

  The value is specified as a String, but as it's XML it will probably be created as a `java.io.Writer`. Here's an example showing how to use this with SAX and the `org.apache.xml.serialize` classes. The lines marked in bold could apply to any method of serializing the XML.

         void addMetaData(PDF pdf, InputSource source)
         {
             // Create a java.io.Writer
             StringWriter meta = new StringWriter();

             // Create a SAX XML serializer using the apache classes
             // We must not include the XML Declaration in the output.
             OutputFormat outformat = new OutputFormat();
             outformat.setOmitXMLDeclaration(true);
             Serializer serial = new XMLSerializer(out, outformat);

             // Create the XML parser and parse the input source
             XMLReader parser = XMLReaderFactory.createXMLReader();
             parser.setContentHandler(serial.asContentHandler());
             parser.parse(inputsource);

             pdf.setMetaData(meta.toString());
         }

  For more information on XML metadata in PDF documents, see http://www.adobe.com/products/xmp

  Parameters:
    `xmldata` - the XML data to embed into the document, or `null` to remove it.
  Since:
    1.1.12

### getMetaData

    public Reader getMetaData()
                       throws IOException

  Return any XML metadata associated with the document. XML Metadata is a PDF 1.4 (Acrobat 5.x) feature, so this method will return `null` for all PDF1.3 or earlier documents, or if no metadata is specified.

  Since 2.6.2 the XMP metadata can be updated by the `setInfo()` method, but to remain consistent with earlier versions this method will return the XMP object from the PDF as it was loaded, or from when it was last updated with `setMetaData()`.

  Here's an example of how to extract the metadata into a DOM tree. Lines in bold could apply to any parsing method.

         InputSource source = new InputSource(pdf.getMetaData());
         DOMParser parser = new DOMParser();
         parser.parse(source);
         Document doc = parser.getDocument();

  For more information on XML metadata in PDF documents, see http://www.adobe.com/products/xmp

  Returns:
    a `Reader` containing the source of the XML
  Throws:
    `IOException`
  Since:
    1.1.12

### setLayout

    public void setLayout(String layout,
                          String mode)

  Deprecated. since 2.7.6 this method has been replaced with the "pagelayout" and "pagemode" keys to the `setOption()` method.

  Controls how the document is initially laid out in the PDF viewer.

  Since:
    2.0

### setViewerPreference

    public void setViewerPreference(String key,
                                    boolean val)

  Deprecated. since 2.7.6 this method has been replaced with the `setOption()` method - they key is the same but with a prefix of `view.`, eg. `view.fitWindow`.

  Set some preferences as to how the document is displayed on screen.

  Since:
    1.1.12

### getViewerPreference

    public boolean getViewerPreference(String key)

  Deprecated. since 2.7.6 replaced by the `setOption()` method - the key is the same as is passed in to this method but with a prefix of `view.`, eg. `FullScreen` becomes `view.FullScreen`.

  Return the value of the specified viewer preference, as set by `setViewerPreference`.

  Parameters:
    `key` - the option to query
  Returns:
    whether the specified viewer preference is set
  Since:
    1.1.12

### setOption

    public void setOption(String key,
                          Object value)

  Set various options and on the PDF, which largely (but not necessarily) follows the options available in the "Document Properties" dialog of Acrobat. The key is a case-insensitive String and the value is an object - it may be `String`, `Boolean`, `Integer` or some other type.

  Passing in an unrecognised key or an invalid value as a parameter will not throw an exception, but will simply have no effect. The list of currently supported options is below.

  view.fullscreen | boolean | Open the document in full-screen mode
  view.displayDocTitle | boolean | The window's title bar should display the document title taken from the the `Title` entry of the `getInfo()` map. If false the title bar should display the filename instead (only works in Acrobat 5 and later)
  view.hideToolBar | boolean | Hide the viewer application's tool bars when the document is active
  view.hideMenuBar | boolean | Hide the viewer application's menu bar when the document is active
  view.hideWindowUI | boolean | Hide user interface elements in the Document window (such as scroll bars and navigation controls), leaving only the document's contents displayed
  view.fitWindow | boolean | Resize the document's window to fit the size of the first displayed page. Note this resizes the window to fit the document, not the other way round
  view.centerWindow | boolean | Position the document's window in the center of the screen. Note this moves the whole viewer to the center of the screen, not the document to the center of the viewer
  pagelayout | string | How pages are displayed in the main Acrobat window pane. Values are typically `SinglePage` (the default), `OneColumn` ("Single Page Continuous" in Acrobat 8), `TwoColumnLeft` ("Two-Up Continuous (Facing)" in Acrobat 8), `TwoColumnRight` ("Two-Up Continuous (Cover Page)" in Acrobat 8), `TwoPageLeft` ("Two-Up (Facing)" in Acrobat 8) or `TwoPageRight` ("Two-Up (Cover Page)" in Acrobat 8). Other values are possibile but won't be recognised by Acrobat
  pagemode | string | What to display in the left-most pane of the Acrobat window. Values are typically `UseNone` (the default), which prevents the left-pane from being displayed, or `UseOutlines` to display Bookmarks, `UseThumbs` to display the Page Thumbnails, `UseOC` to show the Layers tab or `UseAttachments` to show the Attachments tab. The value "UseSignatures" can also be used to set the initial panel to the Signature panel in the BFO PDF Viewer, although this value has no effect in Acrobat
  view.area | string | Which page box to display when viewing the document on screen. One of `CropBox` (the default), `MediaBox`, `TrimBox`, `BleedBox` or `ArtBox`. Typically this setting is best left unchanged
  view.clip | string | Which page box to clip the page contents to when viewing the document on screen. One of `CropBox` (the default), `MediaBox`, `TrimBox`, `BleedBox` or `ArtBox`. Typically this setting is best left unchanged
  print.area | string | Which page box to display when printing the document. One of `CropBox` (the default), `MediaBox`, `TrimBox`, `BleedBox` or `ArtBox`. Typically this setting is best left unchanged
  print.clip | string | Which page box to clip the page contents to when printing the document. One of `CropBox` (the default), `MediaBox`, `TrimBox`, `BleedBox` or `ArtBox`. Typically this setting is best left unchanged
  print.scaling | string | How to scale the document when printed. One of `AppDefault` (which uses the application defaults) or `None` (for no scaling). Some non-standard values are also recognized by our viewer, including `Fit` (scale the page up or down to fit the printable area, preserving the aspect ratio), `FitUnlocked` (as before but don't preserve the aspect ratio), `ShrinkToFit` and `ShrinkToFitUnlocked` (as for Fit and FitUnlocked, but only scale down to fit on the page, not up).
  print.duplex | string | What to set the print duplex settings to in the Acrobat Print Dialog. One of `Simplex` (the default), `DuplexFlipLongEdge` to duplex print on the long edge, or `DuplexFlipShortEdge` to duplex print on the short edge.
  print.matchtraysize | string | Whether to attempt to match the paper source to the page size.
  print.numcopies | integer | The number of copies to set in the print dialog, from 1 to 5.
  print.pagerange | List | Which pages to set as the default pages to print in the Print dialog. Specified as a `java.util.List` containing PDFPage objects.
  bfo.printasimage | List | Force the PDF to be printed as an image when printing with the BFO API only. This option may rarely be needed to print some documents correctly on some JVMs. It will be ignored by non-BFO applications

  Parameters:
    `key` - a case-insensitive key determining the option to set - may not be null
    `value` - the value to set that key to. The type depends on the key, but in general a value of null means the default.
  Since:
    2.7.6

### getOption

    public Object getOption(String key)

  Returns the current value of an option, as set by `setOption()`. If the value for that key is set to it's default, this method will return `null`.

  Parameters:
    `key` - a case-insensitive key determining the option to set - may not be null
  Since:
    2.7.6

### getBookmarks

    public List getBookmarks()

  Return the List of bookmarks at the top level of the document. The `List` contains zero or more `PDFBookmark` objects, and can be altered using any of the standard `List` methods to order the documents bookmarks in any way you see fit. New documents start with an empty list.

  Returns:
    the List of bookmarks at the top level of the document
  Since:
    1.0
  See Also:
    `PDFBookmark`

### getDocumentID

    public String getDocumentID(boolean primary)

  Returns a String representing this documents unique ID. The PDF specification recommends (but not requires) that every document is given a unique ID when it's created which is stored in two parts. The primary ID stays constant throughout the life of the document, the secondary should be updated on every revision - although in the first revision of a document they should be the same. So when comparing the IDs of two documents, if the primary and secondary both match you've found the same document, and when only the primary ID matches you've found a different version of the same document.

  This method return either the primary or secondary ID, depending on whether the `primary` parameter is `true` or `false`. The ID is generally just random characters.

  Calling this method before the document is created (ie when you've just created a new PDF but not called `render()`) will result in this method returning `null`. It may also return `null` for PDFs that do not have an ID specified, although they are fairly rare these days.

  Although the IDs are stored internally as 16 bytes, we return a String of 32 hex-characters to make them easier to display and compare.

  Parameters:
    `primary` - whether to return the primary or secondary ID
  Returns:
    a 32-character String representing the ID, or `null` if no ID is set
  Since:
    2.1.2

### getForm

    public Form getForm()

  Return the Interactive `Form` or "AcroForm" object which is part of each PDF document. Note that using interactive forms requires the "Extended Edition" of the library - although the classes are supplied with the package an "Extended Edition" license must be purchased to activate this functionality.

  Returns:
    the documents AcroForm
  Since:
    1.1.13

### importFDF

    public void importFDF(FDF fdf)

  Import the contents of the specified `FDF` into the PDF document. Any form values specified in the FDF file will be used to set the corresponding form fields in the PDF, and since 2.2.2 any annotations in the FDF will be imported as well. If a field doesn't exist, a warning is printed and the field is ignored.

  Note that since 2.11.18 any JavaScript on the FDF will be imported as well, and this may involve executing JavaScript with the permissions of the PDF class. See the `FDF.willExecuteJavaScript()` method and the `FDF.setJavaScript(java.lang.String, java.lang.String)` method to disable this.

  Since:
    1.2.1

### render

    public void render(OutputStream out)
                throws IOException

  This method renders the completed PDF to an `OutputStream`. The stream is left open on completion. A document may be rendered more than once.

  Rendering the document typically merges all the revisions of a document, so after rendering the `getNumberOfRevisions()` method will always return zero. The exception to this is documents containing an existing digital signature, or documents with an `OutputProfile` requiring the `OutputProfile.Feature.MultipleRevisions` feature; there is a very specific technical case where this may be necessary, see the API docs on that class for more information.

  Parameters:
    `out` - the output stream to write the PDF to
  Throws:
    `IOException` - if the process could not be completed
  Since:
    1.0

### getRenderProgress

    public float getRenderProgress()

  Get the progress of the `render()` method running in a different thread. The returned value will start at 0 and move towards 1 as the render progresses.

  Since:
    2.8

### addPropertyChangeListener

    public void addPropertyChangeListener(PropertyChangeListener listener)

  Add a `PropertyChangeListener` to this object

  Since:
    2.11.19

### removePropertyChangeListener

    public void removePropertyChangeListener(PropertyChangeListener listener)

  Remove a `PropertyChangeListener` to this object

  Since:
    2.11.19

### setCache

    public static void setCache(Cache cache)

  Set the `Cache` to be used by the library. Note this is a static, method, which means a single cache is used for all PDFs. This also means you do not need to call this method more than once, and doing so is not only inefficient, it could theoretically cause problems in multi-threaded environments like servlet engines. To repeat - if you are going to call this method, do it once in an initialization routine before the first PDF is created.

  Since:
    2.2.2

### setPageLabel

    public void setPageLabel(int startpage,
                             int displaystart,
                             String prefix,
                             char type)

  Set the "Page Label" for a range of pages in the PDF - the way the page number is presented. Calling the method will set the format for all pages from the specified `startpage` to the end of the document, so if multiple formats are required they should be set in ascending order.

  For example, to set the first 4 pages to i, ii, iii, iv and then number normally from 1, call:

       pdf.setPageLabel(0, 1, null, 'r');  // Number all pages in roman starting from 1
       pdf.setPageLabel(4, 1, null, 'D');  // Number from 4th page in decimal starting from 1

  To reset the page labels the the default, call `setPageLabel(0, 1, null, 'D')`. This will number all pages as decimal numbers starting from 1.

  Parameters:
    `startpage` - the first page in the PDF to format with this label, starting from 0
    `displaystart` - the number to give the page specified by startpage - subsequent pages will be numbered sequentially from this value. Minimum value is 1
    `type` - one of 'D' for decimal, 'R' for upper-case roman, 'r' for lower-case roman, 'A' for upper-case letters, 'a' for lower-case letters or 'x' for no numbering - in this case just the prefix will be used.
    `prefix` - the prefix to give to the page labels, or null for no prefix
  Since:
    2.11.19

### getPageLabel

    public String getPageLabel(int num)

  Get the "Page Label" for the specified page number, or null if none is specified.

  Parameters:
    `num` - the page number to get the label for, starting with 0
  Since:
    2.11.19
  See Also:
    `setPageLabel(int, int, java.lang.String, char)`

### setLicenseKey

    public static void setLicenseKey(String key)

  Set the license key for the library. When the library is purchased, the Big Faceless Organization supplies a key which removes the "DEMO" stamp on each of the documents.

  Please note this method is static - it should be called BEFORE the first PDF is created, like so:

        PDF.setLicenseKey(.....);
        PDF pdf = new PDF();

  Parameters:
    `key` - the license key

### toString

    public String toString()

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2012 Big Faceless Organization