TagStructureContext class is used to track necessary information of document's tag structure. More...

Public Member Functions
	TagStructureContext (PdfDocument document)
	Do not use this constructor, instead use iText.Kernel.Pdf.PdfDocument.GetTagStructureContext() method. More...

	TagStructureContext (PdfDocument document, PdfVersion tagStructureTargetVersion)
	Do not use this constructor, instead use iText.Kernel.Pdf.PdfDocument.GetTagStructureContext() method. More...

virtual iText.Kernel.Pdf.Tagutils.TagStructureContext	SetForbidUnknownRoles (bool 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. More...

virtual PdfVersion	GetTagStructureTargetVersion ()
	Gets the version of the PDF standard to which the tag structure shall adhere. More...

virtual 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. More...

virtual WaitingTagsManager	GetWaitingTagsManager ()
	Gets WaitingTagsManager for the current document. More...

virtual 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). More...

virtual iText.Kernel.Pdf.Tagutils.TagStructureContext	SetDocumentDefaultNamespace (PdfNamespace @namespace)
	Sets a namespace that will be used as a default value for the tagging for any new TagTreePointer created. More...

virtual PdfNamespace	FetchNamespace (String namespaceName)
	This method defines a recommended way to obtain iText.Kernel.Pdf.Tagging.PdfNamespace class instances. More...

virtual IRoleMappingResolver	GetRoleMappingResolver (String role)
	Gets an instance of the IRoleMappingResolver corresponding to the current tag structure target version. More...

virtual IRoleMappingResolver	GetRoleMappingResolver (String role, PdfNamespace @namespace)
	Gets an instance of the IRoleMappingResolver corresponding to the current tag structure target version. More...

virtual bool	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. More...

virtual 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. More...

virtual TagTreePointer	RemoveAnnotationTag (PdfAnnotation annotation)
	Removes annotation content item from the tag structure. More...

virtual TagTreePointer	RemoveAnnotationTag (PdfAnnotation annotation, bool setAutoTaggingPointer)
	Removes annotation content item from the tag structure and sets autoTaggingPointer if true is passed. More...

virtual TagTreePointer	RemoveContentItem (PdfPage page, int mcid)
	Removes content item from the tag structure. More...

virtual iText.Kernel.Pdf.Tagutils.TagStructureContext	RemovePageTags (PdfPage page)
	Removes all tags that belong only to this page. More...

virtual iText.Kernel.Pdf.Tagutils.TagStructureContext	FlushPageTags (PdfPage page)
	Flushes the tags which are considered to belong to the given page. More...

virtual void	NormalizeDocumentRootTag ()
	Transforms root tags in a way that complies with the tagged PDF specification. More...

virtual void	PrepareToDocumentClosing ()
	A utility method that prepares the current instance of the TagStructureContext for the closing of document. More...

virtual PdfStructElem	GetPointerStructElem (TagTreePointer pointer)
	Gets iText.Kernel.Pdf.Tagging.PdfStructElem at which TagTreePointer points. More...

virtual TagTreePointer	GetTagPointerById (byte[] id)
	Retrieve a pointer to a structure element by ID. More...

virtual TagTreePointer	GetTagPointerByIdString (String id)
	Retrieve a pointer to a structure element by ID. More...

virtual TagTreePointer	CreatePointerForStructElem (PdfStructElem structElem)
	Creates a new TagTreePointer which points at given iText.Kernel.Pdf.Tagging.PdfStructElem. More...

Detailed Description

TagStructureContext class is used to track necessary information of document's tag structure.

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 iText.Kernel.Pdf.PdfDocument.GetTagStructureContext().

Constructor & Destructor Documentation

◆ TagStructureContext() [1/2]

iText.Kernel.Pdf.Tagutils.TagStructureContext.TagStructureContext ( PdfDocument document )

inline

Do not use this constructor, instead use iText.Kernel.Pdf.PdfDocument.GetTagStructureContext() method.

Do not use this constructor, instead use iText.Kernel.Pdf.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() [2/2]

