SetStructElemExpansion

Tagged PDF & Accessibility

Description

Sets the /E (expansion text) entry on the structure element currently being built on the tag stack. The expansion text is the fully spelled-out form of an abbreviation or acronym contained in the element — for example World Wide Web for a Span element whose content reads WWW, or International Organization for Standardization for a Span containing ISO.

Screen readers and other assistive technology speak the expansion text rather than attempting to pronounce the abbreviated characters, which is essential for abbreviations that cannot be sounded out as words.

Syntax

Delphi

function TPDFlib.SetStructElemExpansion(const Expansion: WideString): Integer;

ActiveX

Function PDFlib::SetStructElemExpansion(Expansion As String) As Long

DLL

int DLSetStructElemExpansion(int InstanceID, const wchar_t *Expansion);
int DLSetStructElemExpansionA(int InstanceID, const char *Expansion);

Parameters

Expansion	The fully expanded text of the abbreviation or acronym in 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 while the target element is at the top of the tag stack, or at any point before the matching EndTag call.

The /E entry is defined in ISO 32000-1 §14.9.5. It is written as a PDF text string in the structure element dictionary and is distinct from the other text properties:

/E (Expansion) — The spelled-out form of an abbreviation or acronym. Used for screen reader pronunciation of abbreviated inline content.
/Alt (see SetStructElemAltText) — A complete substitute description for elements that cannot be rendered visually (images, figures, formulas).
/ActualText (see SetStructElemActualText) — An exact Unicode replacement for glyph sequences whose extracted text would otherwise be incorrect (ligatures, glyph variants).

PDF/UA-1 (ISO 14289-1 §7.2) requires that the natural language of every piece of text be unambiguously determinable. For abbreviations and acronyms where the abbreviated form cannot be read aloud as a word, /E is the standard mechanism to provide that information.

Apply /E on the innermost element that wraps the abbreviation — typically a Span element. The expansion applies only to the content of that element and is not inherited by children.

Example

// Tag an abbreviation with its expansion
PDFlib.BeginTag('Span', '', '');
PDFlib.SetStructElemExpansion('World Wide Web');
PDFlib.WriteText('WWW');
PDFlib.EndTag;

// Tag a standards acronym
PDFlib.BeginTag('Span', '', '');
PDFlib.SetStructElemExpansion('International Organization for Standardization');
PDFlib.WriteText('ISO');
PDFlib.EndTag;