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);

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

Appelez cette fonction immédiatement après BeginTag pendant que l'élément cible est au sommet de la pile de balises (tag stack), ou à tout moment avant l'appel EndTag correspondant

AltText et ActualText servent des objectifs différents ; AltText est un substitut textuel complet pour l'ensemble de l'élément — il remplace le contenu visuel pour les utilisateurs qui ne peuvent pas percevoir la sortie rendue ; ActualText (ISO 32000-1 §14.9.4) fournit la séquence exacte de caractères Unicode pour les glyphes intégrés dont le texte extrait serait autrement incorrect (comme les ligatures), et ne remplace pas le rendu ; les lecteurs d'écran lisent généralement AltText pour les éléments Figure et Formula, et utilisent ActualText pour les corrections au niveau des caractères

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;