Package 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 Details

    • 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 Details

    • 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)

    • findMcrByMcid

      public PdfMcr findMcrByMcid (PdfDocument document, 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.