SetStructElemActualText

Tagged PDF & Accessibility

Description

Sets the /ActualText entry on the structure element currently being built on the tag stack. ActualText provides the exact Unicode text that the element represents, overriding any text extracted from the PDF content stream by reader software.

Use this function when the glyphs rendered in the content stream do not directly map to their intended reading-order characters — for example, a ligature glyph (ﬀ, ﬁ, ﬂ) that should read as the two-character sequence ff, fi, or fl. Without ActualText, text-extraction tools and screen readers may produce incorrect output for such glyphs.

Syntax

Delphi

Function TPDFlib.SetStructElemActualText(Const ActualText: WideString): Integer;

ActiveX

Function PDFlib::SetStructElemActualText(ActualText As String) As Long

DLL

int DLSetStructElemActualText(int InstanceID, const wchar_t * ActualText);

Parameters

ActualText	The Unicode text string to associate with the current structure element. Pass an empty string to clear a previously set value.

Return value

Returns 1 on success, 0 if no structure element is currently open or no document is selected.

Remarks

Appelez cette fonction immédiatement après BeginTag ou BeginTagEx pendant que l'élément cible est au sommet de la pile de balises (tag stack)

ActualText et AltText servent des objectifs différents ; AltText (défini via le paramètre AltText de BeginTag) est une représentation alternative de l'élément entier destinée aux technologies d'assistance lorsque le contenu visuel ne peut pas être rendu ; ActualText complète l'extraction de texte du flux de contenu : il remplace la séquence de caractères extraite de l'élément mais ne supprime pas le rendu ; les lecteurs d'écran qui prennent en charge les deux utiliseront généralement ActualText pour la sortie vocale lorsqu'il est présent

ISO 32000-1 §14.9.4 defines ActualText as a PDF text string entry on the structure element dictionary. PDF/UA-1 (ISO 14289-1 §7.1) requires that text content be extractable and correct; ActualText is the standard mechanism to satisfy this requirement for glyph sequences whose direct extraction would be ambiguous or incorrect.

Example

// Tag a ligature glyph so that text extraction yields "fi"
PDFlib.BeginTag('Span', '', '');
PDFlib.SetStructElemActualText('fi');
PDFlib.TextOut(x, y, #$FB01);   // U+FB01 LATIN SMALL LIGATURE FI
PDFlib.EndTag;