com.itextpdf.kernel.pdf

Class PdfPage

java.lang.Object

com.itextpdf.kernel.pdf.PdfObjectWrapper<PdfDictionary>

com.itextpdf.kernel.pdf.PdfPage

All Implemented Interfaces:

Serializable

public class PdfPage
extends PdfObjectWrapper<PdfDictionary>

See Also:

Serialized Form

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	PdfPage(PdfDictionary pdfObject)
protected	PdfPage(PdfDocument pdfDocument)
protected	PdfPage(PdfDocument pdfDocument, PageSize pageSize)

Method Summary

Modifier and Type	Method and Description
PdfPage	addAnnotation(int index, PdfAnnotation annotation, boolean tagAnnotation) Adds specified PdfAnnotation to specified index in annotations array with or without autotagging.
PdfPage	addAnnotation(PdfAnnotation annotation) Adds specified annotation to the end of annotations array and tagged it.
boolean	containsAnnotation(PdfAnnotation annotation) Checks if page contains the specified annotation.
PdfFormXObject	copyAsFormXObject(PdfDocument toDocument) Copies page as FormXObject to the specified document.
PdfPage	copyTo(PdfDocument toDocument) Copies page to the specified document.
PdfPage	copyTo(PdfDocument toDocument, IPdfPageExtraCopier copier) Copies page to the specified document.
void	flush() Flushes page and it's content stream.
void	flush(boolean flushResourcesContentStreams) Flushes page and its content stream.
List<PdfAnnotation>	getAnnotations() Gets array of annotation dictionaries that shall contain indirect references to all annotations associated with the page.
int	getAnnotsSize() Gets the number of PdfAnnotation associated with this page.
Rectangle	getArtBox() Gets the Rectangle object specified by page's ArtBox, that define the extent of the page’s meaningful content (including potential white space) as intended by the page’s creator.
Rectangle	getBleedBox() Gets the Rectangle object specified by page's BleedBox, that define the region to which the contents of the page shall be clipped when output in a production environment.
byte[]	getContentBytes() Get decoded bytes for the whole page content.
PdfStream	getContentStream(int index) Gets the content stream at specified 0-based index in the Contents object PdfArray.
int	getContentStreamCount() Gets the size of Contents object PdfArray.
Rectangle	getCropBox() Gets the Rectangle specified by page's CropBox, that defines the visible region of default user space.
PdfDocument	getDocument() Gets the PdfDocument that owns that page, or null if such document isn't exist.
PdfStream	getFirstContentStream() Returns the Contents object if it is PdfStream, or first stream in the array if it is PdfArray.
PdfStream	getLastContentStream() Returns the Contents object if it is PdfStream, or last stream in the array if it is PdfArray.
Rectangle	getMediaBox() Gets Rectangle object specified by page's Media Box, that defines the boundaries of the physical medium on which the page shall be displayed or printed
int	getNextMcid() Calculates and returns next available MCID reference.
List<PdfOutline>	getOutlines(boolean updateOutlines) This method gets outlines of a current page
Rectangle	getPageSize() Gets page size, defined by media box object.
Rectangle	getPageSizeWithRotation() Gets page size, considering page rotation.
PdfResources	getResources() Gets the PdfResources wrapper object for this page resources.
int	getRotation() Gets the number of degrees by which the page shall be rotated clockwise when displayed or printed.
byte[]	getStreamBytes(int index) Gets decoded bytes of a certain stream of a page content.
Integer	getStructParentIndex() Gets Integer key of the page’s entry in the structural parent tree.
PdfName	getTabOrder() Gets a name specifying the tab order that shall be used for annotations on the page.
Rectangle	getTrimBox() Gets the Rectangle object specified by page's TrimBox object, that define the intended dimensions of the finished page after trimming.
PdfStream	getXmpMetadata() Gets the XMP Metadata object.
boolean	isIgnorePageRotationForContent()
boolean	isPageRotationInverseMatrixWritten() This flag is meaningful for the case, when page rotation is applied and ignorePageRotationForContent is set to true.
protected boolean	isWrappedObjectMustBeIndirect() Defines if the object behind this wrapper must be an indirect object in the resultant document.
PdfStream	newContentStreamAfter() Creates new PdfStream object and puts it at the end of Contents array (if Contents object is PdfStream it will be replaced with one-element array).
PdfStream	newContentStreamBefore() Creates new PdfStream object and puts it at the beginning of Contents array (if Contents object is PdfStream it will be replaced with one-element array).
PdfPage	put(PdfName key, PdfObject value) Helper method that associate specified value with specified key in the underlined PdfDictionary.
PdfPage	removeAnnotation(PdfAnnotation annotation) Removes an annotation from the page.
PdfPage	setAdditionalAction(PdfName key, PdfAction action) Helper method to add an additional action to this page.
PdfPage	setArtBox(Rectangle rectangle) Sets the ArtBox object, that define the extent of the page’s meaningful content (including potential white space) as intended by the page’s creator.
PdfPage	setBleedBox(Rectangle rectangle) Sets the BleedBox object, that defines the region to which the contents of the page shall be clipped when output in a production environment.
PdfPage	setCropBox(Rectangle rectangle) Sets the CropBox object, that defines the visible region of default user space.
PdfPage	setIgnorePageRotationForContent(boolean ignorePageRotationForContent) If true - defines that in case the page has a rotation, then new content will be automatically rotated in the opposite direction.
PdfPage	setMediaBox(Rectangle rectangle) Sets the Media Box object, that defines the boundaries of the physical medium on which the page shall be displayed or printed.
PdfPage	setPageLabel(PageLabelNumberingStyleConstants numberingStyle, String labelPrefix) This method adds or replaces a page label.
PdfPage	setPageLabel(PageLabelNumberingStyleConstants numberingStyle, String labelPrefix, int firstPage) This method adds or replaces a page label.
void	setPageRotationInverseMatrixWritten() NOTE: For internal usage! Use this method only if you know what you are doing.
PdfPage	setResources(PdfResources pdfResources) Sets PdfResources object.
PdfPage	setRotation(int degAngle) Sets the page rotation.
PdfPage	setTabOrder(PdfName tabOrder) Sets a name specifying the tab order that shall be used for annotations on the page.
PdfPage	setTrimBox(Rectangle rectangle) Sets the TrimBox object, that define the intended dimensions of the finished page after trimming.
void	setXmpMetadata(byte[] xmpMetadata) Sets the XMP Metadata.
void	setXmpMetadata(XMPMeta xmpMeta) Serializes XMP Metadata to byte array and sets it.
void	setXmpMetadata(XMPMeta xmpMeta, SerializeOptions serializeOptions) Serializes XMP Metadata to byte array and sets it.

