com.itextpdf.kernel.pdf.tagging

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".

Constructor Summary

Constructors

Constructor and 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

Modifier and Type	Method and Description
void	addAssociatedFile(PdfFileSpec fs) Adds file associated with structure tree root and identifies the relationship between them.
void	addAssociatedFile(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)
void	addNamespace(PdfNamespace namespace) Adds a PdfNamespace to the list of the namespaces used within the document.
void	addPronunciationLexicon(PdfFileSpec pronunciationLexiconFileSpec) Adds a single PdfFileSpec object, which specifies XML file conforming to PLS.
void	addRoleMapping(String fromRole, String toRole)
static PdfName	convertRoleToPdfName(String role)
void	copyTo(PdfDocument destDocument, int insertBeforePage, Map<PdfPage,PdfPage> page2page) Copies structure to a destDocument and insert it in a specified position in the document.
void	copyTo(PdfDocument destDocument, Map<PdfPage,PdfPage> page2page) Copies structure to a destDocument.
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()
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 a PdfStructIdTree object.
List<IStructureNode>	getKids() Gets list of the direct kids of StructTreeRoot.
PdfArray	getKidsObject()
List<PdfNamespace>	getNamespaces() Gets namespaces used within the document.
PdfArray	getNamespacesObject() An array of namespaces used within the document.
int	getNextMcidForPage(PdfPage page)
Collection<PdfMcr>	getPageMarkedContentReferences(PdfPage page) Gets an unmodifiable collection of marked content references on page.
IStructureNode	getParent()
int	getParentTreeNextKey()
List<PdfFileSpec>	getPronunciationLexiconsList() A List containing one or more PdfFileSpec 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()
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

Methods inherited from class java.lang.Object

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

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, use PdfDocument.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, use PdfDocument.getStructTreeRoot().

Parameters:

structTreeRootDict - a dictionary that defines document structure tree root

document - a document, which contains given structure tree root dictionary

Method Detail

convertRoleToPdfName

public static PdfName convertRoleToPdfName(String role)

addKid

public PdfStructElem addKid(PdfStructElem structElem)

addKid

public PdfStructElem addKid(int index,
                            PdfStructElem structElem)

getParent

public IStructureNode getParent()

Specified by:

getParent in interface IStructureNode

getKids

public List<IStructureNode> getKids()

Gets list of the direct kids of StructTreeRoot. If certain kid is flushed, there will be a null in the list on it's place.

Specified by:

getKids in interface IStructureNode

Returns:

list of the direct kids of StructTreeRoot.

getKidsObject

public PdfArray getKidsObject()

addRoleMapping

public void addRoleMapping(String fromRole,
                           String toRole)

getRoleMap

public PdfDictionary getRoleMap()

getNamespaces

public List<PdfNamespace> getNamespaces()

Gets namespaces used within the document. Essentially this method returns value of getNamespacesObject() wrapped in the PdfNamespace and List classes. Therefore limitations of the referred method are applied to this method too.

Returns:

a List of PdfNamespaces used within the document.

addNamespace

public void addNamespace(PdfNamespace namespace)

Adds a PdfNamespace 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 - a PdfNamespace 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 List<PdfFileSpec> getPronunciationLexiconsList()

A List containing one or more PdfFileSpec 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 more PdfFileSpec.

addPronunciationLexicon

public void addPronunciationLexicon(PdfFileSpec pronunciationLexiconFileSpec)

Adds a single PdfFileSpec object, which specifies XML file conforming to PLS. For more info see getPronunciationLexiconsList().

This value has meaning only for the PDF documents of version 2.0 and higher.

Parameters:

pronunciationLexiconFileSpec - a PdfFileSpec 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 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 interface IStructureNode

flush

public void flush()

Overrides:

flush in class PdfObjectWrapper<PdfDictionary>

copyTo

public void copyTo(PdfDocument destDocument,
                   Map<PdfPage,PdfPage> page2page)

Copies structure to a destDocument. NOTE: Works only for PdfStructTreeRoot 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,
                   Map<PdfPage,PdfPage> page2page)

Copies structure to a destDocument and insert it in a specified position in the document. NOTE: Works only for PdfStructTreeRoot 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 moved

insertBeforePage - 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(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 description

fs - 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 a PdfStructIdTree 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

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.