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);
int DLSetStructElemActualTextA(int InstanceID, const char *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

Call this function immediately after BeginTag or BeginTagEx while the target element is at the top of the tag stack.

ActualText and AltText serve different purposes. AltText (set via the AltText parameter of BeginTag) is an alternative representation of the entire element intended for assistive technology when the visual content cannot be rendered. ActualText supplements content-stream text extraction: it replaces the extracted character sequence of the element but does not suppress rendering. Screen readers that support both will typically use ActualText for read-aloud output when present.

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;