iText.Kernel.Pdf.Tagutils.TagStructureContext.TagStructureContext	(	PdfDocument	document,
		PdfVersion	tagStructureTargetVersion
	)

inline

Do not use this constructor, instead use iText.Kernel.Pdf.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.
tagStructureTargetVersion	the version of the pdf standard to which the tag structure shall adhere.

Member Function Documentation

◆ CheckIfRoleShallBeMappedToStandardRole()

virtual bool iText.Kernel.Pdf.Tagutils.TagStructureContext.CheckIfRoleShallBeMappedToStandardRole	(	String	role,
		PdfNamespace @	namespace
	)

inlinevirtual

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.

Parameters

role	a role in the given namespace which mapping necessity is to be checked.
namespace	a iText.Kernel.Pdf.Tagging.PdfNamespace which this role belongs to, null value refers to the default standard structure namespace.

Returns: true, if the given role in the given namespace is either mapped to the standard structure role or doesn't have to; otherwise false.

◆ CreatePointerForStructElem()

virtual TagTreePointer iText.Kernel.Pdf.Tagutils.TagStructureContext.CreatePointerForStructElem ( PdfStructElem structElem )

inlinevirtual

Creates a new TagTreePointer which points at given iText.Kernel.Pdf.Tagging.PdfStructElem.

Parameters

structElem a iText.Kernel.Pdf.Tagging.PdfStructElem for which TagTreePointer will be created.

Returns: a new TagTreePointer.

◆ FetchNamespace()

virtual PdfNamespace iText.Kernel.Pdf.Tagutils.TagStructureContext.FetchNamespace ( String namespaceName )

inlinevirtual

This method defines a recommended way to obtain iText.Kernel.Pdf.Tagging.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 iText.Kernel.Pdf.Tagging.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.

Parameters

namespaceName a System.String defining the namespace name (conventionally a uniform resource identifier, or URI).

Returns

iText.Kernel.Pdf.Tagging.PdfNamespace wrapper over either already existing namespace object or over the new one.

◆ FlushPageTags()

virtual iText.Kernel.Pdf.Tagutils.TagStructureContext iText.Kernel.Pdf.Tagutils.TagStructureContext.FlushPageTags ( PdfPage page )

inlinevirtual

Flushes the tags which are considered to belong to the given 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 descendants of the given structure element, belong to the current page - the tag is considered to belong to the page. If tag has descendants from several pages - it is flushed, if all other pages except the current one are flushed.

If some of the page's tags have waiting state (see WaitingTagsManager these tags are considered as not yet finished ones, and they and their children won't be flushed.

Parameters

page	a page which tags will be flushed

Returns: current TagStructureContext instance

◆ GetAutoTaggingPointer()

virtual TagTreePointer iText.Kernel.Pdf.Tagutils.TagStructureContext.GetAutoTaggingPointer ( )

inlinevirtual

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.

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. 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).

Returns: the TagTreePointer which is used for all automatic tagging of the document.

◆ GetDocumentDefaultNamespace()

virtual PdfNamespace iText.Kernel.Pdf.Tagutils.TagStructureContext.GetDocumentDefaultNamespace ( )

inlinevirtual

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).

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 iText.Kernel.Pdf.Tagging.StandardNamespaces.PDF_2_0.

This value has meaning only for the PDF documents of version 2.0 and higher.

Returns: a iText.Kernel.Pdf.Tagging.PdfNamespace which is used as a default value for the document tagging.

◆ GetPointerStructElem()

virtual PdfStructElem iText.Kernel.Pdf.Tagutils.TagStructureContext.GetPointerStructElem ( TagTreePointer pointer )

inlinevirtual

Gets iText.Kernel.Pdf.Tagging.PdfStructElem at which TagTreePointer points.

NOTE: Be aware that iText.Kernel.Pdf.Tagging.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 iText.Kernel.Pdf.Tagging.PdfStructElem.

Returns: a iText.Kernel.Pdf.Tagging.PdfStructElem at which given TagTreePointer points.

◆ GetRoleMappingResolver() [1/2]

