SetStructElemID

Tagged PDF, Accessibility

Description

Assigns a unique identity string to the structure element currently open on the tag stack. The ID is written as the /ID entry in the structure element dictionary and is indexed in the document's /IDTree name tree so that other elements can reference it (for example, via the /Headers attribute of table cells). Call this after BeginTag or BeginTagEx and before EndTag.

Syntax

Delphi

function TPDFlib.SetStructElemID(const ID: WideString): Integer;

ActiveX

Function PDFlib::SetStructElemID(ID As String) As Long

DLL

int DLSetStructElemID(int InstanceID, wchar_t * ID);

Parameters

ID	A non-empty string that uniquely identifies this structure element within the document. Choose an ID that is meaningful and unique across the entire document, such as `TH-Col-1`, `TH-Row-2`, or a GUID-like string.

Return value

Returns 1 on success. Returns 0 if no document is open, no tag is currently open on the tag stack, or ID is empty.

Remarks

The /ID entry is defined in ISO 32000-1 §14.7.3.4. All element IDs are gathered into a flat /IDTree name tree on the structure tree root when the document is saved; this allows accessibility tools and other elements to look up elements by ID. The /IDTree entries are sorted alphabetically by ID string.

A common use case is tagging table header cells (TH) with IDs so that data cells (TD) can associate themselves with the correct headers via SetStructElemHeaders. This association is required for complex tables under PDF/UA-1 (ISO 14289-1 §7.10) and WCAG 2.x Success Criterion 1.3.1.

If the same ID is assigned to multiple structure elements, behaviour is undefined; only one element per unique ID should receive a given ID string.

Example

// Tag a column header cell with an ID for later /Headers reference
PDFlib.BeginTag('TH', 'Product Name', '', '');
PDFlib.SetStructElemID('TH-ProductName');
PDFlib.SetStructElemScope('Column');
PDFlib.DrawText('Product Name', 100, 700);
PDFlib.EndTag;

PDFlib.BeginTag('TH', 'Price', '', '');
PDFlib.SetStructElemID('TH-Price');
PDFlib.SetStructElemScope('Column');
PDFlib.DrawText('Price', 250, 700);
PDFlib.EndTag;

// Tag a data cell referencing both header cells
PDFlib.BeginTag('TD', '', '', '');
PDFlib.SetStructElemHeaders('TH-ProductName,TH-Price');
PDFlib.DrawText('Widget A', 100, 680);
PDFlib.EndTag;