Structure Tagging and Alternate Text in PDFs

Introduction

The Mako SDK has APIs to tag elements according to their purpose. Known as structure tags, they are not displayed in the document, but are used by assistive technology such as screen readers for the visually impaired to present the page content with a synthetic voice. Tags establish logical reading order and provide a means of indicating document structure and element type, adding alternative text to non-text elements or substitute text for elements in the PDF document.

Here we describe how to use Mako to tag a paragraph, an image and add alternate text to the image.

Code example

We begin by setting the tagged PDF property using IDOMMetadata. This is necessary so that a viewer is aware that tags are present in the document.

C#

  // Get or create the metadata
  IDOMMetadata metadata = assembly.getJobMetadata();
  if (metadata == null)
  {
        metadata = IDOMMetadata.create(factory);
  }
  // And add the Marked property - set tagged pdf property
  metadata.setProperty(IDOMMetadata.eType.ePDFInfo, "Marked", new PValue(true));

  assembly.setJobMetadata(metadata);

Next we create the IStructure which will be used to tag the content:

C#

 // Create the Structure which will be used to tag the content
 IStructure structure = IStructure.create(jawsMako);
 document.setStructure(structure);

 IStructureElement documentElement = IStructureElement.create(jawsMako, "Document");
 documentElement.setTitle("Example Title");
 structure.appendElement(documentElement);

We then create a paragraph structure element, and tag the relevant glyphs node. You can also tag a group node to tag all the nodes within the group.

C#

 // Create the paragraph structure element
 IStructureElement paragraphElement = IStructureElement.create(jawsMako, "P");
 documentElement.appendElement(structure, paragraphElement);

 IDOMGlyphs glyphsnode = node.getContentGlyphs();
 if (glyphsnode != null)
     structure.tagNode(paragraphElement, page, glyphsnode);

Finally, we tag an image and add to it alternate text. Alternate text is voiced by a screen reader, providing a description of the image content.

C#

 CEDLVectIDOMNode pathNodes = fixedPage.findChildrenOfType(eDOMNodeType.eDOMPathNode);

 foreach (var node in pathNodes.toArray())
 {
     IDOMPathNode pathNode = IDOMPathNode.fromRCObject(node);
     IDOMBrush brush = pathNode.getFill();

     if (brush != null && brush.getBrushType() == IDOMBrush.eBrushType.eImage)
     {
         IDOMImageBrush imageBrush = IDOMImageBrush.fromRCObject(brush);
         if (imageBrush != null)
         {
             IStructureElement imageElement = IStructureElement.create(jawsMako, "Figure");
             imageElement.setAlternate("Example of Alternate text");
             imageElement.setLanguage("en");
             IPDFDictionary attributes = IPDFDictionary.create(jawsMako);
             attributes.put("BBox", createPdfBBoxForNode(fixedPage, node));
             attributes.put("O", IPDFName.create(jawsMako, "Layout"));
             attributes.put("Placement", IPDFName.create(jawsMako, "Block"));
             imageElement.setAttributes(attributes);
             documentElement.appendElement(structure, imageElement);
             structure.tagNode(imageElement, page, node);
         }
     }
 }

Additional Information

This blog article on tagging elements in a PDF may be of interest. This GitHub code snippet may also be helpful.

Also included in the Mako SDK within the simpleexamples project is pdfuacreation.cpp (also .cs and .java) which contains additional examples of structure tagging, such as tables.