org.icepdf.core.pobjects
Class Page

java.lang.Object
  org.icepdf.core.pobjects.Dictionary
      org.icepdf.core.pobjects.Page

public class Page
extends Dictionary

This class represents the leaves of a PageTree object known as Page class. The page dictionary specifies attributes of the single page of the document. Many of the page's attributes are inherited from the page tree dictionary if not specified in the page dictionary.

The page object also provides a method which will extract a page's content, such as text and images. The paint method is the core of the ICEpdf renderer, allowing page content to be painted to any Java graphics context.

Page objects in a PDF document have different boundaries defined which govern various aspects of the pre-press process, such as cropping, bleed, and trimming. Facilities for including printer's marks, such a registration targets, gray ramps color bars, and cut marks which assist in the production process. When getting a page's size, the default boundary used is the crop box which is what most viewer applications should use. However, if your application requires the use of different page boundaries, they can be specified when using the getSize or paint methods. If in doubt, always use the crop box constant.

Since:

1.0

See Also:

PageTree

Field Summary

static Name	ANNOTS_KEY
static Name	ARTBOX_KEY
static Name	BLEEDBOX_KEY
static int	BOUNDARY_ARTBOX Defines the extent of the page's meaningful content as intended by the page's creator.
static int	BOUNDARY_BLEEDBOX Defines the region to which the contents of the page should be clipped when output in a production environment (Mainly commercial printing).
static int	BOUNDARY_CROPBOX Defines the visible region of the default user space.
static int	BOUNDARY_MEDIABOX Defines the boundaries of the physical medium on which the page is intended to be displayed or printed.
static int	BOUNDARY_TRIMBOX Defines the intended dimensions of the finished page after trimming.
static Name	CONTENTS_KEY
static Name	CROPBOX_KEY
static java.awt.Color	highlightColor
static Name	MEDIABOX_KEY
static Name	PARENT_KEY
static Name	RESOURCES_KEY
static Name	ROTATE_KEY
static float	selectionAlpha Transparency value used to simulate text highlighting.
static java.awt.Color	selectionColor
static Name	THUMB_KEY
static Name	TRIMBOX_KEY
static Name	TYPE

Fields inherited from class org.icepdf.core.pobjects.Dictionary

entries, FORM_TYPE_KEY, inited, isDeleted, isNew, LENGTH_KEY, library, SUBTYPE_KEY, TYPE_KEY

Constructor Summary

Page(Library l, java.util.HashMap h)
Create a new Page object.

Method Summary