Methods inherited from class com.itextpdf.kernel.pdf.PdfObjectWrapper

ensureObjectIsAddedToDocument, ensureUnderlyingObjectHasIndirectReference, getPdfObject, isFlushed, makeIndirect, makeIndirect, markObjectAsIndirect, setForbidRelease, setModified, setPdfObject, unsetForbidRelease

Methods inherited from class java.lang.Object

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

Constructor Detail

PdfPage

protected PdfPage(PdfDictionary pdfObject)

PdfPage

protected PdfPage(PdfDocument pdfDocument,
                  PageSize pageSize)

PdfPage

protected PdfPage(PdfDocument pdfDocument)

Method Detail

getPageSize

public Rectangle getPageSize()

Gets page size, defined by media box object. This method doesn't take page rotation into account.

Returns:

Rectangle that specify page size.

getPageSizeWithRotation

public Rectangle getPageSizeWithRotation()

Gets page size, considering page rotation.

Returns:

Rectangle that specify size of rotated page.

getRotation

public int getRotation()

Gets the number of degrees by which the page shall be rotated clockwise when displayed or printed. Shall be a multiple of 90.

Returns:

int number of degrees. Default value: 0

setRotation

public PdfPage setRotation(int degAngle)

Sets the page rotation.

Parameters:

