Package com.itextpdf.kernel.pdf.tagging

Class PdfStructTreeRoot

    • 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​(java.lang.String role)

      • getKids

        public java.util.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​(java.lang.String fromRole,
                           java.lang.String toRole)

      • getNamespaces

        public java.util.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 java.util.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 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

      • findObjRefByStructParentIndex

        public PdfObjRef findObjRefByStructParentIndex​(PdfDictionary pageDict,
                                               int structParentIndex)

      • copyTo

        public void copyTo​(PdfDocument destDocument,
                   java.util.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,
                   java.util.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)

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

      • 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 class PdfObjectWrapper<PdfDictionary>
        Returns:
        true if in the resultant document the object behind the wrapper must be indirect, otherwise false.

      • ifKidIsStructElementAddToList

        private void ifKidIsStructElementAddToList​(PdfObject kid,
                                           java.util.List<IStructureNode> kids)