BeginTagEx2

Tagged PDF & Accessibility

Description

Opens a new structure element and pushes it onto the tag stack, setting all main element properties in a single call. BeginTagEx2 is a convenience wrapper for BeginTagEx followed by SetStructElemTitle, SetStructElemID, and SetStructElemExpansion. Passing an empty string for any of Title, ElemID, or Expansion skips the corresponding setter; the other parameters behave identically to BeginTagEx.

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

Syntax

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);

Parameters

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); передайте пустую строку для исключения

Return value

Returns 1 on success, 0 if no document is selected.

Remarks

Вызывайте EndTag один раз для каждого успешного вызова BeginTagEx2, чтобы извлечь элемент из стека тегов; структурные элементы могут быть вложенными: вызов BeginTagEx2 при открытом другом элементе создает дочерний элемент

Внутренняя реализация полностью эквивалентна следующему

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

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

Example

// 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;