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);
int DLBeginTagEx2A(int InstanceID,
  const char *TagType, const char *AltText, const char *ActualText,
  const char *Lang, const char *Title, const char *ElemID,
  const char *Expansion);

Parameters

TagType	The structure element type name, e.g. `Figure`, `Table`, `Span`, `P`. The same types accepted by BeginTag.
AltText	Alternative text written to the /Alt entry (ISO 32000-1 §14.9.3). Pass an empty string to omit.
ActualText	Actual text written to the /ActualText entry (ISO 32000-1 §14.9.4). Pass an empty string to omit.
Lang	BCP 47 language tag written to the /Lang entry (ISO 32000-1 §14.9.2), e.g. `en-US`, `fr`, `zh-Hant-TW`. Pass an empty string to inherit the document language.
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

Call EndTag once for each successful BeginTagEx2 call to pop the element from the tag stack. Structure elements may be nested: calling BeginTagEx2 while another element is open creates a child element.

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;