Table of Contents

Class TagTreePointer

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

TagTreePointer class is used to modify the document's tag tree.

public class TagTreePointer
Inheritance
TagTreePointer
Inherited Members

Remarks

TagTreePointer class is used to modify the document's tag tree. At any given moment, instance of this class 'points' at the specific position in the tree (at the specific tag), however every instance can be freely moved around the tree primarily using MoveToKid(int) and MoveToParent() methods. For the current tag you can add new tags, modify it's role and properties, etc. Also, using instance of this class, you can change tag position in the tag structure, you can flush current tag or remove it.

There could be any number of the instances of this class, simultaneously pointing to different (or the same) parts of the tag structure. Because of this, you can for example remove the tag at which another instance is currently pointing. In this case, this another instance becomes invalid, and invocation of any method on it will result in exception. To make given instance valid again, use MoveToRoot() method.

Constructors

TagTreePointer(PdfDocument)

Creates TagTreePointer instance.

public TagTreePointer(PdfDocument document)

Parameters

document PdfDocument

the document, at which tag structure this instance will point.

Remarks

Creates TagTreePointer instance. After creation TagTreePointer points at the root tag.

The PdfNamespace for the new tags, which don't explicitly define namespace by the means of SetNamespace(PdfNamespace) , is set to the value returned by GetDocumentDefaultNamespace() on TagTreePointer creation. See also SetNamespaceForNewTags(PdfNamespace).

TagTreePointer(TagTreePointer)

A copy constructor.

public TagTreePointer(TagTreePointer tagPointer)

Parameters

tagPointer TagTreePointer

the TagTreePointer from which current position and page are copied.

Methods

AddAnnotationTag(PdfAnnotation)

Adds a new content item for the given PdfAnnotation under the current tag.

public virtual TagTreePointer AddAnnotationTag(PdfAnnotation annotation)

Parameters

annotation PdfAnnotation

PdfAnnotation to be tagged.

Returns

TagTreePointer

this TagTreePointer instance.

Remarks

Adds a new content item for the given PdfAnnotation under the current tag.

By default, when annotation is added to the page it is automatically tagged with auto tagging pointer (see GetAutoTaggingPointer() ). If you want to add annotation tag manually, be sure to use AddAnnotation(int, PdfAnnotation, bool) method with false for boolean flag.

AddTag(int, string)

Adds a new tag with given role to the tag structure.

public virtual TagTreePointer AddTag(int index, string role)

Parameters

index int

zero-based index in kids array of parent tag at which new tag will be added.

role string

role of the new tag.

Returns

TagTreePointer

this TagTreePointer instance.

Remarks

Adds a new tag with given role to the tag structure. This method call moves this TagTreePointer to the added kid.
This call is equivalent of calling sequentially SetNextNewKidIndex(int) and AddTag(string).

AddTag(int, AccessibilityProperties)

Adds a new tag to the tag structure.

public virtual TagTreePointer AddTag(int index, AccessibilityProperties properties)

Parameters

index int

zero-based index in kids array of parent tag at which new tag will be added.

properties AccessibilityProperties

accessibility properties which define a new tag role and other properties.

Returns

TagTreePointer

this TagTreePointer instance.

Remarks

Adds a new tag to the tag structure. This method call moves this TagTreePointer to the added kid.
New tag will have a role and attributes defined by the given AccessibilityProperties. This call is equivalent of calling sequentially SetNextNewKidIndex(int) and AddTag(AccessibilityProperties).

AddTag(string)

Adds a new tag with given role to the tag structure.

public virtual TagTreePointer AddTag(string role)

Parameters

role string

role of the new tag.

Returns

TagTreePointer

this TagTreePointer instance.

Remarks

Adds a new tag with given role to the tag structure. This method call moves this TagTreePointer to the added kid.

AddTag(AccessibilityProperties)

Adds a new tag to the tag structure.

public virtual TagTreePointer AddTag(AccessibilityProperties properties)

Parameters

properties AccessibilityProperties

accessibility properties which define a new tag role and other properties.

Returns

TagTreePointer

this TagTreePointer instance.

Remarks

Adds a new tag to the tag structure. This method call moves this TagTreePointer to the added kid.
New tag will have a role and attributes defined by the given AccessibilityProperties.

ApplyProperties(AccessibilityProperties)

Applies properties to the current tag.

public virtual void ApplyProperties(AccessibilityProperties properties)

Parameters

properties AccessibilityProperties

the properties to be applied to the current tag.

Remarks

Applies properties to the current tag.

FlushParentsIfAllKidsFlushed() 

public virtual TagTreePointer FlushParentsIfAllKidsFlushed()

Returns

TagTreePointer

FlushTag()

Flushes current tag and all it's descendants.

public virtual TagTreePointer FlushTag()

Returns

TagTreePointer

this TagTreePointer instance.

Remarks

Flushes current tag and all it's descendants. This method call moves this TagTreePointer to the current tag parent.

If some of the descendant tags of the current tag have waiting state (see WaitingTagsManager ), then these tags are considered as not yet finished ones, and they won't be flushed immediately, but they will be flushed, when waiting state is removed.

