THotPDF.AddStructureElement and Tagged PDF Helpers
This page documents the current THotPDF tagged-PDF and PDF/UA structure-tree helpers. Code identifiers match the public declarations
Current Delphi Surface
function AddStructureElement(const Role: AnsiString; Parent: THPDFDictionaryObject;
PageIndex: Integer = -1; MCID: Integer = -1): THPDFDictionaryObject; overload;
function AddStructureElement(const Role: AnsiString; Parent: THPDFDictionaryObject;
PageIndex: Integer; MCID: Integer;
const AltText: AnsiString; const ActualText: AnsiString): THPDFDictionaryObject; overload;
function AddStructureElement(const Role: AnsiString; Parent: THPDFDictionaryObject;
PageIndex: Integer; MCID: Integer;
const AltText: AnsiString; const ActualText: AnsiString;
const IDStr: AnsiString): THPDFDictionaryObject; overload;
function AddStructureElement(T: THPDFStandardStructureType; Parent: THPDFDictionaryObject;
PageIndex: Integer = -1; MCID: Integer = -1): THPDFDictionaryObject; overload;
procedure SetStructureElementLanguage(Elem: THPDFDictionaryObject; const Lang: AnsiString);
procedure SetStructureElementExpansionText(Elem: THPDFDictionaryObject; const ExpansionText: AnsiString);
procedure SetStructureElementTitle(Elem: THPDFDictionaryObject; const Title: AnsiString);
procedure AddStructRoleMap(const SourceRole: AnsiString; const TargetRole: AnsiString);
function BeginTaggedContent(const Role: AnsiString; Parent: THPDFDictionaryObject;
const Lang: AnsiString = ''; const Alt: AnsiString = '';
const ActualText: AnsiString = ''; const ExpansionText: AnsiString = ''): THPDFDictionaryObject;
procedure EndTaggedContent;
function EmitTaggedHeading(Level: Integer; Parent: THPDFDictionaryObject; X, Y: Single; const Text: WideString): THPDFDictionaryObject;
function BeginTaggedList(Parent: THPDFDictionaryObject; const NumberingStyle: AnsiString = 'None'): THPDFDictionaryObject;
function EmitTaggedListItem(ListElem: THPDFDictionaryObject; LblX, LblY: Single; const LabelText: WideString; BodyX, BodyY: Single; const BodyText: WideString): THPDFDictionaryObject;
function BeginTaggedTable(Parent: THPDFDictionaryObject): THPDFDictionaryObject;
function AddTaggedTableRow(TableElem: THPDFDictionaryObject): THPDFDictionaryObject;
function EmitTaggedTableHeader(TRElem: THPDFDictionaryObject; X, Y: Single; const Text: WideString; const Scope: AnsiString): THPDFDictionaryObject;
function EmitTaggedTableCell(TRElem: THPDFDictionaryObject; X, Y: Single; const Text: WideString): THPDFDictionaryObject;
function BeginTaggedFigure(Parent: THPDFDictionaryObject; const AltText: AnsiString; const BBox: array of Single): THPDFDictionaryObject;
procedure EndTaggedFigure;
procedure RegisterAnnotForStructure(AnnotDict: THPDFDictionaryObject; StructElem: THPDFDictionaryObject);
function StandardStructureTypeToName(T: THPDFStandardStructureType): AnsiString;
function IsStandardStructureType(const Name: AnsiString): Boolean;Creating Structure Elements
AddStructureElement creates a /StructElem dictionary and appends it as a child of Parent (pass nil to attach under the structure tree root). PageIndex links the element to its page via /Pg; pass a negative value to omit. MCID, when zero or greater, associates a marked-content sequence on the page with the element and registers it in the document /ParentTree. The six-argument overload adds /Alt (alternative description read aloud for non-text content such as figures and formulas) and /ActualText (replacement text returned by copy/paste for hard-to-extract glyphs). The seven-argument overload additionally writes a document-unique /ID so other structure elements can target the element by ID (ISO 32000-1 §14.7.2)
Standard Structure Types (Table 333)
The THPDFStandardStructureType enum overload is the type-safe entry point: the emitted /S role name is guaranteed to be one of the standard structure types of ISO 32000-1 §14.8.4 Table 333, eliminating the typo and case-sensitivity hazard of the open-string overload. The enum groups the names by their specification family:
- Grouping:
sstDocument,sstPart,sstArt,sstSect,sstDiv,sstBlockQuote,sstCaption,sstTOC,sstTOCI,sstIndex,sstNonStruct,sstPrivate - Block-level:
sstH,sstH1-sstH6,sstP,sstL,sstLI,sstLbl,sstLBody,sstTable,sstTR,sstTH,sstTD,sstTHead,sstTBody,sstTFoot - Inline-level:
sstSpan,sstQuote,sstNote,sstReference,sstBibEntry,sstCode,sstLink,sstAnnot - Ruby and Warichu:
sstRuby,sstRB,sstRT,sstRP,sstWarichu,sstWT,sstWP - Illustration:
sstFigure,sstFormula,sstForm
Note the lowercase letters in sstLbl / sstLBody: the literal PDF role names are Lbl and LBody. Custom role names can still be passed through the AnsiString tagged-PDF and PDF/UA structure-tree helpers. Code identifiers match the public declarations in Lib/HPDFDoc.pas
Current Delphi Surface
procedure SetStructureElementLanguage(Elem: THPDFDictionaryObject; const Lang: AnsiString);
procedure SetStructureElementExpansionText(Elem: THPDFDictionaryObject; const ExpansionText: AnsiString);
procedure SetStructureElementTitle(Elem: THPDFDictionaryObject; const Title: AnsiString);
procedure AddStructRoleMap(const SourceRole: AnsiString; const TargetRole: AnsiString);
function BeginTaggedContent(const Role: AnsiString; Parent: THPDFDictionaryObject;
const Lang: AnsiString = ''; const Alt: AnsiString = '';
const ActualText: AnsiString = ''; const ExpansionText: AnsiString = ''): THPDFDictionaryObject;
procedure EndTaggedContent;
function EmitTaggedHeading(Level: Integer; Parent: THPDFDictionaryObject; X, Y: Single; const Text: WideString): THPDFDictionaryObject;
function BeginTaggedList(Parent: THPDFDictionaryObject; const NumberingStyle: AnsiString = 'None'): THPDFDictionaryObject;
function EmitTaggedListItem(ListElem: THPDFDictionaryObject; LblX, LblY: Single; const LabelText: WideString; BodyX, BodyY: Single; const BodyText: WideString): THPDFDictionaryObject;
function BeginTaggedTable(Parent: THPDFDictionaryObject): THPDFDictionaryObject;
function AddTaggedTableRow(TableElem: THPDFDictionaryObject): THPDFDictionaryObject;
function EmitTaggedTableHeader(TRElem: THPDFDictionaryObject; X, Y: Single; const Text: WideString; const Scope: AnsiString): THPDFDictionaryObject;
function EmitTaggedTableCell(TRElem: THPDFDictionaryObject; X, Y: Single; const Text: WideString): THPDFDictionaryObject;
function BeginTaggedFigure(Parent: THPDFDictionaryObject; const AltText: AnsiString; const BBox: array of Single): THPDFDictionaryObject;
procedure EndTaggedFigure;
procedure RegisterAnnotForStructure(AnnotDict: THPDFDictionaryObject; StructElem: THPDFDictionaryObject);
function StandardStructureTypeToName(T: THPDFStandardStructureType): AnsiString;
function IsStandardStructureType(const Name: AnsiString): Boolean;Structure Attributes and Role Mapping
SetStructureElementLanguage writes a BCP-47 /Lang override, SetStructureElementExpansionText writes the /E expansion text, SetStructureElementTitle writes the human-readable /T title, and AddStructRoleMap maps custom structure roles back to standard PDF roles. StandardStructureTypeToName returns the PDF role name for a THPDFStandardStructureType value, and IsStandardStructureType checks whether a role name is one of the standard roles
High-Level Tagged Helpers
EmitTaggedHeading, BeginTaggedList, EmitTaggedListItem, BeginTaggedTable, AddTaggedTableRow, EmitTaggedTableHeader, EmitTaggedTableCell, BeginTaggedFigure, EndTaggedFigure, and RegisterAnnotForStructure cover common PDF/UA heading, list, table, figure, and annotation wiring without forcing callers to manage MCIDs manually
Typical Workflow
Enable tagged output or PDFUACompliance, create the root structure element, use the helper family to emit semantic content, and close every begun tagged-content or figure sequence before EndDoc
Continuation-safe authoring
BeginTaggedContentForStructure and AppendStructureMarkedContent attach page-local marked-content references to one existing logical structure element across page continuations
Automatic PDF/UA Structure from Layout Trees applies the same model to declarative headings, lists, tables, figures, and artifacts