virtual IRoleMappingResolver iText.Kernel.Pdf.Tagutils.TagStructureContext.GetRoleMappingResolver ( String role )

inlinevirtual

Gets an instance of the IRoleMappingResolver corresponding to the current tag structure target version.

Gets an instance of the IRoleMappingResolver corresponding to the current tag structure target version. This method implies that role is in the default standard structure namespace.

Parameters

role	a role in the default standard structure namespace which mapping is to be resolved.

Returns: a IRoleMappingResolver instance, with the giving role as current.

◆ GetRoleMappingResolver() [2/2]

virtual IRoleMappingResolver iText.Kernel.Pdf.Tagutils.TagStructureContext.GetRoleMappingResolver	(	String	role,
		PdfNamespace @	namespace
	)

inlinevirtual

Gets an instance of the IRoleMappingResolver corresponding to the current tag structure target version.

Parameters

role	a role in the given namespace which mapping is to be resolved.
namespace	a iText.Kernel.Pdf.Tagging.PdfNamespace which this role belongs to.

Returns: a IRoleMappingResolver instance, with the giving role in the given iText.Kernel.Pdf.Tagging.PdfNamespace as current.

◆ GetTagPointerById()

virtual TagTreePointer iText.Kernel.Pdf.Tagutils.TagStructureContext.GetTagPointerById ( byte[] id )

inlinevirtual

Retrieve a pointer to a structure element by ID.

Parameters

id	the ID of the element to retrieve

Returns: a TagTreePointer to the element in question, or null if there is none.

◆ GetTagPointerByIdString()

virtual TagTreePointer iText.Kernel.Pdf.Tagutils.TagStructureContext.GetTagPointerByIdString ( String id )

inlinevirtual

Retrieve a pointer to a structure element by ID.

Retrieve a pointer to a structure element by ID. * The ID will be encoded as a UTF-8 string and passed to GetTagPointerById(byte[]).

Parameters

id	the ID of the element to retrieve

Returns: a TagTreePointer to the element in question, or null if there is none.

◆ GetTagStructureTargetVersion()

virtual PdfVersion iText.Kernel.Pdf.Tagutils.TagStructureContext.GetTagStructureTargetVersion ( )

inlinevirtual

Gets the version of the PDF standard to which the tag structure shall adhere.

Returns: the tag structure target version

◆ GetWaitingTagsManager()

virtual WaitingTagsManager iText.Kernel.Pdf.Tagutils.TagStructureContext.GetWaitingTagsManager ( )

inlinevirtual

Gets WaitingTagsManager for the current document.

Gets 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.

Returns: document's WaitingTagsManager class instance.

◆ NormalizeDocumentRootTag()

virtual void iText.Kernel.Pdf.Tagutils.TagStructureContext.NormalizeDocumentRootTag ( )

inlinevirtual

Transforms root tags in a way that complies with the tagged PDF specification.

Transforms root tags in a way that complies with the tagged PDF specification. Depending on PDF version behaviour may differ.
ISO 32000-1 (PDF 1.7 and lower) 14.8.4.2 Grouping Elements
"In a tagged PDF document, the structure tree shall contain a single top-level element; that is, the structure tree root (identified by the StructTreeRoot entry in the document catalogue) shall have only one child in its K (kids) array. If the PDF file contains a complete document, the structure type Document should be used 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."
For PDF 2.0 and higher root tag is allowed to have only the Document role.

◆ PrepareToDocumentClosing()

virtual void iText.Kernel.Pdf.Tagutils.TagStructureContext.PrepareToDocumentClosing ( )

inlinevirtual

A utility method that prepares the current instance of the TagStructureContext for the closing of document.

A utility method that prepares the current instance of the TagStructureContext for the closing of document. Essentially it flushes all the "hanging" information to the document.

◆ RemoveAnnotationTag() [1/2]

virtual TagTreePointer iText.Kernel.Pdf.Tagutils.TagStructureContext.RemoveAnnotationTag ( PdfAnnotation annotation )

inlinevirtual

Removes annotation content item from the tag structure.

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

Parameters