degAngle - the int number of degrees by which the page shall be rotated clockwise when displayed or printed. Shall be a multiple of 90.

Returns:

this PdfPage instance.

getContentStream

public PdfStream getContentStream(int index)

Gets the content stream at specified 0-based index in the Contents object PdfArray. The situation when Contents object is a PdfStream is treated like a one element array.

Parameters:

index - the int index of returned PdfStream.

Returns:

PdfStream object at specified index.

Throws:

IndexOutOfBoundsException - if the index is out of range

getContentStreamCount

public int getContentStreamCount()

Gets the size of Contents object PdfArray. The situation when Contents object is a PdfStream is treated like a one element array.

Returns:

the int size of Contents object, or 1 if Contents object is a PdfStream.

getFirstContentStream

public PdfStream getFirstContentStream()

Returns the Contents object if it is PdfStream, or first stream in the array if it is PdfArray.

Returns:

first PdfStream in Contents object, or null if Contents is empty.

getLastContentStream

public PdfStream getLastContentStream()

Returns the Contents object if it is PdfStream, or last stream in the array if it is PdfArray.

Returns:

first PdfStream in Contents object, or null if Contents is empty.

newContentStreamBefore

public PdfStream newContentStreamBefore()

Creates new PdfStream object and puts it at the beginning of Contents array (if Contents object is PdfStream it will be replaced with one-element array).

Returns:

Created PdfStream object.

newContentStreamAfter

public PdfStream newContentStreamAfter()

Creates new PdfStream object and puts it at the end of Contents array (if Contents object is PdfStream it will be replaced with one-element array).

Returns:

Created PdfStream object.

getResources

public PdfResources getResources()

Gets the PdfResources wrapper object for this page resources. If page doesn't have resource object, then it will be inherited from page's parents. If neither parents nor page has the resource object, then the new one is created and added to page dictionary.

NOTE: If you'll try to modify the inherited resources, then the new resources object will be created, so you won't change the parent's resources. This new object under the wrapper will be added to page dictionary on flush(), or you can add it manually with this line, if needed:
getPdfObject().put(PdfName.Resources, getResources().getPdfObject());

Returns:

PdfResources wrapper of the page.

setResources

public PdfPage setResources(PdfResources pdfResources)

Sets PdfResources object.

Parameters:

pdfResources - PdfResources to set.

Returns:

this PdfPage instance.

setXmpMetadata

public void setXmpMetadata(byte[] xmpMetadata)
                    throws IOException

Sets the XMP Metadata.

Parameters:

xmpMetadata - the byte[] of XMP Metadata to set.

Throws:

IOException - in case of writing error.

setXmpMetadata

public void setXmpMetadata(XMPMeta xmpMeta,
                           SerializeOptions serializeOptions)
                    throws XMPException,
                           IOException

Serializes XMP Metadata to byte array and sets it.

Parameters:

xmpMeta - the XMPMeta object to set.

serializeOptions - the SerializeOptions used while serialization.

Throws:

XMPException - in case of XMP Metadata serialization error.

IOException - in case of writing error.

setXmpMetadata

public void setXmpMetadata(XMPMeta xmpMeta)
                    throws XMPException,
                           IOException

Serializes XMP Metadata to byte array and sets it. Uses padding equals to 2000.

Parameters:

xmpMeta - the XMPMeta object to set.

Throws:

XMPException - in case of XMP Metadata serialization error.

IOException - in case of writing error.

getXmpMetadata

public PdfStream getXmpMetadata()
                         throws XMPException

Gets the XMP Metadata object.

Returns:

PdfStream object, that represent XMP Metadata.

Throws:

XMPException

copyTo

public PdfPage copyTo(PdfDocument toDocument)

Copies page to the specified document.

NOTE: Works only for pages from the document opened in reading mode, otherwise an exception is thrown.

Parameters:

toDocument - a document to copy page to.

Returns:

copied PdfPage.

copyTo

public PdfPage copyTo(PdfDocument toDocument,
                      IPdfPageExtraCopier copier)