GetContext() 

public virtual TagStructureContext GetContext()

Returns

TagStructureContext

the TagStructureContext associated with the document to which this pointer belongs.

GetCurrentContentStream() 

public virtual PdfStream GetCurrentContentStream()

Returns

PdfStream

the content stream which content will be tagged with this instance of TagTreePointer.

GetCurrentPage() 

public virtual PdfPage GetCurrentPage()

Returns

PdfPage

a page which content will be tagged with this instance of TagTreePointer.

GetDocument() 

public virtual PdfDocument GetDocument()

Returns

PdfDocument

the document, at which tag structure this instance points.

GetIndexInParentKidsList()

Defines index of the current tag in the parent's kids list.

public virtual int GetIndexInParentKidsList()

Returns

int

returns index of the current tag in the parent's kids list, or -1 if either current tag is a root tag, parent is flushed or it wasn't possible to define index.

GetKidsRoles()

Gets current tag kids roles.

public virtual IList<string> GetKidsRoles()

Returns

IList<string>

current tag kids roles

Remarks

Gets current tag kids roles. If certain kid is already flushed, at its position there will be a null. If kid is a content item, at it's position there will be "MCR" string literal (stands for Marked Content Reference).

GetNamespaceForNewTags()

Gets a PdfNamespace which will be set to every new tag created by this TagTreePointer instance.

public virtual PdfNamespace GetNamespaceForNewTags()

Returns

PdfNamespace

a PdfNamespace which is to be set for the new tags created, or null if one is not defined.

See Also

GetProperties()

Gets accessibility properties of the current tag.

public virtual AccessibilityProperties GetProperties()

Returns

AccessibilityProperties

accessibility properties of the current tag.

GetRole()

Gets current tag role.

public virtual string GetRole()

Returns

string

current tag role.

GetTagReference()

Creates a reference to the current tag, which could be used to associate a content on the PdfCanvas with current tag.

public virtual TagReference GetTagReference()

Returns

TagReference

the reference to the current tag.

Remarks

Creates a reference to the current tag, which could be used to associate a content on the PdfCanvas with current tag. See OpenTag(TagReference) and SetPageForTagging(PdfPage).

GetTagReference(int)

Creates a reference to the current tag, which could be used to associate a content on the PdfCanvas with current tag.

public virtual TagReference GetTagReference(int index)

Parameters

index int

zero-based index in kids array of tag. These indexes define the logical order of the content on the page.

Returns

TagReference

the reference to the current tag.

Remarks

Creates a reference to the current tag, which could be used to associate a content on the PdfCanvas with current tag. See OpenTag(TagReference) and SetPageForTagging(PdfPage).

IsPointingToSameTag(TagTreePointer)

Checks if this TagTreePointer is pointing at the same tag as the giving TagTreePointer.

public virtual bool IsPointingToSameTag(TagTreePointer otherPointer)

Parameters

otherPointer TagTreePointer

a TagTreePointer which is checked against this instance on whether they point at the same tag.

Returns

bool

true if both TagTreePointer instances point at the same tag, false otherwise.

MoveToKid(int)

Moves this TagTreePointer instance to the kid of the current tag.

public virtual TagTreePointer MoveToKid(int kidIndex)

Parameters

kidIndex int

zero-based index of the current tag kid to which pointer will be moved.

Returns

TagTreePointer

this TagTreePointer instance.

MoveToKid(int, string)

Moves this TagTreePointer instance to the nth descendant of the current tag which has the given role.

public virtual TagTreePointer MoveToKid(int n, string role)

Parameters

n int

if there are several descendants with the given role, pointer will be moved to the descendant which has zero-based index n if you count only the descendants with the given role in BFS order.

role string

role of the current tag descendant to which pointer will be moved.

Returns

TagTreePointer

this TagTreePointer instance.

Remarks

Moves this TagTreePointer instance to the nth descendant of the current tag which has the given role. If there are no direct kids of the tag with such role, further descendants are checked in BFS order.

MoveToKid(string)

Moves this TagTreePointer instance to the first descendant of the current tag which has the given role.

public virtual TagTreePointer MoveToKid(string role)

Parameters

role string

role of the current tag descendant to which pointer will be moved. If there are several descendants with this role, pointer will be moved to the first kid with such role in BFS order.

Returns

TagTreePointer

this TagTreePointer instance.

Remarks

Moves this TagTreePointer instance to the first descendant of the current tag which has the given role. If there are no direct kids of the tag with such role, further descendants are checked in BFS order.

MoveToParent()

Moves this TagTreePointer instance to the parent of the current tag.

public virtual TagTreePointer MoveToParent()

Returns

TagTreePointer

this TagTreePointer instance.

MoveToPointer(TagTreePointer)

Moves this TagTreePointer instance to the tag at which given TagTreePointer instance is pointing.

public virtual TagTreePointer MoveToPointer(TagTreePointer tagTreePointer)

Parameters

tagTreePointer TagTreePointer

a TagTreePointer that points at the tag which will become the current tag of this instance.

Returns

TagTreePointer

