public class TagStructureContext extends Object
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.
PdfDocument
. To obtain instance of this class use PdfDocument.getTagStructureContext()
.
Modifier and Type | Field and Description |
---|---|
protected TagTreePointer |
autoTaggingPointer |
Constructor and Description |
---|
TagStructureContext(PdfDocument document)
Do not use this constructor, instead use PdfDocument.getTagStructureContext() method.
|
TagStructureContext(PdfDocument document, PdfVersion tagStructureTargetVersion)
Do not use this constructor, instead use PdfDocument.getTagStructureContext() method.
|
Modifier and Type | Method and Description |
---|---|
boolean |
checkIfRoleShallBeMappedToStandardRole(String role, PdfNamespace namespace)
Checks if the given role and namespace are specified to be obligatory mapped to the standard structure namespace in order to be a valid role in the Tagged PDF.
|
TagTreePointer |
createPointerForStructElem(PdfStructElem structElem)
Creates a new TagTreePointer which points at given PdfStructElem .
|
PdfNamespace |
fetchNamespace(String namespaceName)
This method defines a recommended way to obtain PdfNamespace class instances.
|
TagStructureContext |
flushPageTags(PdfPage page)
Flushes the tags which are considered to belong to the given page.
|
TagTreePointer |
getAutoTaggingPointer()
All tagging logic performed by iText automatically (along with addition of content, annotations etc) uses TagTreePointer returned by this method to manipulate the tag structure.
|
PdfNamespace |
getDocumentDefaultNamespace()
A namespace that is used as a default value for the tagging for any new TagTreePointer created (including the pointer returned by getAutoTaggingPointer() , which implies that automatically created tag structure will be in this namespace by default).
|
PdfStructElem |
getPointerStructElem(TagTreePointer pointer)
Gets PdfStructElem at which TagTreePointer points.
|
IRoleMappingResolver |
getRoleMappingResolver(String role)
Gets an instance of the IRoleMappingResolver corresponding to the current tag structure target version.
|
IRoleMappingResolver |
getRoleMappingResolver(String role, PdfNamespace namespace)
Gets an instance of the IRoleMappingResolver corresponding to the current tag structure target version.
|
PdfVersion |
getTagStructureTargetVersion() |
WaitingTagsManager |
getWaitingTagsManager()
Gets WaitingTagsManager for the current document.
|
void |
normalizeDocumentRootTag()
Transforms root tags in a way that complies with the tagged PDF specification.
|
void |
prepareToDocumentClosing()
A utility method that prepares the current instance of the TagStructureContext for the closing of document.
|
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 |
removePageTags(PdfPage page)
Removes all tags that belong only to this page.
|
IRoleMappingResolver |
resolveMappingToStandardOrDomainSpecificRole(String role, PdfNamespace namespace)
Gets an instance of the IRoleMappingResolver which is already in the "resolved" state: it returns role in the standard or domain-specific namespace for the IRoleMappingResolver.getRole() and IRoleMappingResolver.getNamespace() methods calls which correspond to the mapping of the given role; or null if the given role is not mapped to the standard or domain-specific one.
|
TagStructureContext |
setDocumentDefaultNamespace(PdfNamespace namespace)
Sets a namespace that will be used as a default value for the tagging for any new TagTreePointer created.
|
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.
|
protected TagTreePointer autoTaggingPointer
public TagStructureContext(PdfDocument document)
PdfDocument.getTagStructureContext()
method.
TagStructureContext
for document. There shall be only one instance of this class per PdfDocument
.
document
- the document which tag structure will be manipulated with this class.
public TagStructureContext(PdfDocument document, PdfVersion tagStructureTargetVersion)
PdfDocument.getTagStructureContext()
method.
TagStructureContext
for document. There shall be only one instance of this class per PdfDocument
.
document
- the document which tag structure will be manipulated with this class.
tagStructureTargetVersion
- the version of the pdf standard to which the tag structure shall adhere.
public TagStructureContext setForbidUnknownRoles(boolean forbidUnknownRoles)
forbidUnknownRoles
- new value of the flag
TagStructureContext
instance.
public PdfVersion getTagStructureTargetVersion()
public TagTreePointer getAutoTaggingPointer()
TagTreePointer
returned by this method to manipulate the 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 Section tag, which would result in placing all automatically tagged content under Section tag).
TagTreePointer
which is used for all automatic tagging of the document.
public WaitingTagsManager getWaitingTagsManager()
WaitingTagsManager
for the current document. It allows to mark tags as waiting, which would indicate that they are incomplete and are not ready to be flushed.
WaitingTagsManager
class instance.
public PdfNamespace getDocumentDefaultNamespace()
TagTreePointer
created (including the pointer returned by getAutoTaggingPointer()
, which implies that automatically created tag structure will be in this namespace by default).
By default, this value is defined based on the PDF document version and the existing tag structure inside a document. For the new empty PDF 2.0 documents this namespace is set to StandardNamespaces.PDF_2_0
.
This value has meaning only for the PDF documents of version 2.0 and higher.
PdfNamespace
which is used as a default value for the document tagging.
public TagStructureContext setDocumentDefaultNamespace(PdfNamespace namespace)
TagTreePointer
created. See getDocumentDefaultNamespace()
for more info.
Be careful when changing this property value. It is most recommended to do it right after the PdfDocument
was created, before any content was added. Changing this value after any content was added might result in the mingled tag structure from the namespaces point of view. So in order to maintain the document consistent but in the namespace different from default, set this value before any modifications to the document were made and before getAutoTaggingPointer()
method was called for the first time.
This value has meaning only for the PDF documents of version 2.0 and higher.
namespace
- a PdfNamespace
which is to be used as a default value for the document tagging.
TagStructureContext
instance.
public PdfNamespace fetchNamespace(String namespaceName)
PdfNamespace
class instances.
Returns either a wrapper over an already existing namespace dictionary in the document or over a new one if such namespace wasn't encountered before. Calling this method is considered as encountering a namespace, i.e. two sequential calls on this method will return the same namespace instance (which is not true in general case of two method calls, for instance if several namespace instances with the same name are created via PdfNamespace
constructors and set to the elements of the tag structure, then the last encountered one will be returned by this method). However encountered namespaces will not be added to the document's structure tree root /Namespaces
array unless they were set to the certain element of the tag structure.
namespaceName
- a String
defining the namespace name (conventionally a uniform resource identifier, or URI).
public IRoleMappingResolver getRoleMappingResolver(String role)
IRoleMappingResolver
corresponding to the current tag structure target version. This method implies that role is in the default standard structure namespace.
role
- a role in the default standard structure namespace which mapping is to be resolved.
IRoleMappingResolver
instance, with the giving role as current.
public IRoleMappingResolver getRoleMappingResolver(String role, PdfNamespace namespace)
IRoleMappingResolver
corresponding to the current tag structure target version.
role
- a role in the given namespace which mapping is to be resolved.
namespace
- a PdfNamespace
which this role belongs to.
IRoleMappingResolver
instance, with the giving role in the given PdfNamespace
as current.
public boolean checkIfRoleShallBeMappedToStandardRole(String role, PdfNamespace namespace)
role
- a role in the given namespace which mapping necessity is to be checked.
namespace
- a PdfNamespace
which this role belongs to, null value refers to the default standard structure namespace.
public IRoleMappingResolver resolveMappingToStandardOrDomainSpecificRole(String role, PdfNamespace namespace)
IRoleMappingResolver
which is already in the "resolved" state: it returns role in the standard or domain-specific namespace for the IRoleMappingResolver.getRole()
and IRoleMappingResolver.getNamespace()
methods calls which correspond to the mapping of the given role; or null if the given role is not mapped to the standard or domain-specific one.
role
- a role in the given namespace which mapping is to be resolved.
namespace
- a PdfNamespace
which this role belongs to.
IRoleMappingResolver
which returns false for the IRoleMappingResolver.currentRoleShallBeMappedToStandard()
method call; if mapping cannot be resolved to this state, this method returns null, which means that the given role in the specified namespace is not mapped to the standard role in the standard namespace.
public TagTreePointer removeAnnotationTag(PdfAnnotation annotation)
TagTreePointer
instance which points at annotation tag parent if annotation was removed, otherwise returns null.
public TagTreePointer removeContentItem(PdfPage page, int mcid)
page
- page, which contains this content item
mcid
- marked content id of this content item
TagTreePointer
which points at the parent of the removed content item, or null if there is no such mcid on given page.
public TagStructureContext removePageTags(PdfPage page)
flushPageTags(PdfPage)
.
page
- page that defines which tags are to be removed
TagStructureContext
instance.
public TagStructureContext flushPageTags(PdfPage page)
WaitingTagsManager
these tags are considered as not yet finished ones, and they and their children won't be flushed.
page
- a page which tags will be flushed.
public void normalizeDocumentRootTag()
public void prepareToDocumentClosing()
TagStructureContext
for the closing of document. Essentially it flushes all the "hanging" information to the document.
public PdfStructElem getPointerStructElem(TagTreePointer pointer)
Gets PdfStructElem
at which TagTreePointer
points.
PdfStructElem
is a low level class, use it carefully, especially in conjunction with high level TagTreePointer
and TagStructureContext
classes.
pointer
- a TagTreePointer
which points at desired PdfStructElem
.
PdfStructElem
at which given TagTreePointer
points.
public TagTreePointer createPointerForStructElem(PdfStructElem structElem)
TagTreePointer
which points at given PdfStructElem
.
structElem
- a PdfStructElem
for which TagTreePointer
will be created.
TagTreePointer
.
Copyright © 1998–2018 iText Group NV. All rights reserved.