TagTreePointer (iText 7 - kernel 7.2.5 API)

java.lang.Object
- com.itextpdf.kernel.pdf.tagutils.TagTreePointer

```
public class TagTreePointer
extends Object
```
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.

Constructor Summary

Constructors
Constructor and Description

TagTreePointer(PdfDocument document)
Creates TagTreePointer instance.

TagTreePointer(TagTreePointer tagPointer)
A copy constructor.

Constructors
Constructor and Description
`TagTreePointer(PdfDocument document)` Creates `TagTreePointer` instance.
`TagTreePointer(TagTreePointer tagPointer)` A copy constructor.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`TagTreePointer`	`addAnnotationTag(PdfAnnotation annotation)` Adds a new content item for the given `PdfAnnotation` under the current tag.
`TagTreePointer`	`addTag(AccessibilityProperties properties)` Adds a new tag to the tag structure.
`TagTreePointer`	`addTag(int index, AccessibilityProperties properties)` Adds a new tag to the tag structure.
`TagTreePointer`	`addTag(int index, String role)` Adds a new tag with given role to the tag structure.
`TagTreePointer`	`addTag(String role)` Adds a new tag with given role to the tag structure.
`TagTreePointer`	`flushParentsIfAllKidsFlushed()` For current tag and all of it's parents consequentially checks if the following constraints apply, and flushes the tag if they do or stops if they don't: tag is not already flushed; tag is not in waiting state (see `WaitingTagsManager`); tag is not the root tag; tag has no kids or all of the kids are either flushed themselves or (if they are a marked content reference) belong to the flushed page.
`TagTreePointer`	`flushTag()` Flushes current tag and all it's descendants.
`TagStructureContext`	`getContext()`
`PdfStream`	`getCurrentContentStream()`
`PdfPage`	`getCurrentPage()`
`PdfDocument`	`getDocument()`
`int`	`getIndexInParentKidsList()` Defines index of the current tag in the parent's kids list.
`List<String>`	`getKidsRoles()` Gets current tag kids roles.
`PdfNamespace`	`getNamespaceForNewTags()` Gets a `PdfNamespace` which will be set to every new tag created by this `TagTreePointer` instance.
`AccessibilityProperties`	`getProperties()` Gets accessibility properties of the current tag.
`String`	`getRole()` Gets current tag role.
`TagReference`	`getTagReference()` Creates a reference to the current tag, which could be used to associate a content on the PdfCanvas with current tag.
`TagReference`	`getTagReference(int index)` Creates a reference to the current tag, which could be used to associate a content on the PdfCanvas with current tag.
`boolean`	`isPointingToSameTag(TagTreePointer otherPointer)` Checks if this `TagTreePointer` is pointing at the same tag as the giving `TagTreePointer`.
`TagTreePointer`	`moveToKid(int kidIndex)` Moves this `TagTreePointer` instance to the kid of the current tag.
`TagTreePointer`	`moveToKid(int n, String role)` Moves this `TagTreePointer` instance to the nth descendant of the current tag which has the given role.
`TagTreePointer`	`moveToKid(String role)` Moves this `TagTreePointer` instance to the first descendant of the current tag which has the given role.
`TagTreePointer`	`moveToParent()` Moves this `TagTreePointer` instance to the parent of the current tag.
`TagTreePointer`	`moveToPointer(TagTreePointer tagTreePointer)` Moves this `TagTreePointer` instance to the tag at which given `TagTreePointer` instance is pointing.
`TagTreePointer`	`moveToRoot()` Moves this `TagTreePointer` instance to the document root tag.
`TagTreePointer`	`relocate(TagTreePointer pointerToNewParent)` Moves current tag to the tag at which given `TagTreePointer` points.
`TagTreePointer`	`relocateKid(int kidIndex, TagTreePointer pointerToNewParent)` Moves kid of the current tag to the tag at which given `TagTreePointer` points.
`TagTreePointer`	`removeTag()` Removes the current tag.
`TagTreePointer`	`setContentStreamForTagging(PdfStream contentStream)` 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.
`TagTreePointer`	`setNamespaceForNewTags(PdfNamespace namespace)` 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 `DefaultAccessibilityProperties.setNamespace(PdfNamespace)`.
`TagTreePointer`	`setNextNewKidIndex(int nextNewKidIndex)` Sets index of the next added to the current tag kid, which could be another tag or content item.
`TagTreePointer`	`setPageForTagging(PdfPage page)` Sets a page which content will be tagged with this instance of `TagTreePointer`.
`TagTreePointer`	`setRole(String role)` Sets new role to the current tag.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - TagTreePointer
```
public TagTreePointer(PdfDocument document)
```
    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 DefaultAccessibilityProperties.setNamespace(PdfNamespace), is set to the value returned by TagStructureContext.getDocumentDefaultNamespace() on TagTreePointer creation. See also setNamespaceForNewTags(PdfNamespace).
    
    Parameters:
    
    document - the document, at which tag structure this instance will point.
  - TagTreePointer
