org.apache.pdfbox.multipdf

## Class LayerUtility

- java.lang.Object
- - org.apache.pdfbox.multipdf.LayerUtility

    public class LayerUtility
    extends Object

This class allows to import pages as Form XObjects into a document and use them to create layers (optional content groups). It should used only on loaded documents, not on generated documents because these can contain unfinished parts, e.g. font subsetting information.

### Constructor Summary

Constructors
Constructor and Description
`LayerUtility(PDDocument targetDoc)` Creates a new instance.

### Method Summary

All Methods Instance Methods Concrete Methods
`PDOptionalContentGroup` `appendFormAsLayer(PDPage targetPage, PDFormXObject form, AffineTransform transform, String layerName)` Places the given form over the existing content of the indicated page (like an overlay).
`PDDocument` `getDocument()` Returns the PDF document we work on.
`PDFormXObject` `importPageAsForm(PDDocument sourceDoc, int pageNumber)` Imports a page from some PDF file as a Form XObject so it can be placed on another page in the target document.
`PDFormXObject` `importPageAsForm(PDDocument sourceDoc, PDPage page)` Imports a page from some PDF file as a Form XObject so it can be placed on another page in the target document.
`void` `wrapInSaveRestore(PDPage page)` Some applications may not wrap their page content in a save/restore (q/Q) pair which can lead to problems with coordinate system transformations when content is appended.

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

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

### Constructor Detail

#### LayerUtility

    public LayerUtility(PDDocument targetDoc)

Creates a new instance.

Parameters:
  `targetDoc` - the PDF document to modify

### Method Detail

#### getDocument

    public PDDocument getDocument()

Returns the PDF document we work on.

Returns:
  the PDF document

#### wrapInSaveRestore

    public void wrapInSaveRestore(PDPage page)
                           throws IOException

Some applications may not wrap their page content in a save/restore (q/Q) pair which can lead to problems with coordinate system transformations when content is appended. This method lets you add a q/Q pair around the existing page's content.

Parameters:
  `page` - the page
Throws:
  `IOException` - if an I/O error occurs

#### importPageAsForm

    public PDFormXObject importPageAsForm(PDDocument sourceDoc,
                                          int pageNumber)
                                   throws IOException

Imports a page from some PDF file as a Form XObject so it can be placed on another page in the target document.

You may want to call `wrapInSaveRestore(PDPage)` before invoking the Form XObject to make sure that the graphics state is reset.

Parameters:
  `sourceDoc` - the source PDF document that contains the page to be copied
  `pageNumber` - the 0-based page number of the page to be copied
Returns:
  a Form XObject containing the original page's content
Throws:
  `IOException` - if an I/O error occurs

#### importPageAsForm

    public PDFormXObject importPageAsForm(PDDocument sourceDoc,
                                          PDPage page)
                                   throws IOException

Imports a page from some PDF file as a Form XObject so it can be placed on another page in the target document.

You may want to call `wrapInSaveRestore(PDPage)` before invoking the Form XObject to make sure that the graphics state is reset.

Parameters:
  `sourceDoc` - the source PDF document that contains the page to be copied
  `page` - the page in the source PDF document to be copied
Returns:
  a Form XObject containing the original page's content
Throws:
  `IOException` - if an I/O error occurs

#### appendFormAsLayer

    public PDOptionalContentGroup appendFormAsLayer(PDPage targetPage,
                                                    PDFormXObject form,
                                                    AffineTransform transform,
                                                    String layerName)
                                             throws IOException

Places the given form over the existing content of the indicated page (like an overlay). The form is enveloped in a marked content section to indicate that it's part of an optional content group (OCG), here used as a layer. This optional group is returned and can be enabled and disabled through methods on `PDOptionalContentProperties`.

You may want to call `wrapInSaveRestore(PDPage)` before calling this method to make sure that the graphics state is reset.

Parameters:
  `targetPage` - the target page
  `form` - the form to place
  `transform` - the transformation matrix that controls the placement of your form. You'll need this if your page has a crop box different than the media box, or if these have negative coordinates, or if you want to scale or adjust your form.
  `layerName` - the name for the layer/OCG to produce
Returns:
  the optional content group that was generated for the form usage
Throws:
  `IOException` - if an I/O error occurs