Automatic XFA rich captions

Units: HPDFXFA, HPDFXFAHeadless and HPDFHeadlessAppearance

HPDFXFAWriteHeadlessPDF consumes effective checkbox and radio caption values directly from saved XDP and creates actual native appearance Forms with embedded fonts

Effective caption content

Scalar caption values and exData XHTML body content become native text; the body must use the http://www.w3.org/1999/xhtml namespace

A partial repeated-instance form overlay changes the corresponding template element's text and attributes while retaining unchanged template siblings and their XHTML namespace

A successful exData.loadXML whole-payload replacement supplies its actual imported body instead of merging obsolete template content back into the caption

Comments and processing instructions remain in the original saved XDP but are omitted from the rendering copy, so their payloads never become visible caption text

The rendering copy is bounded to 4096 nodes, depth 64, 65536 overlay work steps and 1 MiB of charged source and serialized XHTML; the native decoder and appearance builders retain their own run, glyph and byte limits

Real font faces and styles

Supply CaptionFontFamilies for actual regular, bold, italic and bold-italic programs and named families

The existing native XHTML decoder resolves inline styles, paragraph boundaries, family lists, colors, sizes, underline and strike formatting; scalar caption font size, weight, posture, typeface and fill color provide the default style

A missing requested face or glyph fails preparation; this consumer does not fabricate bold or italic appearances or discover external fonts

Measurement and placement

Caption measurement and painting use the same native rich layout and supplied font programs, including actual glyph advances, style-specific ascent and descent, common line baselines and wrapping

A fixed left or right reserve constrains the text width; a positive top or bottom reserve permits wrapping within the available field width

An omitted reserve, zero or the schema default -1 uses natural caption extent without automatic text wrapping; explicit paragraph boundaries remain line breaks, and text exceeding a fixed field rectangle is clipped

Automatic left and right captions use their natural width; inline captions ignore explicit reserve during both measurement and placement

Caption margins reduce the actual text region, and caption horizontal and vertical alignment control the resulting appearance placement

The reserve behavior follows the XFA 3.3 caption reserve definition

Natural height includes the final font-metric line extent plus the native two-point padding on each side; it excludes unused trailing leading after the final line

Hidden and inactive captions consume no region; invisible captions reserve their measured region without painting or charging caption glyphs

One actual caption Form is shared across off, on and neutral states of the same widget; repeated instances retain independent content and style graphs

Paragraph margin and custom line-height CSS, caption images and other nontext caption payloads, push-button rich captions and later interactive appearance rebuilding retain separate consumer work

Transactions and acceptance

A successful native property event can be saved and reloaded before automatic PDF creation; script failure restores exact native XML bytes, and preparation budget or cancellation failures preserve destination bytes, length and position

Writes to the destination begin only after the complete candidate succeeds; an error from the caller's own stream write follows that stream's semantics and cannot be rolled back for an arbitrary nonseekable destination

Tests/Linux/XFAHeadlessRichCaptionTests.pas produces actual styled, wrapped, family-selected and nonvisible caption PDFs; XFAHeadlessRichCaptionRuntimeTests.pas covers repeated overlays, whole XML replacement and rollback

XFAHeadlessRichCaptionBudgetTests.pas exercises real resource failures and selected cancellation boundaries, while HeadlessTextExtentTests.pas exposes the measured native line extents

Verify-XFAHeadlessRichCaptions.py inspects saved PDF graphs, exact supplied font-program bytes, shared references, Unicode text, raw text matrices, fontTools metrics and MuPDF rendered pixels without opening a reader UI

Read-only TextHeight · Boolean callback metadata · Boolean markers and states