BeginTagEx2

Структурированный PDF и доступность

Описание

Открывает новый элемент структуры, кладёт его на стек тегов и задаёт все основные свойства одним вызовом. BeginTagEx2 — удобная обёртка над BeginTagEx и следующими за ним SetStructElemTitle, SetStructElemID и SetStructElemExpansion. Пустая строка в Title, ElemID или Expansion пропускает соответствующий сеттер; остальные параметры ведут себя как в BeginTagEx

Используйте BeginTagEx2, когда все описательные свойства элемента известны к моменту его открытия — это избавляет от череды сеттеров. Если какое-то свойство становится известно позже (например AltText приходит асинхронно), берите BeginTag или BeginTagEx и вызывайте отдельные сеттеры после

Синтаксис

Delphi

Function TPDFlib.BeginTagEx2(Const TagType, AltText, ActualText, Lang, Title, ElemID, Expansion: WideString): Integer;

ActiveX

Function PDFlib::BeginTagEx2(TagType As String, AltText As String, ActualText As String, Lang As String, Title As String, ElemID As String, Expansion As String) As Long

DLL

int DLBeginTagEx2(int InstanceID, const wchar_t * TagType, const wchar_t * AltText, const wchar_t * ActualText, const wchar_t * Lang, const wchar_t * Title, const wchar_t * ElemID, const wchar_t * Expansion);

Параметры

TagType	Имя типа элемента структуры, например `Figure`, `Table`, `Span`, `P`; те же типы, что принимает BeginTag
AltText	Альтернативный текст, записываемый в запись /Alt (ISO 32000-1 §14.9.3). Чтобы опустить запись, передайте пустую строку.
ActualText	Фактический текст, записываемый в запись /ActualText (ISO 32000-1 §14.9.4). Чтобы опустить запись, передайте пустую строку.
Lang	Языковой тег BCP 47, записываемый в запись /Lang (ISO 32000-1 §14.9.2), например `en-US`, `fr`, `zh-Hant-TW`. Чтобы унаследовать язык документа, передайте пустую строку.
Title	Понятная человеку метка, записываемая в запись /T (ISO 32000-1 §14.7.2). Показывается в навигационной панели тегов. Чтобы опустить запись, передайте пустую строку.
ElemID	Уникальный идентификатор элемента, записываемый в запись /ID (ISO 32000-1 §14.7.4). Если задан, должен быть уникальным в пределах документа. Чтобы опустить запись, передайте пустую строку.
Expansion	Расшифровка аббревиатуры, записываемая в запись /E (ISO 32000-1 §14.9.5). Чтобы опустить запись, передайте пустую строку.

Возвращаемое значение

Возвращает 1 при успехе, 0 если документ не выбран

Примечания

На каждый успешный вызов BeginTagEx2 нужен один вызов EndTag, снимающий элемент со стека тегов. Элементы структуры вкладываются: вызов BeginTagEx2 при открытом другом элементе создаёт дочерний

Внутренняя реализация в точности эквивалентна:

BeginTagEx(TagType, AltText, ActualText, Lang);
if Title <> '' then SetStructElemTitle(Title);
if ElemID <> '' then SetStructElemID(ElemID);
if Expansion <> '' then SetStructElemExpansion(Expansion);

Отдельные сеттеры остаются доступны для свойств, определяемых уже после открытия элемента, либо не охваченных BeginTagEx2 (например AddTagAttribute для атрибутов ячеек таблицы)

Пример

// Tag a figure with all descriptive properties in one call
PDFlib.BeginTagEx2(
  'Figure',                              // TagType
  'Bar chart: Q1 120, Q2 145, Q3 98',   // AltText
  '',                                    // ActualText (not needed for images)
  '',                                    // Lang (inherit document language)
  'Figure 3: Quarterly Sales',           // Title
  'fig-quarterly-sales',                 // ElemID
  ''                                     // Expansion (not an abbreviation)
);
PDFlib.SetStructElemBBox(x, y, x + w, y + h);
PDFlib.DrawImage(imgHandle, x, y, w, h);
PDFlib.EndTag;

// Tag an acronym span with its expansion
PDFlib.BeginTagEx2(
  'Span',
  '',                                          // AltText
  '',                                          // ActualText
  '',                                          // Lang
  '',                                          // Title
  '',                                          // ElemID
  'World Wide Web Consortium'                  // Expansion
);
PDFlib.WriteText('W3C');
PDFlib.EndTag;

См. также

BeginTag, BeginTagEx, EndTag, SetStructElemTitle, SetStructElemID, SetStructElemExpansion