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.

Use BeginTagEx2 when you already know all the descriptive properties of an element at the time you open it, to avoid several consecutive setter calls. If any property is determined later (for example, the AltText arrives asynchronously), use BeginTag or BeginTagEx and call the individual setters afterwards.

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	The structure element type name, e.g. `Figure`, `Table`, `Span`, `P`. The same types accepted by BeginTag.
AltText	Texte alternatif écrit dans l'entrée /Alt (ISO 32000-1 §14.9.3) ; passez une chaîne vide pour l'omettre
ActualText	Texte réel écrit dans l'entrée /ActualText (ISO 32000-1 §14.9.4) ; passez une chaîne vide pour l'omettre
Lang	Balise de langue BCP 47 écrite dans l'entrée /Lang (ISO 32000-1 §14.9.2), par exemple `en-US`, `fr`, `zh-Hant-TW` ; passez une chaîne vide pour hériter de la langue du document
Title	Human-readable label written to the /T entry (ISO 32000-1 §14.7.2). Shown in the Tags navigation panel. Pass an empty string to omit.
ElemID	Unique element identifier written to the /ID entry (ISO 32000-1 §14.7.4). Must be unique within the document if set. Pass an empty string to omit.
Expansion	Expansion of an abbreviation or acronym written to the /E entry (ISO 32000-1 §14.9.5). Pass an empty string to omit.

Return value

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

Remarks

Appelez EndTag une fois pour chaque appel réussi à BeginTagEx2 afin de retirer l'élément de la pile de balises (tag stack) ; les éléments de structure peuvent être imbriqués : appeler BeginTagEx2 alors qu'un autre élément est ouvert crée un élément enfant

The internal implementation is exactly equivalent to:

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

Individual setters remain available for properties determined after the element is opened, or for properties not covered by BeginTagEx2 (such as AddTagAttribute for table cell attributes).

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;