com.itextpdf.kernel.pdf.tagutils

Class TagStructureContext

java.lang.Object

com.itextpdf.kernel.pdf.tagutils.TagStructureContext

All Implemented Interfaces:

Serializable

public class TagStructureContext
extends Object
implements Serializable

TagStructureContext class is used to track necessary information of document's tag structure. It is also used to make some global modifications of the tag tree like removing or flushing page tags, however these two methods and also others are called automatically and are for the most part for internal usage.
There shall be only one instance of this class per PdfDocument. To obtain instance of this class use PdfDocument.getTagStructureContext().

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected TagTreePointer	autoTaggingPointer

Constructor Summary

Constructors

Constructor and Description
TagStructureContext(PdfDocument document) Do not use this constructor, instead use PdfDocument.getTagStructureContext() method.
TagStructureContext(PdfDocument document, PdfVersion tagStructureTargetVersion)

Method Summary

Modifier and Type	Method and Description
void	actualizeTagsProperties() Method for internal usages.
TagTreePointer	createPointerForStructElem(PdfStructElem structElem) Creates a new TagTreePointer which points at given PdfStructElem.
TagStructureContext	flushPageTags(PdfPage page) Flushes the tags which are considered to belong to the given page.
TagTreePointer	getAutoTaggingPointer() All document auto tagging logic uses TagTreePointer returned by this method to manipulate tag structure.
PdfStructElem	getPointerStructElem(TagTreePointer pointer) Gets PdfStructElem at which TagTreePointer points.
PdfVersion	getTagStructureTargetVersion()
boolean	isElementConnectedToTag(IAccessibleElement element) Checks if given IAccessibleElement is connected to some tag.
TagStructureContext	moveTagPointerToTag(IAccessibleElement element, TagTreePointer tagPointer) Sets the tag, which is connected with the given accessible element, as a current tag for the given TagTreePointer.
void	normalizeDocumentRootTag() Transforms root tags in a way that complies with the PDF References.
TagStructureContext	removeAllConnectionsToTags() Destroys all the retained connections.
TagTreePointer	removeAnnotationTag(PdfAnnotation annotation) Removes annotation content item from the tag structure.
TagTreePointer	removeContentItem(PdfPage page, int mcid) Removes content item from the tag structure.
TagStructureContext	removeElementConnectionToTag(IAccessibleElement element) Destroys the connection between the given accessible element and the tag to which this element is connected to.
TagStructureContext	removePageTags(PdfPage page) Removes all tags that belong only to this page.
TagStructureContext	setForbidUnknownRoles(boolean forbidUnknownRoles) If forbidUnknownRoles is set to true, then if you would try to add new tag which has not a standard role and it's role is not mapped through RoleMap, an exception will be raised.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

autoTaggingPointer

protected TagTreePointer autoTaggingPointer

Constructor Detail

TagStructureContext

public TagStructureContext(PdfDocument document)

Do not use this constructor, instead use PdfDocument.getTagStructureContext() method.
Creates TagStructureContext for document. There shall be only one instance of this class per PdfDocument.

Parameters:

document - the document which tag structure will be manipulated with this class.

TagStructureContext

public TagStructureContext(PdfDocument document,
                           PdfVersion tagStructureTargetVersion)

Method Detail

setForbidUnknownRoles

public TagStructureContext setForbidUnknownRoles(boolean forbidUnknownRoles)

If forbidUnknownRoles is set to true, then if you would try to add new tag which has not a standard role and it's role is not mapped through RoleMap, an exception will be raised. Default value - true.

Parameters:

forbidUnknownRoles - new value of the flag

Returns:

current TagStructureContext instance.

getTagStructureTargetVersion

public PdfVersion getTagStructureTargetVersion()

getAutoTaggingPointer

public TagTreePointer getAutoTaggingPointer()

All document auto tagging logic uses TagTreePointer returned by this method to manipulate tag structure. Typically it points at the root tag. This pointer also could be used to tweak auto tagging process (e.g. move this pointer to the Sect tag, which would result in placing all automatically tagged content under Sect tag).

