Class TagTreePointer
- java.lang.Object
-
- com.itextpdf.kernel.pdf.tagutils.TagTreePointer
-
public class TagTreePointer extends java.lang.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 usingmoveToKid(int)
andmoveToParent()
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.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description private static class
TagTreePointer.RoleFinderHandler
private static class
TagTreePointer.TagTreeIteratorApproverWithStop
Deprecated.change ITagTreeIteratorHandler#nextElement to return boolean showing whether the iteration should be continued.
-
Field Summary
Fields Modifier and Type Field Description private PdfStream
contentStream
private PdfNamespace
currentNamespace
private PdfPage
currentPage
private PdfStructElem
currentStructElem
private static java.lang.String
MCR_MARKER
private int
nextNewKidIndex
private TagStructureContext
tagStructureContext
-
Constructor Summary
Constructors Constructor Description TagTreePointer(PdfDocument document)
CreatesTagTreePointer
instance.TagTreePointer(PdfStructElem structElem, PdfDocument document)
TagTreePointer(TagTreePointer tagPointer)
A copy constructor.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description TagTreePointer
addAnnotationTag(PdfAnnotation annotation)
Adds a new content item for the givenPdfAnnotation
under the current tag.private PdfMcr
addNewKid(PdfMcr kid)
private PdfStructElem
addNewKid(PdfStructElem kid)
private PdfStructElem
addNewKid(AccessibilityProperties properties)
private PdfStructElem
addNewKid(java.lang.String role)
TagTreePointer
addTag(int index, AccessibilityProperties properties)
Adds a new tag to the tag structure.TagTreePointer
addTag(int index, java.lang.String role)
Adds a new tag with given role to the tag structure.TagTreePointer
addTag(AccessibilityProperties properties)
Adds a new tag to the tag structure.TagTreePointer
addTag(java.lang.String role)
Adds a new tag with given role to the tag structure.void
applyProperties(AccessibilityProperties properties)
Applies properties to the current tag.(package private) int
createNextMcidForStructElem(PdfStructElem elem, int index)
private boolean
ensureElementPageEqualsKidPage(PdfStructElem elem, PdfDictionary kidPage)
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 (seeWaitingTagsManager
); 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()
private PdfStructElem
getCurrentElemEnsureIndirect()
PdfPage
getCurrentPage()
(package private) PdfStructElem
getCurrentStructElem()
PdfDocument
getDocument()
int
getIndexInParentKidsList()
Defines index of the current tag in the parent's kids list.java.util.List<java.lang.String>
getKidsRoles()
Gets current tag kids roles.PdfNamespace
getNamespaceForNewTags()
Gets aPdfNamespace
which will be set to every new tag created by thisTagTreePointer
instance.private int
getNextNewKidPosition()
AccessibilityProperties
getProperties()
Gets accessibility properties of the current tag.java.lang.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 thisTagTreePointer
is pointing at the same tag as the givingTagTreePointer
.private boolean
markedContentNotInPageStream()
TagTreePointer
moveToKid(int kidIndex)
Moves thisTagTreePointer
instance to the kid of the current tag.TagTreePointer
moveToKid(int n, java.lang.String role)
Moves thisTagTreePointer
instance to the nth descendant of the current tag which has the given role.TagTreePointer
moveToKid(java.lang.String role)
Moves thisTagTreePointer
instance to the first descendant of the current tag which has the given role.TagTreePointer
moveToParent()
Moves thisTagTreePointer
instance to the parent of the current tag.TagTreePointer
moveToPointer(TagTreePointer tagTreePointer)
Moves thisTagTreePointer
instance to the tag at which givenTagTreePointer
instance is pointing.TagTreePointer
moveToRoot()
Moves thisTagTreePointer
instance to the document root tag.private PdfMcr
prepareMcrForMovingToNewParent(PdfMcr mcrKid, PdfStructElem newParent)
private void
processKidNamespace(PdfStructElem kid)
TagTreePointer
relocate(TagTreePointer pointerToNewParent)
Moves current tag to the tag at which givenTagTreePointer
points.TagTreePointer
relocateKid(int kidIndex, TagTreePointer pointerToNewParent)
Moves kid of the current tag to the tag at which givenTagTreePointer
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.(package private) TagTreePointer
setCurrentStructElem(PdfStructElem structElem)
TagTreePointer
setNamespaceForNewTags(PdfNamespace namespace)
Sets aPdfNamespace
which will be set to every new tag created by thisTagTreePointer
instance if this tag doesn't explicitly define namespace by the means ofDefaultAccessibilityProperties.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 ofTagTreePointer
.TagTreePointer
setRole(java.lang.String role)
Sets new role to the current tag.private void
throwExceptionIfCurrentPageIsNotInited()
-
-
-
Field Detail
-
MCR_MARKER
private static final java.lang.String MCR_MARKER
- See Also:
- Constant Field Values
-
tagStructureContext
private TagStructureContext tagStructureContext
-
currentStructElem
private PdfStructElem currentStructElem
-
currentPage
private PdfPage currentPage
-
contentStream
private PdfStream contentStream
-
currentNamespace
private PdfNamespace currentNamespace
-
nextNewKidIndex
private int nextNewKidIndex
-
-
Constructor Detail
-
TagTreePointer
public TagTreePointer(PdfDocument document)
CreatesTagTreePointer
instance. After creationTagTreePointer
points at the root tag.The
PdfNamespace
for the new tags, which don't explicitly define namespace by the means ofDefaultAccessibilityProperties.setNamespace(PdfNamespace)
, is set to the value returned byTagStructureContext.getDocumentDefaultNamespace()
onTagTreePointer
creation. See alsosetNamespaceForNewTags(PdfNamespace)
.- Parameters:
document
- the document, at which tag structure this instance will point.
-
TagTreePointer
public TagTreePointer(TagTreePointer tagPointer)
A copy constructor.- Parameters:
tagPointer
- theTagTreePointer
from which current position and page are copied.
-
TagTreePointer
TagTreePointer(PdfStructElem structElem, PdfDocument document)
-
-
Method Detail
-
setPageForTagging
public TagTreePointer setPageForTagging(PdfPage page)
Sets a page which content will be tagged with this instance ofTagTreePointer
. To tag page content:- Set pointer position to the tag which will be the parent of the page content item;
- Call
getTagReference()
to obtain the reference to the current tag; - Pass
TagReference
to thePdfCanvas.openTag(TagReference)
method of the page'sPdfCanvas
to start marked content item; - Draw content on
PdfCanvas
; - Use
PdfCanvas.closeTag()
to finish marked content item.
- Parameters:
page
- the page which content will be tagged with this instance ofTagTreePointer
.- 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 anull
for this value, when tagging of this stream content is finished.- Parameters:
contentStream
- the content stream which content will be tagged with this instance ofTagTreePointer
ornull
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 aPdfNamespace
which will be set to every new tag created by thisTagTreePointer
instance if this tag doesn't explicitly define namespace by the means ofDefaultAccessibilityProperties.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 viaTagStructureContext.fetchNamespace(String)
.- Parameters:
namespace
- aPdfNamespace
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 correspondingAccessibilityProperties
.- Returns:
- this
TagTreePointer
instance. - See Also:
TagStructureContext.fetchNamespace(String)
-
getNamespaceForNewTags
public PdfNamespace getNamespaceForNewTags()
Gets aPdfNamespace
which will be set to every new tag created by thisTagTreePointer
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(java.lang.String role)
Adds a new tag with given role to the tag structure. This method call moves thisTagTreePointer
to the added kid.- Parameters:
role
- role of the new tag.- Returns:
- this
TagTreePointer
instance.
-
addTag
public TagTreePointer addTag(int index, java.lang.String role)
Adds a new tag with given role to the tag structure. This method call moves thisTagTreePointer
to the added kid.
This call is equivalent of calling sequentiallysetNextNewKidIndex(int)
andaddTag(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 thisTagTreePointer
to the added kid.
New tag will have a role and attributes defined by the givenAccessibilityProperties
.- 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 thisTagTreePointer
to the added kid.
New tag will have a role and attributes defined by the givenAccessibilityProperties
. This call is equivalent of calling sequentiallysetNextNewKidIndex(int)
andaddTag(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 givenPdfAnnotation
under the current tag.
By default, when annotation is added to the page it is automatically tagged with auto tagging pointer (seeTagStructureContext.getAutoTaggingPointer()
). If you want to add annotation tag manually, be sure to usePdfPage.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 ofaddTag(String)
method, withrelocateKid(int, TagTreePointer)
andaddAnnotationTag(PdfAnnotation)
.
Keep in mind, that this method set property to theTagTreePointer
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 thisTagTreePointer
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 givenTagTreePointer
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
- theTagTreePointer
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 givenTagTreePointer
points. This method doesn't change either this instance or pointerToNewParent position.- Parameters:
pointerToNewParent
- theTagTreePointer
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. SeePdfCanvas.openTag(TagReference)
andsetPageForTagging(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. SeePdfCanvas.openTag(TagReference)
andsetPageForTagging(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 thisTagTreePointer
instance to the document root tag.- Returns:
- this
TagTreePointer
instance.
-
moveToParent
public TagTreePointer moveToParent()
Moves thisTagTreePointer
instance to the parent of the current tag.- Returns:
- this
TagTreePointer
instance.
-
moveToKid
public TagTreePointer moveToKid(int kidIndex)
Moves thisTagTreePointer
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(java.lang.String role)
Moves thisTagTreePointer
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, java.lang.String role)
Moves thisTagTreePointer
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 java.util.List<java.lang.String> getKidsRoles()
Gets current tag kids roles. If certain kid is already flushed, at its position there will be anull
. 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 thisTagTreePointer
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.
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 java.lang.String getRole()
Gets current tag role.- Returns:
- current tag role.
-
setRole
public TagTreePointer setRole(java.lang.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 thisTagTreePointer
instance to the tag at which givenTagTreePointer
instance is pointing.- Parameters:
tagTreePointer
- aTagTreePointer
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 thisTagTreePointer
is pointing at the same tag as the givingTagTreePointer
.- Parameters:
otherPointer
- aTagTreePointer
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.
-
createNextMcidForStructElem
int createNextMcidForStructElem(PdfStructElem elem, int index)
-
setCurrentStructElem
TagTreePointer setCurrentStructElem(PdfStructElem structElem)
-
getCurrentStructElem
PdfStructElem getCurrentStructElem()
-
applyProperties
public void applyProperties(AccessibilityProperties properties)
Applies properties to the current tag.- Parameters:
properties
- the properties to be applied to the current tag.
-
getNextNewKidPosition
private int getNextNewKidPosition()
-
addNewKid
private PdfStructElem addNewKid(java.lang.String role)
-
addNewKid
private PdfStructElem addNewKid(AccessibilityProperties properties)
-
processKidNamespace
private void processKidNamespace(PdfStructElem kid)
-
addNewKid
private PdfStructElem addNewKid(PdfStructElem kid)
-
getCurrentElemEnsureIndirect
private PdfStructElem getCurrentElemEnsureIndirect()
-
prepareMcrForMovingToNewParent
private PdfMcr prepareMcrForMovingToNewParent(PdfMcr mcrKid, PdfStructElem newParent)
-
ensureElementPageEqualsKidPage
private boolean ensureElementPageEqualsKidPage(PdfStructElem elem, PdfDictionary kidPage)
-
markedContentNotInPageStream
private boolean markedContentNotInPageStream()
-
throwExceptionIfCurrentPageIsNotInited
private void throwExceptionIfCurrentPageIsNotInited()
-
-