THotPDF.AddStructureElement und Tagged-PDF-Hilfsfunktionen

Diese Seite dokumentiert die aktuellen THotPDF Tagged-PDF- und PDF/UA-Strukturbaum-Hilfsfunktionen — Die Code-Bezeichner entsprechen den öffentlichen Deklarationen

Aktuelle Delphi-Schnittstelle

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;

Erstellen von Strukturelementen

AddStructureElement erstellt ein /StructElem-Dictionary und hängt es als untergeordnetes Element an Parent an (übergeben Sie nil, um es unter der Strukturbaumwurzel anzuhängen) — PageIndex verknüpft das Element über /Pg mit seiner Seite; übergeben Sie einen negativen Wert, um dies auszulassen; MCID, wenn null oder größer, verknüpft eine marked-content-Sequenz auf der Seite mit dem Element und registriert sie im /ParentTree des Dokuments; die Überladung mit sechs Argumenten fügt /Alt (alternative Beschreibung, die für Nicht-Text-Inhalte wie Abbildungen und Formeln vorgelesen wird) und /ActualText (Ersatztext, der durch Kopieren/Einfügen für schwer zu extrahierende Glyphen zurückgegeben wird) hinzu; die Überladung mit sieben Argumenten schreibt zusätzlich eine dokumentweit eindeutige /ID, damit andere Strukturelemente das Element per ID anvisieren können (ISO 32000-1 §14.7.2)

Standard-Strukturtypen (Tabelle 333)

Die Überladung mit dem Enum THPDFStandardStructureType ist der typsichere Einstiegspunkt: Es ist garantiert, dass der ausgegebene /S-Rollenname einer der Standard-Strukturtypen aus ISO 32000-1 §14.8.4 Tabelle 333 ist, wodurch Tippfehler und Probleme mit der Groß-/Kleinschreibung bei der Überladung mit freiem String vermieden werden — Das Enum gruppiert die Namen nach ihrer Spezifikationsfamilie:

Gruppierung: sstDocument, sstPart, sstArt, sstSect, sstDiv, sstBlockQuote, sstCaption, sstTOC, sstTOCI, sstIndex, sstNonStruct, sstPrivate
Blockebene: sstH, sstH1-sstH6, sstP, sstL, sstLI, sstLbl, sstLBody, sstTable, sstTR, sstTH, sstTD, sstTHead, sstTBody, sstTFoot
Inlineebene: sstSpan, sstQuote, sstNote, sstReference, sstBibEntry, sstCode, sstLink, sstAnnot
Ruby und Warichu: sstRuby, sstRB, sstRT, sstRP, sstWarichu, sstWT, sstWP
Illustration: sstFigure, sstFormula, sstForm

Beachten Sie die Kleinbuchstaben in sstLbl / sstLBody: Die buchstäblichen PDF-Rollennamen lauten Lbl und LBody — Benutzerdefinierte Rollennamen können weiterhin über die AnsiString-Überladung übergeben und mit AddStructRoleMap wieder einer Standardrolle zugeordnet werden

Beispiel

PDF.PDFUACompliance := pdfuaPDFUA1;
PDF.BeginDoc;
Doc := PDF.AddStructureElement(sstDocument, nil);
H1 := PDF.AddStructureElement(sstH1, Doc);
PDF.SetStructureElementLanguage(Doc, 'en-US');
PDF.SetStructureElementTitle(H1, 'Annual Report');
// Alt / ActualText ride on the AnsiString overload; reuse the
// spec-prescribed role name via StandardStructureTypeToName
Fig := PDF.AddStructureElement(StandardStructureTypeToName(sstFigure), Doc, 0, -1,
  'Sales by quarter: Q1 4.2M, Q2 5.1M, Q3 5.8M, Q4 6.4M', '');

Strukturattribute und Rollenzuordnung

SetStructureElementLanguage schreibt einen BCP-47 /Lang-Override, SetStructureElementExpansionText schreibt den /E-Erweiterungstext, SetStructureElementTitle schreibt den lesbaren /T-Titel und AddStructRoleMap ordnet benutzerdefinierte Strukturrollen wieder Standard-PDF-Rollen zu — StandardStructureTypeToName gibt den PDF-Rollennamen für einen THPDFStandardStructureType-Wert zurück, und IsStandardStructureType prüft, ob ein Rollenname eine der Standardrollen ist

High-Level Tagged-Hilfsfunktionen

EmitTaggedHeading, BeginTaggedList, EmitTaggedListItem, BeginTaggedTable, AddTaggedTableRow, EmitTaggedTableHeader, EmitTaggedTableCell, BeginTaggedFigure, EndTaggedFigure und RegisterAnnotForStructure decken gängige PDF/UA-Überschriften-, Listen-, Tabellen-, Abbildungs- und Anmerkungsverknüpfungen ab, ohne dass Aufrufer gezwungen sind, MCIDs manuell zu verwalten

Typischer Arbeitsablauf

Aktivieren Sie die getaggte Ausgabe oder PDFUACompliance, erstellen Sie das Wurzel-Strukturelement, verwenden Sie die Hilfsfunktionen zur Ausgabe semantischer Inhalte und schließen Sie jede begonnene getaggte Inhalts- oder Abbildungssequenz vor EndDoc