TagTreePointer (iText 7 7.0.4 API)

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

All Implemented Interfaces:

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

See Also:

Serialized Form

Constructor Summary

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(IAccessibleElement element)` Adds a new tag to the tag structure.
`TagTreePointer`	`addTag(IAccessibleElement element, boolean keepConnectedToTag)` Adds a new tag to the tag structure.
`TagTreePointer`	`addTag(int index, IAccessibleElement element)` Adds a new tag to the tag structure.
`TagTreePointer`	`addTag(int index, IAccessibleElement element, boolean keepConnectedToTag)` Adds a new tag to the tag structure.
`TagTreePointer`	`addTag(int index, PdfName role)` Adds a new tag with given role to the tag structure.
`TagTreePointer`	`addTag(PdfName role)` Adds a new tag with given role to the tag structure.
`TagTreePointer`	`flushTag()` Flushes the current tag and all it's descenders.
`IAccessibleElement`	`getConnectedElement(boolean createIfNotExist)` Gets connected accessible element for the current tag.
`PdfStream`	`getCurrentContentStream()`
`PdfPage`	`getCurrentPage()`
`PdfDocument`	`getDocument()`
`List<PdfName>`	`getKidsRoles()` Gets current element kids roles.
`AccessibilityProperties`	`getProperties()` Gets accessibility properties of the current tag.
`PdfName`	`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`	`isElementConnectedToTag(IAccessibleElement element)` Checks if given `IAccessibleElement` is connected to some tag.
`TagTreePointer`	`moveToKid(int kidIndex)` Moves this `TagTreePointer` instance to the kid of the current tag.
`TagTreePointer`	`moveToKid(int n, PdfName role)` Moves this `TagTreePointer` instance to the kid of the current tag.
`TagTreePointer`	`moveToKid(PdfName role)` Moves this `TagTreePointer` instance to the kid of the current tag.
`TagTreePointer`	`moveToParent()` Moves this `TagTreePointer` instance to the parent of the current tag.
`TagTreePointer`	`moveToRoot()` Moves this `TagTreePointer` instance to the document root tag.
`TagTreePointer`	`moveToTag(IAccessibleElement element)` Moves this `TagTreePointer` instance to a tag, which is connected with the given accessible element.
`TagTreePointer`	`relocateKid(int kidIndex, TagTreePointer pointerToNewParent)` Moves kid of the current tag to the tag at which given `TagTreePointer` points.
`TagStructureContext`	`removeElementConnectionToTag(IAccessibleElement element)` Destroys the connection between the given accessible element and the tag to which this element is connected to.
`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`	`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(PdfName 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.
    
    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 PdfTagReference 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.
  - getCurrentContentStream
```
public PdfStream getCurrentContentStream()
```
    Returns:
    
    the content stream which content will be tagged with this instance of TagTreePointer.
  - getDocument
```
public PdfDocument getDocument()
```
    Returns:
    
    the document, at which tag structure this instance points.
  - addTag
```
public TagTreePointer addTag(PdfName 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,
                             PdfName 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(PdfName).
    
    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(IAccessibleElement element)
```
    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 IAccessibleElement.
    
    Parameters:
    
    element - accessible element which represents a new tag.
    
    Returns:
    
    this TagTreePointer instance.
  - addTag
```
public TagTreePointer addTag(IAccessibleElement element,
                             boolean keepConnectedToTag)
```
    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 IAccessibleElement.
    
    If keepConnectedToTag is true then a newly created tag will retain the connection with given accessible element. See moveToTag(com.itextpdf.kernel.pdf.tagutils.IAccessibleElement) for more explanations about tag connections concept.
    
    If the same accessible element is connected to the tag and is added twice to the same parent - this TagTreePointer instance would move to connected kid instead of creating tag twice. But if it is added to some other parent, then connection will be removed.
    
    Parameters:
    
    element - accessible element which represents a new tag.
    
    keepConnectedToTag - defines if to retain the connection between accessible element and the tag.
    
    Returns:
    
    this TagTreePointer instance.
  - addTag
```
public TagTreePointer addTag(int index,
                             IAccessibleElement element)
```
    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 IAccessibleElement. This call is equivalent of calling sequentially setNextNewKidIndex(int) and addTag(IAccessibleElement).
    
    Parameters:
    
    index - zero-based index in kids array of parent tag at which new tag will be added.
    
    element - accessible element which represents a new tag.
    
    Returns:
    
    this TagTreePointer instance.
  - addTag
```
public TagTreePointer addTag(int index,
                             IAccessibleElement element,
                             boolean keepConnectedToTag)
```
    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 IAccessibleElement.
    
    If keepConnectedToTag is true then a newly created tag will retain the connection with given accessible element. See moveToTag(com.itextpdf.kernel.pdf.tagutils.IAccessibleElement) for more explanations about tag connections concept.
    
    If the same accessible element is connected to the tag and is added twice to the same parent - this TagTreePointer instance would move to connected kid instead of creating tag twice. But if it is added to some other parent, then connection will be removed.
    
    This call is equivalent of calling sequentially setNextNewKidIndex(int) and addTag(IAccessibleElement, boolean).
    
    Parameters:
    
    index - zero-based index in kids array of parent tag at which new tag will be added.
    
    element - accessible element which represents a new tag.
    
    keepConnectedToTag - defines if to retain the connection between accessible element and the tag.
    
    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(PdfName) 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.
  - isElementConnectedToTag
```
public boolean isElementConnectedToTag(IAccessibleElement element)
```
    Checks if given IAccessibleElement is connected to some tag. See moveToTag(com.itextpdf.kernel.pdf.tagutils.IAccessibleElement) for more explanations about tag connections concept.
    
    Parameters:
    
    element - element to check if it has a connected tag.
    
    Returns:
    
    true, if there is a tag which retains the connection to the given accessible element.
  - removeElementConnectionToTag
```
public TagStructureContext removeElementConnectionToTag(IAccessibleElement element)
```
    Destroys the connection between the given accessible element and the tag to which this element is connected to. See moveToTag(com.itextpdf.kernel.pdf.tagutils.IAccessibleElement) for more explanations about tag connections concept.
    
    Parameters:
    
    element - IAccessibleElement which connection to the tag (if there is one) will be removed.
    
    Returns:
    
    this TagStructureContext 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 any tag if document's tag structure was partially 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 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 TagStructureContext 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 TagStructureContext instance.
  - moveToParent
```
public TagTreePointer moveToParent()
```
    Moves this TagTreePointer instance to the parent of the current tag.
    
    Returns:
    
    this TagStructureContext 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 TagStructureContext instance.
  - moveToKid
```
public TagTreePointer moveToKid(PdfName role)
```
    Moves this TagTreePointer instance to the kid of the current tag.
    
    Parameters:
    
    role - role of the current tag kid to which pointer will be moved. If there is several kids with this role, pointer will be moved to the first kid with such role.
    
    Returns:
    
    this TagStructureContext instance.
  - moveToKid
```
public TagTreePointer moveToKid(int n,
                                PdfName role)
```
    Moves this TagTreePointer instance to the kid of the current tag.
    
    Parameters:
    
    n - if there is several kids with the given role, pointer will be moved to the kid which is the n'th if you count kids with such role.
    
    role - role of the current tag kid to which pointer will be moved.
    
    Returns:
    
    this TagStructureContext instance.
  - moveToTag
```
public TagTreePointer moveToTag(IAccessibleElement element)
```
    Moves this TagTreePointer instance to a tag, which is connected with the given accessible element.
    
    The connection between the tag and the accessible element instance is used as a sign that tag is not yet finished and therefore should not be flushed or removed if page tags are flushed or removed. Also, any TagTreePointer could be immediately moved to the tag with connection via it's connected element by using this method. If accessible element is connected to the tag, then all changes of the role or properties of the element will affect the connected tag role and properties.
    For any existing not connected tag the connection could be created using getConnectedElement(boolean) with true as parameter.
    
    Parameters:
    
    element - an element which has a connection with some tag.
    
    Returns:
    
    this TagStructureContext instance.
  - getKidsRoles
```
public List<PdfName> getKidsRoles()
```
    Gets current element kids roles. If certain kid is already flushed, at its position there will be a null. If kid is content item, at its position there will be "MCR" (Marked Content Reference).
    
    Returns:
    
    current element kids roles
  - flushTag
```
public TagTreePointer flushTag()
```
    Flushes the current tag and all it's descenders. This method call moves this TagTreePointer to the current tag parent.
    
    If some of the tags to be flushed are still connected to the accessible elements, then these tags are considered as not yet finished ones, and they won't be flushed immediately, but they will be flushed, when the connection is removed.
    
    Returns:
    
    this TagStructureContext instance.
  - getConnectedElement
```
public IAccessibleElement getConnectedElement(boolean createIfNotExist)
```
    Gets connected accessible element for the current tag. If tag is not connected to element, behaviour is defined by the createIfNotExist flag. See moveToTag(com.itextpdf.kernel.pdf.tagutils.IAccessibleElement) for more explanations about tag connections concept.
    
    Parameters:
    
    createIfNotExist - if true, creates an IAccessibleElement and connects it to the tag.
    
    Returns:
    
    connected IAccessibleElement if there is one (or if it is created), otherwise null.
  - getProperties
```
public AccessibilityProperties getProperties()
```
    Gets accessibility properties of the current tag.
    
    Returns:
    
    accessibility properties of the current tag.
  - getRole
```
public PdfName getRole()
```
    Gets current tag role.
    
    Returns:
    
    current tag role.
  - setRole
```
public TagTreePointer setRole(PdfName role)
```
    Sets new role to the current tag.
    
    Parameters:
    
    role - new role to be set.
    
    Returns:
    
    this TagStructureContext instance.

Class TagTreePointer

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

TagTreePointer

TagTreePointer

Method Detail

setPageForTagging

getCurrentPage

setContentStreamForTagging

getCurrentContentStream

getDocument

addTag

addTag

addTag

addTag

addTag

addTag

addAnnotationTag

setNextNewKidIndex

isElementConnectedToTag

removeElementConnectionToTag

removeTag

relocateKid

getTagReference

getTagReference

moveToRoot

moveToParent

moveToKid

moveToKid

moveToKid

moveToTag

getKidsRoles

flushTag

getConnectedElement

getProperties

getRole

setRole