Class PdfStructTreeRoot
- java.lang.Object
-
- com.itextpdf.kernel.pdf.PdfObjectWrapper<PdfDictionary>
-
- com.itextpdf.kernel.pdf.tagging.PdfStructTreeRoot
-
- All Implemented Interfaces:
IStructureNode
public class PdfStructTreeRoot extends PdfObjectWrapper<PdfDictionary> implements IStructureNode
Represents a wrapper-class for structure tree root dictionary. See ISO-32000-1 "14.7.2 Structure hierarchy".
-
-
Field Summary
Fields Modifier and Type Field Description private PdfDocument
document
private PdfStructIdTree
idTree
private ParentTreeHandler
parentTreeHandler
private static java.util.Map<java.lang.String,PdfName>
staticRoleNames
-
Constructor Summary
Constructors Constructor Description PdfStructTreeRoot(PdfDictionary structTreeRootDict, PdfDocument document)
Creates wrapper instance for already existing logical structure tree root in the document.PdfStructTreeRoot(PdfDocument document)
Creates a new structure tree root instance, this initializes empty logical structure in the document.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addAssociatedFile(PdfFileSpec fs)
Adds file associated with structure tree root and identifies the relationship between them.void
addAssociatedFile(java.lang.String description, PdfFileSpec fs)
Adds file associated with structure tree root and identifies the relationship between them.PdfStructElem
addKid(int index, PdfStructElem structElem)
PdfStructElem
addKid(PdfStructElem structElem)
(package private) void
addKidObject(int index, PdfDictionary structElem)
void
addNamespace(PdfNamespace namespace)
Adds aPdfNamespace
to the list of the namespaces used within the document.void
addPronunciationLexicon(PdfFileSpec pronunciationLexiconFileSpec)
Adds a singlePdfFileSpec
object, which specifies XML file conforming to PLS.void
addRoleMapping(java.lang.String fromRole, java.lang.String toRole)
static PdfName
convertRoleToPdfName(java.lang.String role)
void
copyTo(PdfDocument destDocument, int insertBeforePage, java.util.Map<PdfPage,PdfPage> page2page)
Copies structure to adestDocument
and insert it in a specified position in the document.void
copyTo(PdfDocument destDocument, java.util.Map<PdfPage,PdfPage> page2page)
Copies structure to adestDocument
.void
createParentTreeEntryForPage(PdfPage page)
Creates and flushes parent tree entry for the page.PdfMcr
findMcrByMcid(PdfDictionary pageDict, int mcid)
PdfObjRef
findObjRefByStructParentIndex(PdfDictionary pageDict, int structParentIndex)
void
flush()
private static void
flushAllKids(PdfStructTreeRoot elem)
PdfArray
getAssociatedFiles(boolean create)
Returns files associated with structure tree root.PdfDocument
getDocument()
PdfStructIdTree
getIdTree()
Returns the document's structure element ID tree wrapped in aPdfStructIdTree
object.java.util.List<IStructureNode>
getKids()
Gets list of the direct kids of StructTreeRoot.PdfArray
getKidsObject()
java.util.List<PdfNamespace>
getNamespaces()
Gets namespaces used within the document.PdfArray
getNamespacesObject()
An array of namespaces used within the document.int
getNextMcidForPage(PdfPage page)
java.util.Collection<PdfMcr>
getPageMarkedContentReferences(PdfPage page)
Gets an unmodifiable collection of marked content references on page.IStructureNode
getParent()
(package private) ParentTreeHandler
getParentTreeHandler()
int
getParentTreeNextKey()
java.util.List<PdfFileSpec>
getPronunciationLexiconsList()
AList
containing one or morePdfFileSpec
objects, where each specified file is a pronunciation lexicon, which is an XML file conforming to the Pronunciation Lexicon Specification (PLS) Version 1.0.PdfName
getRole()
PdfDictionary
getRoleMap()
private void
ifKidIsStructElementAddToList(PdfObject kid, java.util.List<IStructureNode> kids)
protected boolean
isWrappedObjectMustBeIndirect()
Defines if the object behind this wrapper must be an indirect object in the resultant document.void
move(PdfPage fromPage, int insertBeforePage)
Moves structure associated with specified page and insert it in a specified position in the document.void
savePageStructParentIndexIfNeeded(PdfPage page)
-
Methods inherited from class com.itextpdf.kernel.pdf.PdfObjectWrapper
ensureObjectIsAddedToDocument, ensureUnderlyingObjectHasIndirectReference, getPdfObject, isFlushed, makeIndirect, makeIndirect, markObjectAsIndirect, setForbidRelease, setModified, setPdfObject, unsetForbidRelease
-
-
-
-
Field Detail
-
document
private PdfDocument document
-
parentTreeHandler
private ParentTreeHandler parentTreeHandler
-
idTree
private PdfStructIdTree idTree
-
staticRoleNames
private static java.util.Map<java.lang.String,PdfName> staticRoleNames
-
-
Constructor Detail
-
PdfStructTreeRoot
public PdfStructTreeRoot(PdfDocument document)
Creates a new structure tree root instance, this initializes empty logical structure in the document. This class also handles global state of parent tree, so it's not expected to create multiple instances of this class. Instead, usePdfDocument.getStructTreeRoot()
.- Parameters:
document
- a document to which new instance of struct tree root will be bound
-
PdfStructTreeRoot
public PdfStructTreeRoot(PdfDictionary structTreeRootDict, PdfDocument document)
Creates wrapper instance for already existing logical structure tree root in the document. This class also handles global state of parent tree, so it's not expected to create multiple instances of this class. Instead, usePdfDocument.getStructTreeRoot()
.- Parameters:
structTreeRootDict
- a dictionary that defines document structure tree rootdocument
- a document, which contains given structure tree root dictionary
-
-
Method Detail
-
convertRoleToPdfName
public static PdfName convertRoleToPdfName(java.lang.String role)
-
addKid
public PdfStructElem addKid(PdfStructElem structElem)
-
addKid
public PdfStructElem addKid(int index, PdfStructElem structElem)
-
getParent
public IStructureNode getParent()
- Specified by:
getParent
in interfaceIStructureNode
-
getKids
public java.util.List<IStructureNode> getKids()
Gets list of the direct kids of StructTreeRoot. If certain kid is flushed, there will be anull
in the list on it's place.- Specified by:
getKids
in interfaceIStructureNode
- Returns:
- list of the direct kids of StructTreeRoot.
-
getKidsObject
public PdfArray getKidsObject()
-
addRoleMapping
public void addRoleMapping(java.lang.String fromRole, java.lang.String toRole)
-
getRoleMap
public PdfDictionary getRoleMap()
-
getNamespaces
public java.util.List<PdfNamespace> getNamespaces()
Gets namespaces used within the document. Essentially this method returns value ofgetNamespacesObject()
wrapped in thePdfNamespace
andList
classes. Therefore limitations of the referred method are applied to this method too.- Returns:
- a
List
ofPdfNamespace
s used within the document.
-
addNamespace
public void addNamespace(PdfNamespace namespace)
Adds aPdfNamespace
to the list of the namespaces used within the document.This value has meaning only for the PDF documents of version 2.0 and higher.
- Parameters:
namespace
- aPdfNamespace
to be added.
-
getNamespacesObject
public PdfArray getNamespacesObject()
An array of namespaces used within the document. This value, however, is not automatically updated while the document is processed. It identifies only the namespaces that were in the document at the moment of it's opening.- Returns:
PdfArray
of namespaces used within the document.
-
getPronunciationLexiconsList
public java.util.List<PdfFileSpec> getPronunciationLexiconsList()
AList
containing one or morePdfFileSpec
objects, where each specified file is a pronunciation lexicon, which is an XML file conforming to the Pronunciation Lexicon Specification (PLS) Version 1.0. These pronunciation lexicons may be used as pronunciation hints when the document’s content is presented via text-to-speech. Where two or more pronunciation lexicons apply to the same text, the first match – as defined by the order of entries in the array and the order of entries inside the pronunciation lexicon file – should be used.See ISO 32000-2 14.9.6, "Pronunciation hints".
- Returns:
- A
List
containing one or morePdfFileSpec
.
-
addPronunciationLexicon
public void addPronunciationLexicon(PdfFileSpec pronunciationLexiconFileSpec)
Adds a singlePdfFileSpec
object, which specifies XML file conforming to PLS. For more info seegetPronunciationLexiconsList()
.This value has meaning only for the PDF documents of version 2.0 and higher.
- Parameters:
pronunciationLexiconFileSpec
- aPdfFileSpec
object, which specifies XML file conforming to PLS.
-
createParentTreeEntryForPage
public void createParentTreeEntryForPage(PdfPage page)
Creates and flushes parent tree entry for the page. Effectively this means that new content mustn't be added to the page.- Parameters:
page
-PdfPage
for which to create parent tree entry. Typically this page is flushed after this call.
-
savePageStructParentIndexIfNeeded
public void savePageStructParentIndexIfNeeded(PdfPage page)
-
getPageMarkedContentReferences
public java.util.Collection<PdfMcr> getPageMarkedContentReferences(PdfPage page)
Gets an unmodifiable collection of marked content references on page. NOTE: Do not remove tags when iterating over returned collection, this could lead to the ConcurrentModificationException, because returned collection is backed by the internal list of the actual page tags.- Parameters:
page
-PdfPage
to obtain unmodifiable collection of marked content references- Returns:
- the unmodifiable collection of marked content references on page, if no Mcrs defined returns null
-
findMcrByMcid
public PdfMcr findMcrByMcid(PdfDictionary pageDict, int mcid)
-
findObjRefByStructParentIndex
public PdfObjRef findObjRefByStructParentIndex(PdfDictionary pageDict, int structParentIndex)
-
getRole
public PdfName getRole()
- Specified by:
getRole
in interfaceIStructureNode
-
flush
public void flush()
- Overrides:
flush
in classPdfObjectWrapper<PdfDictionary>
-
copyTo
public void copyTo(PdfDocument destDocument, java.util.Map<PdfPage,PdfPage> page2page)
Copies structure to adestDocument
. NOTE: Works only forPdfStructTreeRoot
that is read from the document opened in reading mode, otherwise an exception is thrown.- Parameters:
destDocument
- document to copy structure to. Shall not be current document.page2page
- association between original page and copied page.
-
copyTo
public void copyTo(PdfDocument destDocument, int insertBeforePage, java.util.Map<PdfPage,PdfPage> page2page)
Copies structure to adestDocument
and insert it in a specified position in the document. NOTE: Works only forPdfStructTreeRoot
that is read from the document opened in reading mode, otherwise an exception is thrown.- Parameters:
destDocument
- document to copy structure to.insertBeforePage
- indicates where the structure to be inserted.page2page
- association between original page and copied page.
-
move
public void move(PdfPage fromPage, int insertBeforePage)
Moves structure associated with specified page and insert it in a specified position in the document.NOTE: Works only for document with not flushed pages.
- Parameters:
fromPage
- page which tag structure will be movedinsertBeforePage
- indicates before tags of which page tag structure will be moved to
-
getParentTreeNextKey
public int getParentTreeNextKey()
-
getNextMcidForPage
public int getNextMcidForPage(PdfPage page)
-
getDocument
public PdfDocument getDocument()
-
addAssociatedFile
public void addAssociatedFile(java.lang.String description, PdfFileSpec fs)
Adds file associated with structure tree root and identifies the relationship between them.Associated files may be used in Pdf/A-3 and Pdf 2.0 documents. The method adds file to array value of the AF key in the structure tree root dictionary. If description is provided, it also will add file description to catalog Names tree.
For associated files their associated file specification dictionaries shall include the AFRelationship key
- Parameters:
description
- the file descriptionfs
- file specification dictionary of associated file
-
addAssociatedFile
public void addAssociatedFile(PdfFileSpec fs)
Adds file associated with structure tree root and identifies the relationship between them.
Associated files may be used in Pdf/A-3 and Pdf 2.0 documents. The method adds file to array value of the AF key in the structure tree root dictionary.
For associated files their associated file specification dictionaries shall include the AFRelationship key
- Parameters:
fs
- file specification dictionary of associated file
-
getAssociatedFiles
public PdfArray getAssociatedFiles(boolean create)
Returns files associated with structure tree root.- Parameters:
create
- defines whether AF arrays will be created if it doesn't exist- Returns:
- associated files array
-
getIdTree
public PdfStructIdTree getIdTree()
Returns the document's structure element ID tree wrapped in aPdfStructIdTree
object. If no such tree exists, it is initialized. The initialization happens lazily, and does not trigger any PDF object changes unless populated.- Returns:
- the
PdfStructIdTree
of the document
-
getParentTreeHandler
ParentTreeHandler getParentTreeHandler()
-
addKidObject
void addKidObject(int index, PdfDictionary structElem)
-
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.
-
flushAllKids
private static void flushAllKids(PdfStructTreeRoot elem)
-
ifKidIsStructElementAddToList
private void ifKidIsStructElementAddToList(PdfObject kid, java.util.List<IStructureNode> kids)
-
-