SetStructElemHeaders

Tagged PDF, Accessibility

Description

Sets the /Headers attribute (Table attribute owner) on the structure element currently open on the tag stack. The attribute associates the current table data or header cell with one or more table header cells identified by their element IDs. This is used to describe complex table structures that cannot be inferred from position alone. Call this after BeginTag or BeginTagEx and before EndTag.

Syntax

Delphi

function TPDFlib.SetStructElemHeaders(const Headers: WideString): Integer;

ActiveX

Function PDFlib::SetStructElemHeaders(Headers As String) As Long

DLL

int DLSetStructElemHeaders(int InstanceID, wchar_t * Headers);

Parameters

Headers	A comma-separated list of element IDs of the TH cells that are column or row headers for the current TD or TH cell. Each ID must match an ElemID assigned to a TH element via SetStructElemID earlier in the same document. Whitespace around commas is ignored. Example: `TH-ProductName,TH-Price`.

Return value

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

Remarks

This function is equivalent to calling AddTagAttribute with Owner=Table, Name=Headers, and the same comma-separated ID list as Value. The attribute is written as a /Headers array of PDF text strings in the structure element's /A attribute dictionary.

The /Headers attribute is defined in ISO 32000-1 §14.8.5.7.2 (Table attribute owner). For simple tables where column headers are directly above their data cells, the /Scope attribute set via SetStructElemScope is generally sufficient. Use /Headers for irregular tables with spanning cells or multi-level headers.

PDF/UA-1 (ISO 14289-1 §7.10) requires that every TD cell be explicitly associated with its header cells in tables where the association cannot be determined from the reading order alone.

Example

// A data cell that spans two logical columns, referencing both headers
PDFlib.BeginTag('TD', '', '', '');
PDFlib.SetStructElemHeaders('TH-ProductName,TH-Price');
PDFlib.DrawText('Widget A  $9.99', 100, 660);
PDFlib.EndTag;