PeachDrawing.PDF

PdfTagRecorder Class

Records the logical structure of a document - headings, paragraphs, lists, figures, links - while its pages are drawn, so the file is a tagged PDF: a reader can navigate it by structure, and assistive technology can read it in order.

public sealed class PdfTagRecorder

Inheritance System.Object → PdfTagRecorder

Remarks

Get one from CreateTagRecorder(bool), call BeginPage(PdfComposerPage) as each page is added, and wrap the drawing of each piece of content in the scope an Open method returns: OpenContentElement(Canvas, object, string, string) tags what is drawn inside it (a paragraph’s text), OpenGroupingElement(object, string) nests the elements opened inside it (a list around its items), and OpenArtifact(Canvas) marks decoration that is not part of the structure. Call Finish() after the last page and before adding links that should be tied to structure elements.

Elements are identified by a key of the caller’s choosing - any object with value or reference equality will do - so the same piece of content drawn again (on the next page, when it spans a page break) lands in the same structure element.

Properties  
IsInMarkedContent Whether what is drawn now lands inside a marked-content sequence already - a content element’s or an artifact’s. Marked content cannot nest, so a caller about to open an artifact for drawing that may be reached from inside another element’s content checks this first.
Methods  
AttachMathMlSource(object, string) Attaches MathML markup to a formula’s structure element as a PDF 2.0 associated file (ISO 32000-2 §14.13, /AFRelationship /Supplement), so assistive technology can read the formula, and indexes it in the document-level /AF array. Does nothing if the key never opened a content element, or if its source was attached already (a formula that spans a page break is drawn more than once).
BeginPage(PdfComposerPage) Starts recording a page. Call it once per page, right after the page is added and before it is drawn.
CheckStructure() Checks the structure recorded so far against requirements of tagged accessible documents (the Matterhorn Protocol’s structural checkpoints) that the file’s content decides and no writer can: a heading that skips a level, a table with no header cell, a figure with no description. Call it after Finish(). It reports, it does not throw: a document can be legitimate and still trip one.
DeclareElement(object, string, object, PdfStructureDetails, bool) Creates the structure element for key now, in the position it is declared, without any content of its own. Declaring the elements of a piece of structure in their logical order before drawing it keeps that order in the tree, where creating each when its content is first drawn would follow the order of drawing. An element opened later with the same key is this one.
DeclareListItemBody(object) Creates the body element of the list item declared with itemKey, in its place under the item.
Finish() Completes the structure tree after the last page: writes each page’s entry in the parent tree and, when the document has a title, asks readers to show it (required once a document is tagged). Call it before LinkAnnotation(object, PdfLink).
HasElement(object) Whether a structure element has been created for key.
LinkAnnotation(object, PdfLink) Ties a link to the structure element of the content it covers, so a reader can reach one from the other (PDF/UA): the element gets a reference to the link in its content, and the link points back at the element. Call it after Finish(), once per link. Does nothing if the key never opened a Link element (tagging was suppressed for it).
LinkAnnotation(object, PdfLink, string, object) Ties a link to the structure element of the content it covers, and gives the link annotation contents as its /Contents: the description a reader announces for the link (PDF/UA requires one on every link).
OpenArtifact(Canvas) Marks everything drawn on canvas until the returned scope is disposed as an artifact: decoration that is not part of the document’s logical structure (a rule, a background).
OpenContentElement(Canvas, object, string, string) Opens a content structure element for key: creates it the first time the key is seen, allocates a marked-content id, and marks everything drawn on canvas until the returned scope is disposed as that element’s content. Content that spans a page break is recorded on each page it lands on. A content element is a leaf: it does not become the parent of elements opened inside it.
OpenContentElement(Canvas, object, string, string, PdfStructureDetails) Opens a content element as OpenContentElement(Canvas, object, string, string) does, giving it a language, a title or attributes the first time it is opened.
OpenGroupingElement(object, string) Opens a grouping structure element for key (a list, a section, a table row): creates it the first time the key is seen, links it to the current parent, and makes it the parent of every element opened inside the returned scope. It carries no content of its own.
OpenGroupingElement(object, string, PdfStructureDetails) Opens a grouping structure element as OpenGroupingElement(object, string) does, giving it a language, a title or attributes the first time it is opened.
OpenListItemBodyElement(object) Opens the body element of a list item, inside the list item element opened with the same key. It is a grouping element with its own cache, because the list item itself already owns a distinct element under that key.