Table of Contents

Class PdfStructTreeRoot

Namespace
iText.Kernel.Pdf.Tagging
Assembly
itext.kernel.dll

Represents a wrapper-class for structure tree root dictionary.

public class PdfStructTreeRoot : PdfObjectWrapper<PdfDictionary>, IStructureNode
Inheritance
PdfStructTreeRoot
Implements
Inherited Members

Remarks

Represents a wrapper-class for structure tree root dictionary. See ISO-32000-1 "14.7.2 Structure hierarchy".

Constructors

PdfStructTreeRoot(PdfDictionary, PdfDocument)

Creates wrapper instance for already existing logical structure tree root in the document.

public PdfStructTreeRoot(PdfDictionary structTreeRootDict, PdfDocument document)

Parameters

structTreeRootDict PdfDictionary

a dictionary that defines document structure tree root

document PdfDocument

a document, which contains given structure tree root dictionary

Remarks

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 GetStructTreeRoot().

PdfStructTreeRoot(PdfDocument)

Creates a new structure tree root instance, this initializes empty logical structure in the document.

public PdfStructTreeRoot(PdfDocument document)

Parameters

document PdfDocument

a document to which new instance of struct tree root will be bound

Remarks

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 GetStructTreeRoot().

Methods

AddAssociatedFile(string, PdfFileSpec)

Adds file associated with structure tree root and identifies the relationship between them.

public virtual void AddAssociatedFile(string description, PdfFileSpec fs)

Parameters

description string

the file description

fs PdfFileSpec

file specification dictionary of associated file

Remarks

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

AddAssociatedFile(PdfFileSpec)

Adds file associated with structure tree root and identifies the relationship between them. 
public virtual void AddAssociatedFile(PdfFileSpec fs)

Parameters

fs PdfFileSpec

file specification dictionary of associated file

Remarks

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

AddKid(int, PdfStructElem) 

public virtual PdfStructElem AddKid(int index, PdfStructElem structElem)

Parameters

index int
structElem PdfStructElem

Returns

PdfStructElem

AddKid(PdfStructElem) 

public virtual PdfStructElem AddKid(PdfStructElem structElem)

Parameters

structElem PdfStructElem

Returns

PdfStructElem

AddNamespace(PdfNamespace)

Adds a PdfNamespace to the list of the namespaces used within the document.

public virtual void AddNamespace(PdfNamespace @namespace)

Parameters

namespace PdfNamespace

a PdfNamespace to be added.

Remarks

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.

AddPronunciationLexicon(PdfFileSpec)

Adds a single PdfFileSpec object, which specifies XML file conforming to PLS.

public virtual void AddPronunciationLexicon(PdfFileSpec pronunciationLexiconFileSpec)

Parameters

pronunciationLexiconFileSpec PdfFileSpec

a PdfFileSpec object, which specifies XML file conforming to PLS.

Remarks

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.

AddRoleMapping(string, string) 

public virtual void AddRoleMapping(string fromRole, string toRole)

Parameters

fromRole string
toRole string

ConvertRoleToPdfName(string) 

public static PdfName ConvertRoleToPdfName(string role)

Parameters

role string

Returns

PdfName

CopyTo(PdfDocument, IDictionary<PdfPage, PdfPage>)

Copies structure to a destDocument.

public virtual void CopyTo(PdfDocument destDocument, IDictionary<PdfPage, PdfPage> page2page)

Parameters

destDocument PdfDocument

document to copy structure to. Shall not be current document.

page2page IDictionary<PdfPage, PdfPage>

association between original page and copied page.

Remarks

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.

CopyTo(PdfDocument, int, IDictionary<PdfPage, PdfPage>)

Copies structure to a destDocument and insert it in a specified position in the document.

public virtual void CopyTo(PdfDocument destDocument, int insertBeforePage, IDictionary<PdfPage, PdfPage> page2page)

Parameters

destDocument PdfDocument

document to copy structure to.

insertBeforePage int

indicates where the structure to be inserted.

page2page IDictionary<PdfPage, PdfPage>

association between original page and copied page.

Remarks

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.

CreateParentTreeEntryForPage(PdfPage)

Creates and flushes parent tree entry for the page.