Annotation	addAnnotation(Annotation newAnnotation) Adds an annotation that was previously added to the document.
void	addPaintPageListener(PaintPageListener listener)
void	deleteAnnotation(Annotation annot) Deletes the specified annotation instance from his page.
java.util.List<Annotation>	getAnnotations() Gets all annotation information associated with this page.
java.awt.geom.Rectangle2D.Float	getArtBox() Gets the art box boundary defined by this page.
java.awt.geom.Rectangle2D.Float	getBleedBox() Gets the bleed box boundary defined by this page.
java.awt.geom.Rectangle2D.Double	getBoundingBox(float userRotation) Get the bounding box that the page can occupy, given the userRotation and page's own pageRotation.
java.awt.geom.Rectangle2D.Double	getBoundingBox(float userRotation, float userZoom) Get the bounding box that the page can occupy, given the userRotation, userZoom, page's own pageRotation.
java.awt.geom.Rectangle2D.Double	getBoundingBox(int boundary, float userRotation, float userZoom) Get the bounding box that the page can occupy, given the userRotation, userZoom, page's own pageRotation and cropBox boundary.
java.awt.geom.Rectangle2D.Float	getCropBox() Gets the crop box boundary defined by this page.
java.lang.String[]	getDecodedContentSteam() Returns the decoded content stream for this page instance.
java.util.List<java.awt.Image>	getImages() Gets a vector of Images where each index represents an image inside this page.
java.awt.geom.Rectangle2D.Float	getMediaBox() Gets the media box boundary defined by this page.
PRectangle	getPageBoundary(int specifiedBox) Utility method for appling the page boundary rules.
java.awt.Shape	getPageShape(int boundary, float userRotation, float userZoom) This method returns a Shape that represents the outline of this Page, after being rotated and zoomed.
java.awt.geom.AffineTransform	getPageTransform(int boundary, float userRotation, float userZoom) The Java Graphics coordinate system has the origin at the top-left of the screen, with Y values increasing as one moves down the screen.
PageTree	getParent() Gets the page's parent page tree.
protected Reference	getParentReference() Gets a reference to the page's parent page tree.
Resources	getResources()
PDimension	getSize(float userRotation) Get the width and height that the page can occupy, given the userRotation, page's own pageRotation and cropBox boundary.
PDimension	getSize(float userRotation, float userZoom) Get the width and height that the page can occupy, given the userRotation, userZoom, page's own pageRotation and cropBox boundary.
PDimension	getSize(int boundary, float userRotation, float userZoom) Get the width and height that the page can occupy, given the userRotation, userZoom, page's own pageRotation and cropBox boundary.
PageText	getText() Gest the PageText data structure for this page using an accelerated parsing technique that ignores some text elements.
Thumbnail	getThumbnail() Gets a Thumbnail object associated with this page.
float	getTotalRotation(float userRotation) Gets the total rotation factor of the page after applying a user rotation factor.
java.awt.geom.Rectangle2D.Float	getTrimBox() Gets the trim box boundary defined by this page.
PageText	getViewText() Gest the PageText data structure for this page.
void	init() Initialize the Page object.
boolean	isInitiated()
void	notifyPaintPageListeners()
void	paint(java.awt.Graphics g, int renderHintType, int boundary, float userRotation, float userZoom) Paints the contents of this page to the graphics context using the specified rotation, zoom, rendering hints and page boundary.
void	paint(java.awt.Graphics g, int renderHintType, int boundary, float userRotation, float userZoom, boolean paintAnnotations, boolean paintSearchHighlight) Paints the contents of this page to the graphics context using the specified rotation, zoom, rendering hints and page boundary.
void	paintPageContent(java.awt.Graphics g, int renderHintType, float userRotation, float userZoom, boolean paintAnnotations, boolean paintSearchHighlight) Paints the contents of this page to the graphics context using the specified rotation, zoom, rendering hints.
void	removePaintPageListener(PaintPageListener listener)
void	requestInterrupt()
void	resetInitializedState() Reset the pages initialized flag and as a result subsequent calls to this page may trigger a call to init().
void	setPObjectReference(Reference reference) Sets the reference used to identify this Dictionary in the PDF document.
java.lang.String	toString() Returns a summary of the page dictionary entries.
boolean	updateAnnotation(Annotation annotation) Updates the annotation associated with this page.

Methods inherited from class org.icepdf.core.pobjects.Dictionary

getEntries, getFloat, getInt, getLibrary, getNumber, getObject, getPObjectReference, isDeleted, isNew, setDeleted, setNew

Methods inherited from class java.lang.Object

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

Field Detail

selectionAlpha

public static final float selectionAlpha

Transparency value used to simulate text highlighting.

See Also:

Constant Field Values

selectionColor

public static java.awt.Color selectionColor

highlightColor

public static java.awt.Color highlightColor

TYPE

public static final Name TYPE

ANNOTS_KEY

public static final Name ANNOTS_KEY

CONTENTS_KEY

public static final Name CONTENTS_KEY

RESOURCES_KEY

public static final Name RESOURCES_KEY

THUMB_KEY

public static final Name THUMB_KEY

PARENT_KEY

public static final Name PARENT_KEY

ROTATE_KEY

public static final Name ROTATE_KEY

MEDIABOX_KEY

public static final Name MEDIABOX_KEY

CROPBOX_KEY

public static final Name CROPBOX_KEY

ARTBOX_KEY

public static final Name ARTBOX_KEY

BLEEDBOX_KEY

public static final Name BLEEDBOX_KEY

TRIMBOX_KEY

public static final Name TRIMBOX_KEY

BOUNDARY_MEDIABOX

public static final int BOUNDARY_MEDIABOX

Defines the boundaries of the physical medium on which the page is intended to be displayed or printed.

See Also:

Constant Field Values

BOUNDARY_CROPBOX

public static final int BOUNDARY_CROPBOX

Defines the visible region of the default user space. When the page is displayed or printed, its contents are to be clipped to this rectangle and then imposed on the output medium in some implementation defined manner.

See Also:

Constant Field Values

BOUNDARY_BLEEDBOX

public static final int BOUNDARY_BLEEDBOX

Defines the region to which the contents of the page should be clipped when output in a production environment (Mainly commercial printing).

