SetStructElemColSpan

Tagged PDF, Accessibility

Description

Sets the /ColSpan attribute (Table attribute owner) on the structure element currently open on the tag stack. The value indicates how many columns the current table cell spans. Equivalent to calling AddTagAttribute with Owner=Table, Name=ColSpan, and the integer value as a string.

Syntax

Delphi

function TPDFlib.SetStructElemColSpan(ColSpan: Integer): Integer;

ActiveX

Function PDFlib::SetStructElemColSpan(ColSpan As Long) As Long

DLL

int DLSetStructElemColSpan(int InstanceID, int ColSpan);

Parameters

ColSpan	The number of columns the current table cell spans. Must be a positive integer. A value of 1 means the cell occupies exactly one column (default behavior when no ColSpan is set). Values greater than 1 indicate a spanning header or data cell.

Return value

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

Remarks

Call this function after BeginTag (with tag type TH or TD) and before EndTag. The /ColSpan attribute is defined in ISO 32000-1 §14.8.5.7.2 (Table attribute owner, Table 337).

Spanning cells are common in complex tables — for example, a column header that spans two data columns. Providing the /ColSpan attribute allows assistive technology to correctly compute cell positions and associate headers with data cells across the entire table grid.

When a cell also spans multiple rows, use SetStructElemRowSpan in combination with this function.

Example

// A header cell spanning two columns
PDFlib.BeginTag('TH', 'Q1 and Q2 Revenue', '', '');
PDFlib.SetStructElemScope('Column');
PDFlib.SetStructElemColSpan(2);
PDFlib.DrawText('Q1 and Q2 Revenue', 100, 700);
PDFlib.EndTag;