THPDFHeadlessDocument.SetTextFieldValueWithAppearance

procedure SetTextFieldValueWithAppearance(FieldIndex: Integer;
  const Text: UnicodeString; const TrueTypeFont: SysUtils.TBytes;
  const Options: THPDFHeadlessTextAppearanceOptions);

Updates a writable terminal AcroForm text field and builds an explicit normal appearance for each existing widget, using the same document object graph on native Linux and Windows

Widget rectangles supply the appearance dimensions; inherited field Q supplies left, center, or right alignment when present, otherwise the options alignment applies

The profile supports single-line and multiline plain text, measured word wrapping with character fallback, CR/LF line breaks, fixed size or auto-fit, comb cells with a positive inherited MaxLen, and widget rotations in multiples of 90 degrees

Complex scripts, bidi runs, ligatures, and combining sequences use HarfBuzz and FriBidi when ShapeComplexText is enabled; direct Unicode text remains independent of those runtimes, and missing glyphs or malformed surrogate pairs produce an appearance diagnostic

Complex multiline wrapping operates on logical Unicode clusters before bidi reordering and reshaping; comb cells retain the direct one-glyph-per-scalar profile

For an existing rich-text field, this method replaces the content with one plain style and synchronizes V, RV and every widget appearance; use SetRichTextFieldValueWithAppearance to supply mixed styles

Password fields generate one bullet per Unicode scalar and retain the actual Unicode field value in V; appearance glyph mappings and accessibility text contain the mask, while the value follows the document encryption policy

Password fields cannot be multiline or comb fields; malformed Unicode, control characters, missing mask glyphs, cancellation and resource exhaustion preserve the original field

File-select fields display the literal Unicode path as ordinary field text; this operation does not open, execute or attach the selected file

Fonts require valid named TrueType outlines and actual metrics, with installable or editable embedding flags; full-font embedding honors no-subsetting permissions and rejects restricted, preview-and-print, bitmap-only, missing, and unknown permissions

The method prepares all field replacements, appearance dictionaries, new font and Form objects, and serialization budgets before changing a field; preflight failures preserve its previous value and appearance links

New objects are owned by the document and saved through the original bounded incremental writer, including encryption of new strings and streams under the original AES-256 R5 or R6 policy

NeedAppearances is cleared after explicit appearances cover the changed field, unless another value-only edit or an original unresolved appearance requirement remains

When the original flag is true, other non-signature fields conservatively keep it true until their appearance requirements are satisfied; use the separate choice and button methods to regenerate those fields

Read-only, MaxLen, existing signatures, certification permissions, AES form-fill permissions, source protection, cancellation, and atomic output policies remain in effect

If both the document and appearance options specify cancellation tokens, they must be the same token

See THPDFHeadlessTextAppearanceOptions and HPDFBuildHeadlessTextAppearance for the bounded font and layout contract