```
public TagTreePointer(TagTreePointer tagPointer)
```
    A copy constructor.
    
    Parameters:
    
    tagPointer - the TagTreePointer from which current position and page are copied.
- Method Detail
  - setPageForTagging
```
public TagTreePointer setPageForTagging(PdfPage page)
```
    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 PdfCanvas.openTag(TagReference) method of the page's PdfCanvas to start marked content item;
    4. Draw content on PdfCanvas;
    5. Use PdfCanvas.closeTag() to finish marked content item.
    Parameters:
    
    page - the page which content will be tagged with this instance of TagTreePointer.
    
    Returns:
    
    this TagTreePointer instance.
  - getCurrentPage
```
public PdfPage getCurrentPage()
```
    Returns:
    
    a page which content will be tagged with this instance of TagTreePointer.
  - setContentStreamForTagging
```
public TagTreePointer setContentStreamForTagging(PdfStream contentStream)
```
    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.
    
    Parameters:
    
    contentStream - the content stream which content will be tagged with this instance of TagTreePointer or null if content stream tagging is finished
    
    Returns:
    
    current TagTreePointer instance
  - getCurrentContentStream
```
public PdfStream getCurrentContentStream()
```
    Returns:
    
    the content stream which content will be tagged with this instance of TagTreePointer.
  - getContext
```
public TagStructureContext getContext()
```
    Returns:
    
    the TagStructureContext associated with the document to which this pointer belongs.
  - getDocument
```
public PdfDocument getDocument()
```
    Returns:
    
    the document, at which tag structure this instance points.
  - setNamespaceForNewTags
```
public TagTreePointer setNamespaceForNewTags(PdfNamespace namespace)
```
    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 DefaultAccessibilityProperties.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 TagStructureContext.fetchNamespace(String).
    
    Parameters:
    
    namespace - 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:
    
    this TagTreePointer instance.
    
    See Also:
    
    TagStructureContext.fetchNamespace(String)
  - getNamespaceForNewTags
```
public PdfNamespace getNamespaceForNewTags()
```
    Gets a PdfNamespace which will be set to every new tag created by this TagTreePointer instance.
    
    Returns:
    
    a PdfNamespace which is to be set for the new tags created, or null if one is not defined.
    
    See Also:
    
    setNamespaceForNewTags(PdfNamespace)
  - addTag
```
public TagTreePointer addTag(String role)
```
    Adds a new tag with given role to the tag structure. This method call moves this TagTreePointer to the added kid.
    
    Parameters:
    
    role - role of the new tag.
    
    Returns:
    
    this TagTreePointer instance.
  - addTag
```
public TagTreePointer addTag(int index,
                             String role)
```
    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).
    
    Parameters:
    
    index - zero-based index in kids array of parent tag at which new tag will be added.
    
    role - role of the new tag.
    
    Returns:
    
    this TagTreePointer instance.
  - addTag
```
public TagTreePointer addTag(AccessibilityProperties properties)
```
    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.
    
    Parameters:
    
    properties - accessibility properties which define a new tag role and other properties.
    
    Returns:
    
    this TagTreePointer instance.
  - addTag
```
public TagTreePointer addTag(int index,
                             AccessibilityProperties properties)
```
    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).
    
    Parameters:
    
    index - zero-based index in kids array of parent tag at which new tag will be added.
    
    properties - accessibility properties which define a new tag role and other properties.
    
    Returns:
    
    this TagTreePointer instance.
  - addAnnotationTag
```
public TagTreePointer addAnnotationTag(PdfAnnotation annotation)
```
    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 TagStructureContext.getAutoTaggingPointer()). If you want to add annotation tag manually, be sure to use PdfPage.addAnnotation(int, PdfAnnotation, boolean) method with false for boolean flag.
    
    Parameters:
    
    annotation - PdfAnnotation to be tagged.
    
    Returns:
    
    this TagTreePointer instance.
  - setNextNewKidIndex
```
public TagTreePointer setNextNewKidIndex(int nextNewKidIndex)
```
    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.
    
    Parameters:
    
    nextNewKidIndex - index of the next added kid.
    
    Returns:
    
    this TagTreePointer instance.
  - removeTag
```
public TagTreePointer removeTag()
```
    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.
    
    Returns:
    
    this TagStructureContext instance.
  - relocateKid
```
public TagTreePointer relocateKid(int kidIndex,
                                  TagTreePointer pointerToNewParent)
```
    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.
    
    Parameters:
    
    kidIndex - zero-based index of the current tag's kid to be relocated.
    
    pointerToNewParent - the TagTreePointer which is positioned at the tag which will become kid's new parent.
    
    Returns:
    
    this TagTreePointer instance.
  - relocate
```
public TagTreePointer relocate(TagTreePointer pointerToNewParent)
```
    Moves current tag to the tag at which given TagTreePointer points. This method doesn't change either this instance or pointerToNewParent position.
    
    Parameters:
    
    pointerToNewParent - the TagTreePointer which is positioned at the tag which will become current tag new parent.
    
    Returns:
    
    this TagTreePointer instance.
  - getTagReference
