AddRoleMap

Tagged PDF, Accessibility

Description

Registers a mapping from a custom structure-element type name to a standard PDF structure type in the document's RoleMap dictionary.

When tagged PDF content uses non-standard tag names (e.g. company-specific or application-specific element types), the PDF specification requires those names to be mapped to a standard PDF structure type in the structure tree root's /RoleMap entry. ISO 14289-1 §7.1 mandates this mapping for all PDF/UA-1 documents that contain non-standard structure element types.

Call AddRoleMap once per custom type, before calling BeginTag or BeginTagEx with that type. Multiple mappings can be registered. If the same custom type is registered more than once, the last mapping wins.

The RoleMap is written to the structure tree root when the document is saved, if at least one mapping has been registered.

Syntax

Delphi

function TPDFlib.AddRoleMap(const CustomType, StandardType: WideString): Integer;

ActiveX

Function PDFlib::AddRoleMap(CustomType As String, StandardType As String) As Long

DLL

int DLAddRoleMap(int InstanceID, wchar_t* CustomType, wchar_t* StandardType);
int DLAddRoleMapA(int InstanceID, char* CustomType, char* StandardType);

Parameters

Return values

Example

// Document with custom element types mapped to standard PDF structure types
PDF.SetPDFUAMode('en-US');
PDF.AddRoleMap('Headline', 'H1');
PDF.AddRoleMap('Subheadline', 'H2');
PDF.AddRoleMap('Caption', 'P');

PDF.BeginTag('Headline', '', '');
PDF.PrintText(50, 750, 'Annual Report 2026');
PDF.EndTag;

PDF.BeginTag('Subheadline', '', '');
PDF.PrintText(50, 720, 'Financial Highlights');
PDF.EndTag;