See Also:

Constant Field Values

BOUNDARY_TRIMBOX

public static final int BOUNDARY_TRIMBOX

Defines the intended dimensions of the finished page after trimming.

See Also:

Constant Field Values

BOUNDARY_ARTBOX

public static final int BOUNDARY_ARTBOX

Defines the extent of the page's meaningful content as intended by the page's creator.

See Also:

Constant Field Values

Constructor Detail

Page

public Page(Library l,
            java.util.HashMap h)

Create a new Page object. A page object represents a PDF object that has the name page associated with it. It also conceptually represents a page entity and all of it child elements that are associated with it.

Parameters:

l - pointer to default library containing all document objects

h - HashMap containing all of the dictionary entries

Method Detail

isInitiated

public boolean isInitiated()

setPObjectReference

public void setPObjectReference(Reference reference)

Description copied from class: Dictionary

Sets the reference used to identify this Dictionary in the PDF document. The reference number and generation number of this reference is needed by the encryption algorithm to correctly decrypt this object.

This method should only be used by the PDF Parser. Use of this method outside the context of the PDF Parser may result in unpredictable behavior.

Overrides:

setPObjectReference in class Dictionary

Parameters:

reference - Reference used to identify this Dictionary in the PDF document.

See Also:

Dictionary.getPObjectReference()

resetInitializedState

public void resetInitializedState()

Reset the pages initialized flag and as a result subsequent calls to this page may trigger a call to init().

init

public void init()

Initialize the Page object. This method triggers the parsing of a page's child elements. Once a page has been initialized, it can be painted.

Overrides:

init in class Dictionary

getThumbnail

public Thumbnail getThumbnail()

Gets a Thumbnail object associated with this page. If no Thumbnail entry exists then null is returned.

Returns:

thumbnail object of this page, null if no thumbnail value is encoded.

requestInterrupt

public void requestInterrupt()

paint

public void paint(java.awt.Graphics g,
                  int renderHintType,
                  int boundary,
                  float userRotation,
                  float userZoom)

Paints the contents of this page to the graphics context using the specified rotation, zoom, rendering hints and page boundary.

Parameters:

g - graphics context to which the page content will be painted.

renderHintType - Constant specified by the GraphicsRenderingHints class. There are two possible entries, SCREEN and PRINT, each with configurable rendering hints settings.

boundary - Constant specifying the page boundary to use when painting the page content.

userRotation - Rotation factor, in degrees, to be applied to the rendered page

userZoom - Zoom factor to be applied to the rendered page

paint

public void paint(java.awt.Graphics g,
                  int renderHintType,
                  int boundary,
                  float userRotation,
                  float userZoom,
                  boolean paintAnnotations,
                  boolean paintSearchHighlight)

Paints the contents of this page to the graphics context using the specified rotation, zoom, rendering hints and page boundary.

Parameters:

g - graphics context to which the page content will be painted.

renderHintType - Constant specified by the GraphicsRenderingHints class. There are two possible entries, SCREEN and PRINT, each with configurable rendering hints settings.

boundary - Constant specifying the page boundary to use when painting the page content.

userRotation - Rotation factor, in degrees, to be applied to the rendered page

userZoom - Zoom factor to be applied to the rendered page

paintAnnotations - true enables the painting of page annotations. False paints no annotations for a given page.

paintSearchHighlight - true enables the painting of search highlight state of text object. The search controller can be used to easily search and add highlighted state for search terms.

paintPageContent

public void paintPageContent(java.awt.Graphics g,
                             int renderHintType,
                             float userRotation,
                             float userZoom,
                             boolean paintAnnotations,
                             boolean paintSearchHighlight)

Paints the contents of this page to the graphics context using the specified rotation, zoom, rendering hints.

The drawing commands that are issued on the given graphics context will use coordinates in PDF user coordinate space. It is the responsibility of the caller of this method to setup the graphics context to correctly interpret these coordinates.

Parameters:

g - graphics context to which the page content will be painted.

renderHintType - Constant specified by the GraphicsRenderingHints class. There are two possible entries, SCREEN and PRINT, each with configurable rendering hints settings.

userRotation - Rotation factor, in degrees, to be applied to the rendered page

userZoom - Zoom factor to be applied to the rendered page

paintAnnotations - true enables the painting of page annotations. False paints no annotations for a given page.

