Automatic XFA Boolean styles and captions

Units: HPDFXFA and HPDFXFAHeadless

HPDFXFAWriteHeadlessPDF consumes effective checkButton properties and creates native checkbox and radio appearance streams from the actual XFA layout

Markers and outlines

The checkButton size defaults to 10pt and controls the square marker region within the field's content region; explicit size measurements, field and UI margins, and paragraph horizontal and vertical alignment determine its position

The square and round shapes determine the outline; the default asserted mark is a cross for a square outline and a filled circle for a round outline, following the XFA 3.3 checkButton specification

Explicit check, circle, cross, diamond, square and star marks use real vector paths; they do not depend on the supplied font containing a checkbox symbol

The first UI border edge supplies its thickness, color and visibility; the default outline is black and 0.5pt wide, while the effective field font color supplies the asserted mark color

The marker shrinks to the remaining content region when its configured size exceeds that region; a caption or margin that leaves no content region causes candidate preparation to fail

Scalar Unicode captions

Scalar caption text retains Unicode and delimiters exactly and becomes a real embedded-font Form XObject referenced from every off, on and neutral appearance for that widget

The caption shares one appearance and font graph across its states, and its UTF-16 units are counted once per widget in TXFAHeadlessPDFResult.GlyphUnits

Left and right reserve a caption width, while top and bottom reserve a height; an omitted or zero reserve uses the supplied font's actual glyph advances and line metrics to calculate the natural caption extent

Inline captions precede the marker and ignore an explicit reserve; caption margins inset the text within its allocated region

A caption font size and fill color override the field's size and color; caption paragraph alignment overrides field alignment, while CaptionFontFamilies can supply actual style faces and named families

Hidden and inactive captions occupy no region and allocate no font graph; invisible captions retain their region without painting or allocating caption glyphs

The rich caption consumer additionally consumes effective XHTML, real configured style faces and family selection, mixed line metrics and wrapped caption heights

Third checkbox states

When allowNeutral is enabled, the third saved item is the neutral checkbox export; matching values retain a distinct native /V and widget /AS with their own /AP /N entry

The neutral appearance draws the empty outline and the same caption; it does not draw the asserted mark

The checkbox /Opt array keeps one on-export entry for its single widget, as required by the PDF button-field model; a third saved appearance state does not add a second widget option

Empty exports, the reserved Off name and names beginning with XFAOn receive collision-free native state aliases using their UTF-8 bytes as uppercase hexadecimal after XFAOn; the third original export can be recovered from its saved state name

A radio member ignores a third item and retains its existing two-state appearance dictionary and template/data scope group identity

The adapter persists the initial state graph; an application's later native button-edit operation has its own state and appearance contract

Native instance properties and transactions

The checkButton size, shape, mark and allowNeutral defaults are available through the native runtime schema; absent checkButton border and margin properties can be created through the existing property transaction

Effective repeated-instance checkButton, caption, font and margin properties survive SaveToBytes and immediately control the corresponding automatically created PDF widget; the first repeated instance retains its independent properties

Literal UTF-8 event source and Unicode binding values retain their scalars before saved XDP is converted, including caption text changed by a native JavaScript event; see HPDFXFAExecuteJavaScriptEvent

Script failure restores exact native XML before creation, and preparation failures preserve destination position, length and bytes; glyph, object and font budgets and cancellation retain the automatic creator's transaction boundary

Acceptance sources

Tests/Linux/XFAHeadlessBooleanStylesTests.pas produces real mark pairs, captions, neutral and reserved states, repeated-instance script changes and rollback cases without a reader UI

Tests/Linux/Verify-XFAHeadlessBooleanStyles.py checks actual saved state dictionaries, shared font resources, caption placement, Unicode text and distinct marker pixels with pypdf and MuPDF

Boolean callback metadata describes the additive transport hints consumed by the native creator