Returns:

the TagTreePointer which is used for all auto tagging of the document.

isElementConnectedToTag

public boolean isElementConnectedToTag(IAccessibleElement element)

Checks if given IAccessibleElement is connected to some tag.

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.

Parameters:

element - IAccessibleElement which connection to the tag (if there is one) will be removed.

Returns:

current TagStructureContext instance.

removeAnnotationTag

public TagTreePointer removeAnnotationTag(PdfAnnotation annotation)

Removes annotation content item from the tag structure. If annotation is not added to the document or is not tagged, nothing will happen.

Returns:

TagTreePointer instance which points at annotation tag parent if annotation was removed, otherwise returns null.

removeContentItem

public TagTreePointer removeContentItem(PdfPage page,
                                        int mcid)

Removes content item from the tag structure.
Nothing happens if there is no such mcid on given page.

Parameters:

page - page, which contains this content item

mcid - marked content id of this content item

Returns:

TagTreePointer which points at the parent of the removed content item, or null if there is no such mcid on given page.

removePageTags

public TagStructureContext removePageTags(PdfPage page)

Removes all tags that belong only to this page. The logic which defines if tag belongs to the page is described at flushPageTags(PdfPage).

Parameters:

page - page that defines which tags are to be removed

Returns:

current TagStructureContext instance.

moveTagPointerToTag

public TagStructureContext moveTagPointerToTag(IAccessibleElement element,
                                               TagTreePointer tagPointer)

Sets the tag, which is connected with the given accessible element, as a current tag for the given TagTreePointer. An exception will be thrown, if given accessible element is not connected to any tag.

Parameters:

element - an element which has a connection with some tag.

tagPointer - TagTreePointer which will be moved to the tag connected to the given accessible element.

Returns:

current TagStructureContext instance.

removeAllConnectionsToTags

public TagStructureContext removeAllConnectionsToTags()

Destroys all the retained connections.

Returns:

current TagStructureContext instance.

flushPageTags

public TagStructureContext flushPageTags(PdfPage page)

Flushes the tags which are considered to belong to the given page. The logic that defines if the given tag (structure element) belongs to the page is the following: if all the marked content references (dictionary or number references), that are the descenders of the given structure element, belong to the current page - the tag is considered to belong to the page. If tag has descenders from several pages - it is flushed, if all other pages except the current one are flushed.

If some of the page's tags are still connected to the accessible elements, in this case these tags are considered as not yet finished ones, and they won't be flushed.

Parameters:

page - a page which tags will be flushed.

normalizeDocumentRootTag

public void normalizeDocumentRootTag()

Transforms root tags in a way that complies with the PDF References.
PDF Reference 10.7.3 Grouping Elements:
For most content extraction formats, the document must be a tree with a single top-level element; the structure tree root (identified by the StructTreeRoot entry in the document catalog) must have only one child in its K (kids) array. If the PDF file contains a complete document, the structure type Document is recommended for this top-level element in the logical structure hierarchy. If the file contains a well-formed document fragment, one of the structure types Part, Art, Sect, or Div may be used instead.

actualizeTagsProperties

public void actualizeTagsProperties()

Method for internal usages. Essentially, all it does is just making sure that for connected tags the properties are up to date with the connected accessible elements properties.

getPointerStructElem

public PdfStructElem getPointerStructElem(TagTreePointer pointer)

Gets PdfStructElem at which TagTreePointer points.

NOTE: Be aware that PdfStructElem is a low level class, use it carefully, especially in conjunction with high level TagTreePointer and TagStructureContext classes.

Parameters:

pointer - a TagTreePointer which points at desired PdfStructElem.

Returns:

a PdfStructElem at which given TagTreePointer points.

createPointerForStructElem

public TagTreePointer createPointerForStructElem(PdfStructElem structElem)

Creates a new TagTreePointer which points at given PdfStructElem.

Parameters:

structElem - a PdfStructElem for which TagTreePointer will be created.

Returns:

a new TagTreePointer.