AddRoleMapA

Tagged PDF, Accessibility

Description

The trailing A denotes the ANSI (char) DLL entry point; the ActiveX/COM surface exposes only the Unicode form. Behaviour is identical to AddRoleMap and string arguments are interpreted using the current SetAnsiMode code page

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 DLAddRoleMapA(InstanceID: Integer; CustomType, StandardType: PAnsiChar): Integer;

DLL

int DLAddRoleMapA(int InstanceID, const char * CustomType, const char * StandardType);

Parameters

CustomType	The custom (non-standard) structure element type name used in BeginTag or BeginTagEx calls, e.g. `Headline`, `Caption`, `Callout`.
StandardType	The standard PDF structure type that the custom type maps to: `P`, `H1`–`H6`, `Figure`, `Table`, `Span`, `Link`, `Note`, etc. (see ISO 32000-1 §14.8.4). Must be a recognized standard type for the mapping to satisfy PDF/UA conformance checkers.

Return values

0	Failed (no document is open)
1	Mapping registered successfully

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;