Copies page to the specified document.

NOTE: Works only for pages from the document opened in reading mode, otherwise an exception is thrown.

Parameters:

toDocument - a document to copy page to.

copier - a copier which bears a special copy logic. May be null. It is recommended to use the same instance of IPdfPageExtraCopier for the same output document.

Returns:

copied PdfPage.

copyAsFormXObject

public PdfFormXObject copyAsFormXObject(PdfDocument toDocument)
                                 throws IOException

Copies page as FormXObject to the specified document.

Parameters:

toDocument - a document to copy to.

Returns:

copied PdfFormXObject object.

Throws:

IOException

getDocument

public PdfDocument getDocument()

Gets the PdfDocument that owns that page, or null if such document isn't exist.

Returns:

PdfDocument that owns that page, or null if such document isn't exist.

flush

public void flush()

Flushes page and it's content stream.

If the page belongs to the document which is tagged, page flushing also triggers flushing of the tags, which are considered to belong to the page. The logic that defines if the given tag (structure element) belongs to the page is the following: if all the marked content references (dictionary or number references), that are the descenders of the given structure element, belong to the current page - the tag is considered to belong to the page. If tag has descenders from several pages - it is flushed, if all other pages except the current one are flushed.

Overrides:

flush in class PdfObjectWrapper<PdfDictionary>

flush

public void flush(boolean flushResourcesContentStreams)

Flushes page and its content stream. If flushResourcesContentStreams is true, all content streams that are rendered on this page (like FormXObjects, annotation appearance streams, patterns) and also all images associated with this page will also be flushed.
For notes about tag structure flushing see PdfPage#flush() method.

If PdfADocument is used, flushing will be applied only if flushResourcesContentStreams is true.

Parameters:

flushResourcesContentStreams - if true all content streams that are rendered on this page (like form xObjects, annotation appearance streams, patterns) and also all images associated with this page will be flushed.

getMediaBox

public Rectangle getMediaBox()

Gets Rectangle object specified by page's Media Box, that defines the boundaries of the physical medium on which the page shall be displayed or printed

Returns:

Rectangle object specified by page Media Box, expressed in default user space units.

Throws:

PdfException - in case of any error while reading MediaBox object.

setMediaBox

public PdfPage setMediaBox(Rectangle rectangle)

Sets the Media Box object, that defines the boundaries of the physical medium on which the page shall be displayed or printed.

Parameters:

rectangle - the Rectangle object to set, expressed in default user space units.

Returns:

this PdfPage instance.

getCropBox

public Rectangle getCropBox()

Gets the Rectangle specified by page's CropBox, that defines the visible region of default user space. When the page is displayed or printed, its contents shall be clipped (cropped) to this rectangle and then shall be imposed on the output medium in some implementation-defined manner.

Returns:

the Rectangle object specified by pages's CropBox, expressed in default user space units. MediaBox by default.

setCropBox

public PdfPage setCropBox(Rectangle rectangle)

Sets the CropBox object, that defines the visible region of default user space. When the page is displayed or printed, its contents shall be clipped (cropped) to this rectangle and then shall be imposed on the output medium in some implementation-defined manner.

Parameters:

rectangle - the Rectangle object to set, expressed in default user space units.

Returns:

this PdfPage instance.

setBleedBox

public PdfPage setBleedBox(Rectangle rectangle)

Sets the BleedBox object, that defines the region to which the contents of the page shall be clipped when output in a production environment.

Parameters:

rectangle - the Rectangle object to set, expressed in default user space units.

Returns:

this PdfPage instance.

getBleedBox

public Rectangle getBleedBox()

Gets the Rectangle object specified by page's BleedBox, that define the region to which the contents of the page shall be clipped when output in a production environment.

Returns:

the Rectangle object specified by page's BleedBox, expressed in default user space units. CropBox by default.

setArtBox

public PdfPage setArtBox(Rectangle rectangle)

Sets the ArtBox object, that define the extent of the page’s meaningful content (including potential white space) as intended by the page’s creator.

