com.itextpdf.kernel.pdf

Class PdfCatalog

java.lang.Object

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

com.itextpdf.kernel.pdf.PdfCatalog

public class PdfCatalog
extends PdfObjectWrapper<PdfDictionary>

The root of a document’s object hierarchy.

Field Summary

Fields

Modifier and Type	Field and Description
protected Map<PdfName,PdfNameTree>	nameTrees Map of the PdfNameTree.
protected PdfOCProperties	ocProperties The document’s optional content properties dictionary.
protected PdfNumTree	pageLabels Defining the page labelling for the document.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	PdfCatalog(PdfDictionary pdfObject) Create PdfCatalog dictionary.
protected	PdfCatalog(PdfDocument pdfDocument) Create PdfCatalog to PdfDocument.

Method Summary

Modifier and Type	Method and Description
void	addDeveloperExtension(PdfDeveloperExtension extension) Add an extensions dictionary containing developer prefix identification and version numbers for developer extensions that occur in this document.
void	flush() PdfCatalog will be flushed in PdfDocument.close().
PdfCollection	getCollection() Gets collection dictionary that a conforming reader shall use to enhance the presentation of file attachments stored in the PDF document.
PdfDocument	getDocument() Get PdfDocument with indirect reference associated with the object.
PdfString	getLang() Get natural language.
PdfNameTree	getNameTree(PdfName treeType) This method gets Names tree from the catalog.
PdfOCProperties	getOCProperties(boolean createIfNotExists) Use this method to get the Optional Content Properties Dictionary.
PdfNumTree	getPageLabelsTree(boolean createIfNotExists) This method returns the NumberTree of Page Labels
PdfName	getPageLayout() Get page layout of the document.
PdfName	getPageMode() Get page mode of the document.
PdfViewerPreferences	getViewerPreferences() Get viewer preferences of the document.
protected boolean	isOCPropertiesMayHaveChanged() True indicates that getOCProperties() was called, may have been modified, and thus its dictionary needs to be reconstructed.
protected boolean	isWrappedObjectMustBeIndirect() Defines if the object behind this wrapper must be an indirect object in the resultant document.
PdfCatalog	put(PdfName key, PdfObject value) Add key and value to PdfCatalog dictionary.
PdfCatalog	remove(PdfName key) Remove key from catalog dictionary.
PdfCatalog	setAdditionalAction(PdfName key, PdfAction action) The actions that shall be taken in response to various trigger events affecting the document as a whole.
PdfCatalog	setCollection(PdfCollection collection) Sets collection dictionary that a conforming reader shall use to enhance the presentation of file attachments stored in the PDF document.
void	setLang(PdfString lang) An entry specifying the natural language, and optionally locale.
PdfCatalog	setOpenAction(PdfAction action) A value specifying an action that shall be performed when the document is opened.
PdfCatalog	setOpenAction(PdfDestination destination) A value specifying a destination that shall be displayed when the document is opened.
PdfCatalog	setPageLayout(PdfName pageLayout) This method sets a page layout of the document
PdfCatalog	setPageMode(PdfName pageMode) This method sets a page mode of the document.
PdfCatalog	setViewerPreferences(PdfViewerPreferences preferences) This method sets the document viewer preferences, specifying the way the document shall be displayed on the screen

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

Field Detail

nameTrees

protected Map<PdfName,PdfNameTree> nameTrees

Map of the PdfNameTree. Used for creation name tree dictionary.

pageLabels

protected PdfNumTree pageLabels

Defining the page labelling for the document.

ocProperties

protected PdfOCProperties ocProperties

The document’s optional content properties dictionary.

Constructor Detail

PdfCatalog

protected PdfCatalog(PdfDictionary pdfObject)

Create PdfCatalog dictionary.

Parameters:

pdfObject - the dictionary to be wrapped

PdfCatalog

protected PdfCatalog(PdfDocument pdfDocument)

Create PdfCatalog to PdfDocument.

Parameters:

pdfDocument - A PdfDocument object representing the document to which redaction applies

Method Detail

getOCProperties

public PdfOCProperties getOCProperties(boolean createIfNotExists)

Use this method to get the Optional Content Properties Dictionary. Note that if you call this method, then the PdfDictionary with OCProperties will be generated from PdfOCProperties object right before closing the PdfDocument, so if you want to make low-level changes in Pdf structures themselves (PdfArray, PdfDictionary, etc), then you should address directly those objects, e.g.: PdfCatalog pdfCatalog = pdfDoc.getCatalog(); PdfDictionary ocProps = pdfCatalog.getAsDictionary(PdfName.OCProperties); // manipulate with ocProps. Also note that this method is implicitly called when creating a new PdfLayer instance, so you should either use hi-level logic of operating with layers, or manipulate low-level Pdf objects by yourself.

Parameters:

createIfNotExists - true to create new /OCProperties entry in catalog if not exists, false to return null if /OCProperties entry in catalog is not present.