```
public TagReference getTagReference()
```
    Creates a reference to the current tag, which could be used to associate a content on the PdfCanvas with current tag. See PdfCanvas.openTag(TagReference) and setPageForTagging(PdfPage).
    
    Returns:
    
    the reference to the current tag.
  - getTagReference
```
public TagReference getTagReference(int index)
```
    Creates a reference to the current tag, which could be used to associate a content on the PdfCanvas with current tag. See PdfCanvas.openTag(TagReference) and setPageForTagging(PdfPage).
    
    Parameters:
    
    index - zero-based index in kids array of tag. These indexes define the logical order of the content on the page.
    
    Returns:
    
    the reference to the current tag.
  - moveToRoot
```
public TagTreePointer moveToRoot()
```
    Moves this TagTreePointer instance to the document root tag.
    
    Returns:
    
    this TagTreePointer instance.
  - moveToParent
```
public TagTreePointer moveToParent()
```
    Moves this TagTreePointer instance to the parent of the current tag.
    
    Returns:
    
    this TagTreePointer instance.
  - moveToKid
```
public TagTreePointer moveToKid(int kidIndex)
```
    Moves this TagTreePointer instance to the kid of the current tag.
    
    Parameters:
    
    kidIndex - zero-based index of the current tag kid to which pointer will be moved.
    
    Returns:
    
    this TagTreePointer instance.
  - moveToKid
```
public TagTreePointer moveToKid(String role)
```
    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.
    
    Parameters:
    
    role - 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:
    
    this TagTreePointer instance.
  - moveToKid
```
public TagTreePointer moveToKid(int n,
                                String role)
```
    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.
    
    Parameters:
    
    n - 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 - role of the current tag descendant to which pointer will be moved.
    
    Returns:
    
    this TagTreePointer instance.
  - getKidsRoles
```
public List<String> getKidsRoles()
```
    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).
    
    Returns:
    
    current tag kids roles
  - flushTag
```
public TagTreePointer flushTag()
```
    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.
    
    Returns:
    
    this TagTreePointer instance.
  - flushParentsIfAllKidsFlushed
```
public TagTreePointer flushParentsIfAllKidsFlushed()
```
    For current tag and all of it's parents consequentially checks if the following constraints apply, and flushes the tag if they do or stops if they don't:
    - tag is not already flushed;
    - tag is not in waiting state (see WaitingTagsManager);
    - tag is not the root tag;
    - tag has no kids or all of the kids are either flushed themselves or (if they are a marked content reference) belong to the flushed page.
    It makes sense to use this method in conjunction with TagStructureContext.flushPageTags(PdfPage) for the tags which have just lost their waiting state and might be not flushed only because they had one. This helps to eliminate hanging (not flushed) tags when they don't have waiting state anymore.
    Returns:
    
    this TagTreePointer instance.
  - getProperties
```
public AccessibilityProperties getProperties()
```
    Gets accessibility properties of the current tag.
    
    Returns:
    
    accessibility properties of the current tag.
  - getRole
```
public String getRole()
```
    Gets current tag role.
    
    Returns:
    
    current tag role.
  - setRole
```
public TagTreePointer setRole(String role)
```
    Sets new role to the current tag.
    
    Parameters:
    
    role - new role to be set.
    
    Returns:
    
    this TagTreePointer instance.
  - getIndexInParentKidsList
```
public int getIndexInParentKidsList()
```
    Defines index of the current tag in the parent's kids list.
    
    Returns:
    
    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.
  - moveToPointer
```
public TagTreePointer moveToPointer(TagTreePointer tagTreePointer)
```
    Moves this TagTreePointer instance to the tag at which given TagTreePointer instance is pointing.
    
    Parameters:
    
    tagTreePointer - a TagTreePointer that points at the tag which will become the current tag of this instance.
    
    Returns:
    
    this TagTreePointer instance.
  - isPointingToSameTag
```
public boolean isPointingToSameTag(TagTreePointer otherPointer)
```
    Checks if this TagTreePointer is pointing at the same tag as the giving TagTreePointer.
    
    Parameters:
    
    otherPointer - a TagTreePointer which is checked against this instance on whether they point at the same tag.
    
    Returns:
    
    true if both TagTreePointer instances point at the same tag, false otherwise.

Class TagTreePointer

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

TagTreePointer

TagTreePointer

Method Detail

setPageForTagging

getCurrentPage

setContentStreamForTagging

getCurrentContentStream

getContext

getDocument

setNamespaceForNewTags

getNamespaceForNewTags

addTag

addTag

addTag

addTag

addAnnotationTag

setNextNewKidIndex

removeTag

relocateKid

relocate

getTagReference

getTagReference

moveToRoot

moveToParent

moveToKid

moveToKid

moveToKid

getKidsRoles

flushTag

flushParentsIfAllKidsFlushed

getProperties

getRole

setRole

getIndexInParentKidsList

moveToPointer

isPointingToSameTag