this TagTreePointer instance.

MoveToRoot()

Moves this TagTreePointer instance to the document root tag.

public virtual TagTreePointer MoveToRoot()

Returns

TagTreePointer

this TagTreePointer instance.

Relocate(TagTreePointer)

Moves current tag to the tag at which given TagTreePointer points.

public virtual TagTreePointer Relocate(TagTreePointer pointerToNewParent)

Parameters

pointerToNewParent TagTreePointer

the TagTreePointer which is positioned at the tag which will become current tag new parent.

Returns

TagTreePointer

this TagTreePointer instance.

Remarks

Moves current tag to the tag at which given TagTreePointer points. This method doesn't change either this instance or pointerToNewParent position.

RelocateKid(int, TagTreePointer)

Moves kid of the current tag to the tag at which given TagTreePointer points.

public virtual TagTreePointer RelocateKid(int kidIndex, TagTreePointer pointerToNewParent)

Parameters

kidIndex int

zero-based index of the current tag's kid to be relocated.

pointerToNewParent TagTreePointer

the TagTreePointer which is positioned at the tag which will become kid's new parent.

Returns

TagTreePointer

this TagTreePointer instance.

Remarks

Moves kid of the current tag to the tag at which given TagTreePointer points. This method doesn't change neither this instance nor pointerToNewParent position.

RemoveTag()

Removes the current tag.

public virtual TagTreePointer RemoveTag()

Returns

TagTreePointer

this TagStructureContext instance.

Remarks

Removes the current tag. If it has kids, they will become kids of the current tag parent. This method call moves this TagTreePointer to the current tag parent.

You cannot remove root tag, and also you cannot remove the tag if it's parent is already flushed; in this two cases an exception will be thrown.

SetContentStreamForTagging(PdfStream)

Sometimes, tags are desired to be connected with the content that resides not in the page's content stream, but rather in the some appearance stream or in the form xObject stream.

public virtual TagTreePointer SetContentStreamForTagging(PdfStream contentStream)

Parameters

contentStream PdfStream

the content stream which content will be tagged with this instance of TagTreePointer or null if content stream tagging is finished

Returns

TagTreePointer

current TagTreePointer instance

Remarks

Sometimes, tags are desired to be connected with the content that resides not in the page's content stream, but rather in the some appearance stream or in the form xObject stream. In that case, to have a valid tag structure, one shall set not only the page, on which the content will be rendered, but also the content stream in which the tagged content will reside.

NOTE: It's important to set a null for this value, when tagging of this stream content is finished.

SetNamespaceForNewTags(PdfNamespace)

Sets a PdfNamespace which will be set to every new tag created by this TagTreePointer instance if this tag doesn't explicitly define namespace by the means of SetNamespace(PdfNamespace).

public virtual TagTreePointer SetNamespaceForNewTags(PdfNamespace @namespace)

Parameters

namespace PdfNamespace

a PdfNamespace to be set for the new tags created. If set to null - new tags will have a namespace set only if it is defined in the corresponding AccessibilityProperties.

Returns

TagTreePointer

this TagTreePointer instance.

Remarks

Sets a PdfNamespace which will be set to every new tag created by this TagTreePointer instance if this tag doesn't explicitly define namespace by the means of SetNamespace(PdfNamespace).

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

It's highly recommended to acquire PdfNamespace class instances via FetchNamespace(string).
See Also

SetNextNewKidIndex(int)

Sets index of the next added to the current tag kid, which could be another tag or content item.

public virtual TagTreePointer SetNextNewKidIndex(int nextNewKidIndex)

Parameters

nextNewKidIndex int

index of the next added kid.

Returns

TagTreePointer

this TagTreePointer instance.

Remarks

Sets index of the next added to the current tag kid, which could be another tag or content item. By default, new tag is added at the end of the parent kids array. This property affects only the next added tag, all tags added after will be added with the default behaviour.

This method could be used with any overload of AddTag(string) method, with RelocateKid(int, TagTreePointer) and AddAnnotationTag(PdfAnnotation).
Keep in mind, that this method set property to the TagTreePointer and not to the tag itself, which means that if you would move the pointer, this property would be applied to the new current tag.

SetPageForTagging(PdfPage)

Sets a page which content will be tagged with this instance of TagTreePointer.

public virtual TagTreePointer SetPageForTagging(PdfPage page)

Parameters

page PdfPage

the page which content will be tagged with this instance of TagTreePointer.

Returns

TagTreePointer

this TagTreePointer instance.

Remarks

Sets a page which content will be tagged with this instance of TagTreePointer. To tag page content:

  1. Set pointer position to the tag which will be the parent of the page content item;
  2. Call GetTagReference() to obtain the reference to the current tag;
  3. Pass TagReference to the OpenTag(TagReference) method of the page's PdfCanvas to start marked content item;
  4. Draw content on PdfCanvas ;
  5. Use CloseTag() to finish marked content item.

SetRole(string)

Sets new role to the current tag.

public virtual TagTreePointer SetRole(string role)

Parameters

role string

new role to be set.

Returns

TagTreePointer

this TagTreePointer instance.