Returns:

the Optional Content Properties Dictionary

getDocument

public PdfDocument getDocument()

Get PdfDocument with indirect reference associated with the object.

Returns:

the resultant dictionary

flush

public void flush()

PdfCatalog will be flushed in PdfDocument.close(). User mustn't flush PdfCatalog!

Overrides:

flush in class PdfObjectWrapper<PdfDictionary>

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.

setOpenAction

public PdfCatalog setOpenAction(PdfDestination destination)

A value specifying a destination that shall be displayed when the document is opened. See ISO 32000-1, Table 28 – Entries in the catalog dictionary.

Parameters:

destination - instance of PdfDestination.

Returns:

destination

setOpenAction

public PdfCatalog setOpenAction(PdfAction action)

A value specifying an action that shall be performed when the document is opened. See ISO 32000-1, Table 28 – Entries in the catalog dictionary.

Parameters:

action - instance of PdfAction.

Returns:

action

setAdditionalAction

public PdfCatalog setAdditionalAction(PdfName key,
                                      PdfAction action)

The actions that shall be taken in response to various trigger events affecting the document as a whole. See ISO 32000-1, Table 28 – Entries in the catalog dictionary.

Parameters:

key - the key of which the associated value needs to be returned

action - instance of PdfAction.

Returns:

additional action

getPageMode

public PdfName getPageMode()

Get page mode of the document.

Returns:

current instance of PdfCatalog

setPageMode

public PdfCatalog setPageMode(PdfName pageMode)

This method sets a page mode of the document.
Valid values are: PdfName.UseNone, PdfName.UseOutlines, PdfName.UseThumbs, PdfName.FullScreen, PdfName.UseOC, PdfName.UseAttachments.

Parameters:

pageMode - page mode.

Returns:

current instance of PdfCatalog

getPageLayout

public PdfName getPageLayout()

Get page layout of the document.

Returns:

name object of page layout that shall be used when document is opened

setPageLayout

public PdfCatalog setPageLayout(PdfName pageLayout)

This method sets a page layout of the document

Parameters:

pageLayout - page layout of the document

Returns:

PdfCatalog instance with applied page layout

getViewerPreferences

public PdfViewerPreferences getViewerPreferences()

Get viewer preferences of the document.

Returns:

dictionary of viewer preferences

setViewerPreferences

public PdfCatalog setViewerPreferences(PdfViewerPreferences preferences)

This method sets the document viewer preferences, specifying the way the document shall be displayed on the screen

Parameters:

preferences - document's viewer preferences

Returns:

PdfCatalog instance with applied viewer preferences

getNameTree

public PdfNameTree getNameTree(PdfName treeType)

This method gets Names tree from the catalog.

Parameters:

treeType - type of the tree (Dests, AP, EmbeddedFiles etc).

Returns:

returns PdfNameTree

getPageLabelsTree

public PdfNumTree getPageLabelsTree(boolean createIfNotExists)

This method returns the NumberTree of Page Labels

Parameters:

createIfNotExists - defines whether the NumberTree of Page Labels should be created if it didn't exist before

Returns:

returns PdfNumTree

getLang

public PdfString getLang()

Get natural language.

Returns:

natural language

setLang

public void setLang(PdfString lang)

An entry specifying the natural language, and optionally locale. Use this to specify the Language attribute on a Tagged Pdf element. For the content usage dictionary, use PdfName.Language

Parameters:

lang - language to be set

addDeveloperExtension

public void addDeveloperExtension(PdfDeveloperExtension extension)

Add an extensions dictionary containing developer prefix identification and version numbers for developer extensions that occur in this document. See ISO 32000-1, Table 28 – Entries in the catalog dictionary.

Parameters:

extension - enables developers to identify their own extension relative to a base version of PDF

getCollection

public PdfCollection getCollection()

Gets collection dictionary that a conforming reader shall use to enhance the presentation of file attachments stored in the PDF document.

Returns:

PdfCollection wrapper of collection dictionary.

setCollection

public PdfCatalog setCollection(PdfCollection collection)

Sets collection dictionary that a conforming reader shall use to enhance the presentation of file attachments stored in the PDF document.

Parameters:

collection - dictionary

Returns:

PdfCatalog instance with applied collection dictionary

put

public PdfCatalog put(PdfName key,
                      PdfObject value)

Add key and value to PdfCatalog dictionary.

Parameters:

key - the dictionary key corresponding with the PDF object

value - the value of key

Returns:

the key and value

remove

public PdfCatalog remove(PdfName key)

Remove key from catalog dictionary.

Parameters:

key - the dictionary key corresponding with the PDF object

Returns:

the key

isOCPropertiesMayHaveChanged

protected boolean isOCPropertiesMayHaveChanged()

True indicates that getOCProperties() was called, may have been modified, and thus its dictionary needs to be reconstructed.

Returns:

boolean indicating if the dictionary needs to be reconstructed