Package com.itextpdf.kernel.pdf
Class PdfCatalog
The root of a document’s object hierarchy.
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final org.slf4j.Logger
protected Map
<PdfName, PdfNameTree> Map of thePdfNameTree
.private boolean
protected PdfOCProperties
The document’s optional content properties dictionary.private boolean
private PdfOutline
protected PdfNumTree
Defining the page labelling for the document.private final Map
<PdfObject, List<PdfOutline>> private final PdfPagesTree
private static final String
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
PdfCatalog
(PdfDictionary pdfObject) CreatePdfCatalog
dictionary.protected
PdfCatalog
(PdfDocument pdfDocument) CreatePdfCatalog
toPdfDocument
. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addDeveloperExtension
(PdfDeveloperExtension extension) Add an extensions dictionary containing developer prefix identification and version numbers for developer extensions that occur in this document.(package private) void
addNamedDestination
(PdfString key, PdfObject value) This methods adds new name to the Dests NameTree.(package private) void
addNameToNameTree
(PdfString key, PdfObject value, PdfName treeType) This methods adds a new name to the specified NameTree.private void
addOutlineToPage
(PdfOutline outline, IPdfNameTreeAccess names) private void
addOutlineToPage
(PdfOutline outline, PdfDictionary item, IPdfNameTreeAccess names) (package private) void
addRootOutline
(PdfOutline outline) This method sets the root outline element in the catalog.(package private) void
constructOutlines
(PdfDictionary outlineRoot, IPdfNameTreeAccess names) Constructdictionary
iteratively.(package private) PdfDestination
copyDestination
(PdfObject dest, Map<PdfPage, PdfPage> page2page, PdfDocument toDocument) (package private) PdfDictionary
void
flush()
PdfCatalog will be flushed in PdfDocument.close().Gets collection dictionary that a conforming reader shall use to enhance the presentation of file attachments stored in the PDF document.GetPdfDocument
with indirect reference associated with the object.getLang()
Get natural language.getNameTree
(PdfName treeType) This method gets Names tree from the catalog.getOCProperties
(boolean createIfNotExists) Use this method to get the Optional Content Properties Dictionary.(package private) PdfOutline
getOutlines
(boolean updateOutlines) This method returns a complete outline tree of the whole document.getPageLabelsTree
(boolean createIfNotExists) This method returns the NumberTree of Page LabelsGet page layout of the document.Get page mode of the document.(package private) Map
<PdfObject, List<PdfOutline>> this method return map containing all pages of the document with associated outlines.(package private) PdfPagesTree
Get viewer preferences of the document.(package private) boolean
Indicates if the catalog has any outlinesprivate boolean
isEqualSameNameDestExist
(Map<PdfPage, PdfPage> page2page, PdfDocument toDocument, PdfString srcDestName, PdfArray srcDestArray, PdfPage oldPage) protected boolean
True indicates that getOCProperties() was called, may have been modified, and thus its dictionary needs to be reconstructed.(package private) boolean
This flag determines if Outline tree of the document has been built via calling getOutlines method.protected boolean
Defines if the object behind this wrapper must be an indirect object in the resultant document.boolean
nameTreeContainsKey
(PdfName treeType) This method checks Names tree for specified tree type.Add key and value toPdfCatalog
dictionary.Remove key from catalog dictionary.(package private) void
removeOutlines
(PdfPage page) This method removes all outlines associated with a given pagesetAdditionalAction
(PdfName key, PdfAction action) The actions that shall be taken in response to various trigger events affecting the document as a whole.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
An entry specifying the natural language, and optionally locale.(package private) void
setOcgCopied
(boolean ocgCopied) setOpenAction
(PdfAction action) A value specifying an action that shall be performed when the document is opened.setOpenAction
(PdfDestination destination) A value specifying a destination that shall be displayed when the document is opened.setPageLayout
(PdfName pageLayout) This method sets a page layout of the documentsetPageMode
(PdfName pageMode) This method sets a page mode of the document.setViewerPreferences
(PdfViewerPreferences preferences) This method sets the document viewer preferences, specifying the way the document shall be displayed on the screenMethods inherited from class com.itextpdf.kernel.pdf.PdfObjectWrapper
ensureObjectIsAddedToDocument, ensureUnderlyingObjectHasIndirectReference, getPdfObject, isFlushed, makeIndirect, makeIndirect, markObjectAsIndirect, setForbidRelease, setModified, setPdfObject, unsetForbidRelease
-
Field Details
-
LOGGER
private static final org.slf4j.Logger LOGGER -
ROOT_OUTLINE_TITLE
- See Also:
-
PAGE_MODES
-
PAGE_LAYOUTS
-
pageTree
-
nameTrees
Map of thePdfNameTree
. Used for creationname tree
dictionary. -
pageLabels
Defining the page labelling for the document. -
ocProperties
The document’s optional content properties dictionary. -
outlines
-
pagesWithOutlines
-
outlineMode
private boolean outlineMode -
ocgCopied
private boolean ocgCopied
-
-
Constructor Details
-
PdfCatalog
CreatePdfCatalog
dictionary.- Parameters:
pdfObject
- the dictionary to be wrapped
-
PdfCatalog
CreatePdfCatalog
toPdfDocument
.- Parameters:
pdfDocument
- APdfDocument
object representing the document to which redaction applies
-
-
Method Details
-
getOCProperties
Use this method to get the Optional Content Properties Dictionary. Note that if you call this method, then thePdfDictionary
with OCProperties will be generated fromPdfOCProperties
object right before closing thePdfDocument
, 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
GetPdfDocument
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 classPdfObjectWrapper<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 classPdfObjectWrapper<PdfDictionary>
- Returns:
- true if in the resultant document the object behind the wrapper must be indirect, otherwise false.
-
setOpenAction
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 ofPdfAction
.- Returns:
- action
-
setAdditionalAction
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 returnedaction
- instance ofPdfAction
.- Returns:
- additional action
-
getPageMode
Get page mode of the document.- Returns:
- current instance of
PdfCatalog
-
setPageMode
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
Get page layout of the document.- Returns:
- name object of page layout that shall be used when document is opened
-
setPageLayout
This method sets a page layout of the document- Parameters:
pageLayout
- page layout of the document- Returns:
PdfCatalog
instance with applied page layout
-
getViewerPreferences
Get viewer preferences of the document.- Returns:
- dictionary of viewer preferences
-
setViewerPreferences
This method sets the document viewer preferences, specifying the way the document shall be displayed on the screen- Parameters:
preferences
- document'sviewer preferences
- Returns:
PdfCatalog
instance with applied viewer preferences
-
getNameTree
This method gets Names tree from the catalog.- Parameters:
treeType
- type of the tree (Dests, AP, EmbeddedFiles etc).- Returns:
- returns
PdfNameTree
-
nameTreeContainsKey
This method checks Names tree for specified tree type.- Parameters:
treeType
- type of tree which existence should be checked- Returns:
- true if such tree exists, false otherwise
-
getPageLabelsTree
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
Get natural language.- Returns:
- natural language
-
setLang
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
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
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
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
Add key and value toPdfCatalog
dictionary.- Parameters:
key
- the dictionary key corresponding with the PDF objectvalue
- the value of key- Returns:
- the key and value
-
remove
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
-
setOcgCopied
void setOcgCopied(boolean ocgCopied) -
getPageTree
PdfPagesTree getPageTree() -
getPagesWithOutlines
Map<PdfObject,List<PdfOutline>> getPagesWithOutlines()this method return map containing all pages of the document with associated outlines.- Returns:
- map containing all pages of the document with associated outlines
-
addNamedDestination
This methods adds new name to the Dests NameTree. It throws an exception, if the name already exists.- Parameters:
key
- Name of the destination.value
- An object destination refers to. Must be an array or a dictionary with key /D and array. See ISO 32000-1 12.3.2.3 for more info.
-
addNameToNameTree
This methods adds a new name to the specified NameTree. It throws an exception, if the name already exists.- Parameters:
key
- key in the name treevalue
- value in the name treetreeType
- type of the tree (Dests, AP, EmbeddedFiles etc).
-
getOutlines
This method returns a complete outline tree of the whole document.- Parameters:
updateOutlines
- if the flag is true, the method read the whole document and creates outline tree. If false the method gets cached outline tree (if it was cached via calling getOutlines method before).- Returns:
- fully initialized
PdfOutline
object.
-
hasOutlines
boolean hasOutlines()Indicates if the catalog has any outlines- Returns:
true
, if there are outlines andfalse
otherwise.
-
isOutlineMode
boolean isOutlineMode()This flag determines if Outline tree of the document has been built via calling getOutlines method. If this flag is false all outline operations will be ignored- Returns:
- state of outline mode.
-
removeOutlines
This method removes all outlines associated with a given page- Parameters:
page
- the page to remove outlines
-
addRootOutline
This method sets the root outline element in the catalog.- Parameters:
outline
- the outline dictionary that shall be the root of the document’s outline hierarchy
-
constructOutlines
Constructdictionary
iteratively. Invalid pdf documents will be processed depending onPdfReader.StrictnessLevel
, if it set to lenient, we will ignore and process invalid outline structure, otherwisePdfException
will be thrown.- Parameters:
outlineRoot
-dictionary
root.names
- map containing the PdfObjects stored in the tree.
-
copyDestination
PdfDestination copyDestination(PdfObject dest, Map<PdfPage, PdfPage> page2page, PdfDocument toDocument) -
fillAndGetOcPropertiesDictionary
PdfDictionary fillAndGetOcPropertiesDictionary() -
isEqualSameNameDestExist
-
addOutlineToPage
-
addOutlineToPage
-