SetStructElemAltText

Tagged PDF & Accessibility

Description

Sets the /Alt entry on the structure element currently being built on the tag stack. Alternative text is the text description that assistive technology (screen readers, braille displays) presents to users when the element cannot be rendered visually — for example, an image, figure, or mathematical formula.

This function is equivalent to passing a non-empty AltText argument to BeginTag or BeginTagEx, but allows the alternative text to be set or updated after the element has been opened. It is useful when the description is computed or retrieved asynchronously after the element type is known.

Syntax

Delphi

function TPDFlib.SetStructElemAltText(const AltText: WideString): Integer;

ActiveX

Function PDFlib::SetStructElemAltText(AltText As String) As Long

DLL

int DLSetStructElemAltText(int InstanceID, const wchar_t *AltText);
int DLSetStructElemAltTextA(int InstanceID, const char *AltText);

Parameters

AltText	The alternative text description 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 while the target element is at the top of the tag stack, or at any point before the matching EndTag call.

AltText and ActualText serve different purposes. AltText is a complete textual substitute for the entire element — it replaces the visual content for users who cannot perceive the rendered output. ActualText (ISO 32000-1 §14.9.4) provides the exact Unicode character sequence for inline glyphs whose extracted text would otherwise be incorrect (such as ligatures), and does not replace rendering. Screen readers typically speak AltText for Figure and Formula elements, and use ActualText for character-level corrections.

ISO 32000-1 §14.9.3 defines the /Alt entry. PDF/UA-1 (ISO 14289-1 §7.5) requires alternative descriptions on Figure and Formula structure elements. GetPDFUADiagnostics reports the FIGURE-NO-ALT:N issue code when Figure or Formula elements are missing Alt text.

Example

// Tag an embedded chart image with alternative text
PDFlib.BeginTag('Figure', '', '');
PDFlib.SetStructElemAltText('Bar chart: Q1 sales 120, Q2 sales 145, Q3 sales 98');
PDFlib.SetStructElemBBox(x, y, x + w, y + h);
PDFlib.DrawImage(imgHandle, x, y, w, h);
PDFlib.EndTag;