paintSearchHighlight - true enables the painting of search highlight state of text object. The search controller can be used to easily search and add highlighted state for search terms.

getPageTransform

public java.awt.geom.AffineTransform getPageTransform(int boundary,
                                                      float userRotation,
                                                      float userZoom)

The Java Graphics coordinate system has the origin at the top-left of the screen, with Y values increasing as one moves down the screen. The PDF coordinate system has the origin at the bottom-left of the document, with Y values increasing as one moved up the document. As well, PDFs can be displayed both rotated and zoomed. This method gives an AffineTransform which can be passed to java.awt.Graphics2D.transform(AffineTransform) so that one can then use that Graphics2D in the user-perspectived PDF coordinate space.

Parameters:

boundary - Constant specifying the page boundary to use when painting the page content.

userRotation - Rotation factor, in degrees, to be applied to the rendered page

userZoom - Zoom factor to be applied to the rendered page

Returns:

AffineTransform for translating from the rotated and zoomed PDF coordinate system to the Java Graphics coordinate system

getPageShape

public java.awt.Shape getPageShape(int boundary,
                                   float userRotation,
                                   float userZoom)

This method returns a Shape that represents the outline of this Page, after being rotated and zoomed. It is used for clipping, and drawing borders around the page rendering onscreen.

Parameters:

boundary - Constant specifying the page boundary to use

userRotation - Rotation factor, in degrees, to be applied

userZoom - Zoom factor to be applied

Returns:

Shape outline of the rotated and zoomed portion of this Page corresponding to the specified boundary

addAnnotation

public Annotation addAnnotation(Annotation newAnnotation)