annotation the iText.Kernel.Pdf.Annot.PdfAnnotation that will be removed from the tag structure

Returns

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

◆ RemoveAnnotationTag() [2/2]

virtual TagTreePointer iText.Kernel.Pdf.Tagutils.TagStructureContext.RemoveAnnotationTag	(	PdfAnnotation	annotation,
		bool	setAutoTaggingPointer
	)

inlinevirtual

Removes annotation content item from the tag structure and sets autoTaggingPointer if true is passed.

Removes annotation content item from the tag structure and sets autoTaggingPointer if true is passed. If annotation is not added to the document or is not tagged, nothing will happen.

Parameters

annotation	the iText.Kernel.Pdf.Annot.PdfAnnotation that will be removed from the tag structure
setAutoTaggingPointer	true if TagTreePointer should be set to autoTaggingPointer

Returns

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

◆ RemoveContentItem()

virtual TagTreePointer iText.Kernel.Pdf.Tagutils.TagStructureContext.RemoveContentItem	(	PdfPage	page,
		int	mcid
	)

inlinevirtual

Removes content item from the tag structure.

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()

virtual iText.Kernel.Pdf.Tagutils.TagStructureContext iText.Kernel.Pdf.Tagutils.TagStructureContext.RemovePageTags ( PdfPage page )

inlinevirtual

Removes all tags that belong only to this page.

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

Parameters

page	page that defines which tags are to be removed

Returns: current TagStructureContext instance

◆ ResolveMappingToStandardOrDomainSpecificRole()

virtual IRoleMappingResolver iText.Kernel.Pdf.Tagutils.TagStructureContext.ResolveMappingToStandardOrDomainSpecificRole	(	String	role,
		PdfNamespace @	namespace
	)

inlinevirtual

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.

Parameters

role	a role in the given namespace which mapping is to be resolved.
namespace	a iText.Kernel.Pdf.Tagging.PdfNamespace which this role belongs to.

Returns: an instance of the 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.

◆ SetDocumentDefaultNamespace()

virtual iText.Kernel.Pdf.Tagutils.TagStructureContext iText.Kernel.Pdf.Tagutils.TagStructureContext.SetDocumentDefaultNamespace ( PdfNamespace @ namespace )

inlinevirtual

Sets a namespace that will be used as a default value for the tagging for any new TagTreePointer created.

Sets a namespace that will be used as a default value for the tagging for any new TagTreePointer created. See GetDocumentDefaultNamespace() for more info.

Be careful when changing this property value. It is most recommended doing it right after the iText.Kernel.Pdf.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.

Parameters

namespace a iText.Kernel.Pdf.Tagging.PdfNamespace which is to be used as a default value for the document tagging.

Returns: current TagStructureContext instance.

◆ SetForbidUnknownRoles()

virtual iText.Kernel.Pdf.Tagutils.TagStructureContext iText.Kernel.Pdf.Tagutils.TagStructureContext.SetForbidUnknownRoles ( bool forbidUnknownRoles )

inlinevirtual

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.

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.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ TagStructureContext() [1/2]

◆ TagStructureContext() [2/2]

Member Function Documentation

◆ CheckIfRoleShallBeMappedToStandardRole()

◆ CreatePointerForStructElem()

◆ FetchNamespace()

◆ FlushPageTags()

◆ GetAutoTaggingPointer()

◆ GetDocumentDefaultNamespace()

◆ GetPointerStructElem()

◆ GetRoleMappingResolver() [1/2]

◆ GetRoleMappingResolver() [2/2]

◆ GetTagPointerById()

◆ GetTagPointerByIdString()

◆ GetTagStructureTargetVersion()

◆ GetWaitingTagsManager()

◆ NormalizeDocumentRootTag()

◆ PrepareToDocumentClosing()

◆ RemoveAnnotationTag() [1/2]

◆ RemoveAnnotationTag() [2/2]

◆ RemoveContentItem()

◆ RemovePageTags()

◆ ResolveMappingToStandardOrDomainSpecificRole()

◆ SetDocumentDefaultNamespace()

◆ SetForbidUnknownRoles()