Parameters:

rectangle - the Rectangle object to set, expressed in default user space units.

Returns:

this PdfPage instance.

getArtBox

public Rectangle getArtBox()

Gets the Rectangle object specified by page's ArtBox, that define the extent of the page’s meaningful content (including potential white space) as intended by the page’s creator.

Returns:

the Rectangle object specified by page's ArtBox, expressed in default user space units. CropBox by default.

setTrimBox

public PdfPage setTrimBox(Rectangle rectangle)

Sets the TrimBox object, that define the intended dimensions of the finished page after trimming.

Parameters:

rectangle - the Rectangle object to set, expressed in default user space units.

Returns:

this PdfPage instance.

getTrimBox

public Rectangle getTrimBox()

Gets the Rectangle object specified by page's TrimBox object, that define the intended dimensions of the finished page after trimming.

Returns:

the Rectangle object specified by page's TrimBox, expressed in default user space units. CropBox by default.

getContentBytes

public byte[] getContentBytes()

Get decoded bytes for the whole page content.

Returns:

byte array.

Throws:

PdfException - in case of any IOException.

getStreamBytes

public byte[] getStreamBytes(int index)

Gets decoded bytes of a certain stream of a page content.

Parameters:

index - index of stream inside Content.

Returns:

byte array.

Throws:

PdfException - in case of any IOException.

getNextMcid

public int getNextMcid()

Calculates and returns next available MCID reference.

Returns:

calculated MCID reference.

Throws:

PdfException - in case of not tagged document.

getStructParentIndex

public Integer getStructParentIndex()

Gets Integer key of the page’s entry in the structural parent tree.

Returns:

Integer key of the page’s entry in the structural parent tree. If page has no entry in the structural parent tree, returned value is -1.

setAdditionalAction

public PdfPage setAdditionalAction(PdfName key,
                                   PdfAction action)

Helper method to add an additional action to this page. May be used in chain.

Parameters:

key - a PdfName specifying the name of an additional action

action - the PdfAction to add as an additional action

Returns:

this PdfPage instance.

getAnnotations

public List<PdfAnnotation> getAnnotations()

Gets array of annotation dictionaries that shall contain indirect references to all annotations associated with the page.

Returns:

the List<PdfAnnotation> containing all page's annotations.

containsAnnotation

public boolean containsAnnotation(PdfAnnotation annotation)

Checks if page contains the specified annotation.

Parameters:

annotation - the PdfAnnotation to check.

Returns:

true if page contains specified annotation and false otherwise.

addAnnotation

public PdfPage addAnnotation(PdfAnnotation annotation)

Adds specified annotation to the end of annotations array and tagged it. May be used in chain.

Parameters:

annotation - the PdfAnnotation to add.

Returns:

this PdfPage instance.

addAnnotation

public PdfPage addAnnotation(int index,
                             PdfAnnotation annotation,
                             boolean tagAnnotation)

Adds specified PdfAnnotation to specified index in annotations array with or without autotagging. May be used in chain.

Parameters:

index - the index at which specified annotation will be added. If -1 then annotation will be added to the end of array.

annotation - the PdfAnnotation to add.

tagAnnotation - if true the added annotation will be autotagged.
(see TagStructureContext.getAutoTaggingPointer())

Returns:

this PdfPage instance.

removeAnnotation

public PdfPage removeAnnotation(PdfAnnotation annotation)

Removes an annotation from the page.

NOTE: If document is tagged, PdfDocument's PdfTagStructure instance will point at annotation tag parent after method call.

Parameters:

annotation - an annotation to be removed.

Returns:

this PdfPage instance.

getAnnotsSize

public int getAnnotsSize()

Gets the number of PdfAnnotation associated with this page.

Returns:

the int number of PdfAnnotation associated with this page.

getOutlines

public List<PdfOutline> getOutlines(boolean updateOutlines)

This method gets outlines of a current page

Parameters:

updateOutlines -

Returns:

return all outlines of a current page

isIgnorePageRotationForContent

