SetStructElemWritingMode

Tagged PDF, Accessibility

Description

Sets the /WritingMode attribute (Layout attribute owner) on the structure element currently open on the tag stack. The writing mode declares the principal writing direction of text within the element and affects how assistive technology interprets the reading order. Equivalent to calling AddTagAttribute with Owner=Layout, Name=WritingMode, and the mode name as the value.

Syntax

Delphi

function TPDFlib.SetStructElemWritingMode(const WritingMode: WideString): Integer;

ActiveX

Function PDFlib::SetStructElemWritingMode(WritingMode As String) As Long

DLL

int DLSetStructElemWritingMode(int InstanceID, wchar_t * WritingMode);

Parameters

WritingMode	The writing direction for the element. Must be one of the following values (case-sensitive): LrTb — left to right, top to bottom (default; Latin, Cyrillic, Greek, and most scripts) RlTb — right to left, top to bottom (Arabic, Hebrew) TbRl — top to bottom, right to left (traditional CJK vertical text)

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 or BeginTagEx and before EndTag. The /WritingMode attribute is defined in ISO 32000-1 §14.8.5.4.2 (Layout attribute owner, Table 340).

When a document uses a consistent writing direction throughout, it is not necessary to set /WritingMode on every element — the default LrTb applies when the attribute is absent. Set the attribute explicitly on block-level elements whose writing direction differs from the surrounding content, for example a Hebrew quotation embedded in an English paragraph.

PDF/UA-1 (ISO 14289-1 §7.2) requires that the natural language of every piece of text can be unambiguously determined. /WritingMode complements the /Lang attribute (SetStructElemLang): /Lang declares what language is spoken, while /WritingMode declares the physical writing direction assistive technology should use for presentation.

Example

// Arabic paragraph — right-to-left writing direction
PDFlib.BeginTagEx('P', '', '', 'ar-SA');
PDFlib.SetStructElemWritingMode('RlTb');
PDFlib.DrawText('...Arabic text...', 450, 700);
PDFlib.EndTag;

// Vertical CJK heading
PDFlib.BeginTagEx('H1', '', '', 'zh-TW');
PDFlib.SetStructElemWritingMode('TbRl');
PDFlib.DrawText('...CJK vertical text...', 500, 700);
PDFlib.EndTag;