Adds an annotation that was previously added to the document. It is assumed that the annotation has a valid object reference. This is commonly used with the undo/redo state manager in the RI. Use the method @link{#createAnnotation} for creating new annotations.

Parameters:

newAnnotation - annotation object to add

Returns:

reference to annotaiton that was added.

deleteAnnotation

public void deleteAnnotation(Annotation annot)

Deletes the specified annotation instance from his page. If the annotation was origional then either the page or the annot ref object is also added to the state maanger. If the annotation was new then we just have to update the page and or annot reference as the objects will allready be in the state manager.

updateAnnotation

public boolean updateAnnotation(Annotation annotation)

Updates the annotation associated with this page. If the annotation is not in this page then the annotation is no added.

Parameters:

annotation - annotation object that should be updated for this page.

Returns:

true if the update was successful, false otherwise.

getParentReference

protected Reference getParentReference()

Gets a reference to the page's parent page tree. A reference can be resolved by the Library class.

Returns:

reference to parent page tree.

See Also:

Library

getParent

public PageTree getParent()

Gets the page's parent page tree.

Returns:

parent page tree.

getSize

public PDimension getSize(float userRotation)

Get the width and height that the page can occupy, given the userRotation, page's own pageRotation and cropBox boundary. The page's default zoom of 1.0f is used.

Parameters:

userRotation - Rotation factor specified by the user under which the page will be rotated.

Returns:

Dimension of width and height of the page represented in point units.

See Also:

getSize(float, float)

getSize

public PDimension getSize(float userRotation,
                          float userZoom)

Get the width and height that the page can occupy, given the userRotation, userZoom, page's own pageRotation and cropBox boundary.

Parameters:

userRotation - rotation factor specified by the user under which the page will be rotated.

userZoom - zoom factor specifed by the user under which the page will be rotated.

Returns:

Dimension of width and height of the page represented in point units.

getSize

public PDimension getSize(int boundary,
                          float userRotation,
                          float userZoom)

Get the width and height that the page can occupy, given the userRotation, userZoom, page's own pageRotation and cropBox boundary.

Parameters:

boundary - boundary constant to specify which boundary to respect when calculating the page's size.

userRotation - rotation factor specified by the user under which the page will be rotated.

userZoom - zoom factor specified by the user under which the page will be rotated.

Returns:

Dimension of width and height of the page represented in point units. or null if the boundary box is not defined.

getBoundingBox

public java.awt.geom.Rectangle2D.Double getBoundingBox(float userRotation)

Get the bounding box that the page can occupy, given the userRotation and page's own pageRotation. The boundary of BOUNDARY_CROPBOX, and the default zoom of 1.0f are assumed.

Parameters:

userRotation - Rotation factor specified by the user under which the page will be rotated.

Returns:

Dimension of width and height of the page represented in point units.

See Also:

getSize(float, float)

getBoundingBox

public java.awt.geom.Rectangle2D.Double getBoundingBox(float userRotation,
                                                       float userZoom)

Get the bounding box that the page can occupy, given the userRotation, userZoom, page's own pageRotation.

Parameters:

userRotation - rotation factor specified by the user under which the page will be rotated.

userZoom - zoom factor specified by the user under which the page will be rotated.

Returns:

Rectangle encompassing the page represented in point units.

getBoundingBox

public java.awt.geom.Rectangle2D.Double getBoundingBox(int boundary,
                                                       float userRotation,
                                                       float userZoom)

Get the bounding box that the page can occupy, given the userRotation, userZoom, page's own pageRotation and cropBox boundary.

Parameters:

boundary - boundary constant to specify which boundary to respect when calculating the page's size.

userRotation - rotation factor specified by the user under which the page will be rotated.

userZoom - zoom factor specified by the user under which the page will be rotated.

Returns:

Rectangle encompassing the page represented in point units.

getPageBoundary

public PRectangle getPageBoundary(int specifiedBox)

Utility method for appling the page boundary rules.

Parameters:

specifiedBox - page boundary constant

Returns:

bounds of page after the chain of rules have been applied.

toString

public java.lang.String toString()

Returns a summary of the page dictionary entries.

Overrides:

toString in class Dictionary

Returns:

dictionary entries.

getTotalRotation

public float getTotalRotation(float userRotation)

Gets the total rotation factor of the page after applying a user rotation factor. This method will normalize rotation factors to be in the range of 0 to 360 degrees.

Parameters:

userRotation - rotation factor to be applied to page

Returns:

Total Rotation, representing pageRoation + user rotation factor applied to the whole document.

getAnnotations

public java.util.List<Annotation> getAnnotations()

Gets all annotation information associated with this page. Each entry in the vector represents one annotation. The size of the vector represents the total number of annotations associated with the page.

Returns:

annotation associated with page; null, if there are no annotations.

getDecodedContentSteam

public java.lang.String[] getDecodedContentSteam()

Returns the decoded content stream for this page instance. A page instance can have more then one content stream associated with it.

Returns:

An array of decoded content stream. Each index in the array represents one content stream. Null return and null String array values are possible.

getMediaBox

public java.awt.geom.Rectangle2D.Float getMediaBox()

Gets the media box boundary defined by this page. The media box is a required page entry and can be inherited from its parent page tree.

Returns:

media box boundary in user space units.

getCropBox

public java.awt.geom.Rectangle2D.Float getCropBox()

Gets the crop box boundary defined by this page. The media box is a required page entry and can be inherited from its parent page tree.

Returns:

crop box boundary in user space units.

getArtBox

public java.awt.geom.Rectangle2D.Float getArtBox()

Gets the art box boundary defined by this page. The art box is a required page entry and can be inherited from its parent page tree.

Returns:

art box boundary in user space units.

getBleedBox

public java.awt.geom.Rectangle2D.Float getBleedBox()

Gets the bleed box boundary defined by this page. The bleed box is a required page entry and can be inherited from its parent page tree.

Returns:

bleed box boundary in user space units.

getTrimBox

public java.awt.geom.Rectangle2D.Float getTrimBox()

Gets the trim box boundary defined by this page. The trim box is a required page entry and can be inherited from its parent page tree.

Returns:

trim box boundary in user space units.

getViewText

public PageText getViewText()

Gest the PageText data structure for this page. PageText is made up of lines, words and glyphs which can be used for searches, text extraction and text highlighting. The coordinates system has been normalized to page space.

Returns:

list of text sprites for the given page.

getText

public PageText getText()
                 throws java.lang.InterruptedException

Gest the PageText data structure for this page using an accelerated parsing technique that ignores some text elements. This method should be used for straight text extraction.

Returns:

vector of Strings of all text objects inside the specified page.

Throws:

java.lang.InterruptedException

getImages

public java.util.List<java.awt.Image> getImages()

Gets a vector of Images where each index represents an image inside this page.

Returns:

vector of Images inside the current page

getResources

public Resources getResources()

addPaintPageListener

public void addPaintPageListener(PaintPageListener listener)

removePaintPageListener

public void removePaintPageListener(PaintPageListener listener)

notifyPaintPageListeners

public void notifyPaintPageListeners()