public boolean isIgnorePageRotationForContent()

Returns:

true - if in case the page has a rotation, then new content will be automatically rotated in the opposite direction. On the rotated page this would look like if new content ignores page rotation.

setIgnorePageRotationForContent

public PdfPage setIgnorePageRotationForContent(boolean ignorePageRotationForContent)

If true - defines that in case the page has a rotation, then new content will be automatically rotated in the opposite direction. On the rotated page this would look like if new content ignores page rotation. Default value - false.

Parameters:

ignorePageRotationForContent - - true to ignore rotation of the new content on the rotated page.

setPageLabel

public PdfPage setPageLabel(PageLabelNumberingStyleConstants numberingStyle,
                            String labelPrefix)

This method adds or replaces a page label.

Parameters:

numberingStyle - The numbering style that shall be used for the numeric portion of each page label. May be NULL

labelPrefix - The label prefix for page labels in this range. May be NULL

Returns:

this PdfPage instance.

setPageLabel

public PdfPage setPageLabel(PageLabelNumberingStyleConstants numberingStyle,
                            String labelPrefix,
                            int firstPage)

This method adds or replaces a page label.

Parameters:

numberingStyle - The numbering style that shall be used for the numeric portion of each page label. May be NULL

labelPrefix - The label prefix for page labels in this range. May be NULL

firstPage - The value of the numeric portion for the first page label in the range. Must be greater or equal 1.

Returns:

this PdfPage instance.

setTabOrder

public PdfPage setTabOrder(PdfName tabOrder)

Sets a name specifying the tab order that shall be used for annotations on the page. The possible values are PdfName.R (row order), PdfName.C (column order), and PdfName.S (structure order). See ISO 32000 12.5, "Annotations" for details.

Parameters:

tabOrder - a PdfName specifying the annotations tab order. See method description for the allowed values.

Returns:

this PdfPage instance.

getTabOrder

public PdfName getTabOrder()

Gets a name specifying the tab order that shall be used for annotations on the page. The possible values are PdfName.R (row order), PdfName.C (column order), and PdfName.S (structure order). See ISO 32000 12.5, "Annotations" for details.

Returns:

a PdfName specifying the annotations tab order or null if tab order is not defined.

put

public PdfPage put(PdfName key,
                   PdfObject value)

Helper method that associate specified value with specified key in the underlined PdfDictionary. May be used in chain.

Parameters:

key - the PdfName key with which the specified value is to be associated.

value - the PdfObject value to be associated with the specified key.

Returns:

this PdfPage object.

isPageRotationInverseMatrixWritten

public boolean isPageRotationInverseMatrixWritten()

This flag is meaningful for the case, when page rotation is applied and ignorePageRotationForContent is set to true. NOTE: It is needed for the internal usage.

This flag defines if inverse matrix (which rotates content into the opposite direction from page rotation direction in order to give the impression of the not rotated text) is already applied to the page content stream. See setIgnorePageRotationForContent(boolean)

Returns:

true, if inverse matrix is already applied, false otherwise.

setPageRotationInverseMatrixWritten

public void setPageRotationInverseMatrixWritten()

NOTE: For internal usage! Use this method only if you know what you are doing.

This method is called when inverse matrix (which rotates content into the opposite direction from page rotation direction in order to give the impression of the not rotated text) is applied to the page content stream. See setIgnorePageRotationForContent(boolean)

isWrappedObjectMustBeIndirect

protected boolean isWrappedObjectMustBeIndirect()

Description copied from class: PdfObjectWrapper

Defines if the object behind this wrapper must be an indirect object in the resultant document.

If this method returns true it doesn't necessarily mean that object must be in the indirect state at any moment, but rather defines that when the object will be written to the document it will be transformed into indirect object if it's not indirect yet.

Return value of this method shouldn't depend on any logic, it should return always true or false.

Specified by:

isWrappedObjectMustBeIndirect in class PdfObjectWrapper<PdfDictionary>

Returns:

true if in the resultant document the object behind the wrapper must be indirect, otherwise false.