public virtual void CreateParentTreeEntryForPage(PdfPage page)

Parameters

page PdfPage

PdfPage for which to create parent tree entry. Typically this page is flushed after this call.

Remarks

Creates and flushes parent tree entry for the page. Effectively this means that new content mustn't be added to the page.

FindMcrByMcid(PdfDictionary, int) 

public virtual PdfMcr FindMcrByMcid(PdfDictionary pageDict, int mcid)

Parameters

pageDict PdfDictionary
mcid int

Returns

PdfMcr

FindMcrByMcid(PdfDocument, int) 

public virtual PdfMcr FindMcrByMcid(PdfDocument document, int mcid)

Parameters

document PdfDocument
mcid int

Returns

PdfMcr

FindObjRefByStructParentIndex(PdfDictionary, int) 

public virtual PdfObjRef FindObjRefByStructParentIndex(PdfDictionary pageDict, int structParentIndex)

Parameters

pageDict PdfDictionary
structParentIndex int

Returns

PdfObjRef

Flush() 

public override void Flush()

GetAssociatedFiles(bool)

Returns files associated with structure tree root.

public virtual PdfArray GetAssociatedFiles(bool create)

Parameters

create bool

defines whether AF arrays will be created if it doesn't exist

Returns

PdfArray

associated files array

GetDocument() 

public virtual PdfDocument GetDocument()

Returns

PdfDocument

GetIdTree()

Returns the document's structure element ID tree wrapped in a PdfStructIdTree object.

public virtual PdfStructIdTree GetIdTree()

Returns

PdfStructIdTree

the PdfStructIdTree of the document

Remarks

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.

GetKids()

Gets list of the direct kids of StructTreeRoot.

public virtual IList<IStructureNode> GetKids()

Returns

IList<IStructureNode>

list of the direct kids of StructTreeRoot.

Remarks

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.

GetKidsObject() 

public virtual PdfArray GetKidsObject()

Returns

PdfArray

GetNamespaces()

Gets namespaces used within the document.

public virtual IList<PdfNamespace> GetNamespaces()

Returns

IList<PdfNamespace>

a of PdfNamespace s used within the document.

Remarks

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

GetNamespacesObject()

An array of namespaces used within the document.

public virtual PdfArray GetNamespacesObject()

Returns

PdfArray

PdfArray of namespaces used within the document.

Remarks

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.

GetNextMcidForPage(PdfPage) 

public virtual int GetNextMcidForPage(PdfPage page)

Parameters

page PdfPage

Returns

int

GetPageMarkedContentReferences(PdfPage)

Gets an unmodifiable collection of marked content references on page.

public virtual ICollection<PdfMcr> GetPageMarkedContentReferences(PdfPage page)

Parameters

page PdfPage

PdfPage to obtain unmodifiable collection of marked content references

Returns

ICollection<PdfMcr>

the unmodifiable collection of marked content references on page, if no Mcrs defined returns null

Remarks

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.

GetParent() 

public virtual IStructureNode GetParent()

Returns

IStructureNode

GetParentTreeNextKey() 

public virtual int GetParentTreeNextKey()

Returns

int

GetPronunciationLexiconsList()

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

public virtual IList<PdfFileSpec> GetPronunciationLexiconsList()

Returns

IList<PdfFileSpec>

A containing one or more PdfFileSpec.

Remarks

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

GetRole() 

public virtual PdfName GetRole()

Returns

PdfName

GetRoleMap() 

public virtual PdfDictionary GetRoleMap()

Returns

PdfDictionary

IsWrappedObjectMustBeIndirect() 

protected override bool IsWrappedObjectMustBeIndirect()

Returns

bool

Move(PdfPage, int)

Moves structure associated with specified page and insert it in a specified position in the document.

public virtual void Move(PdfPage fromPage, int insertBeforePage)

Parameters

fromPage PdfPage

page which tag structure will be moved

insertBeforePage int

indicates before tags of which page tag structure will be moved to

Remarks

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.

SavePageStructParentIndexIfNeeded(PdfPage) 

public virtual void SavePageStructParentIndexIfNeeded(PdfPage page)

Parameters

page PdfPage