THPDFHeadlessDocument.SetTextFieldValueWithAppearance

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

Updates a writable terminal AcroForm text field and constructs 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 provides left, centre 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 yield an appearance diagnostic

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

For an existing rich-text field, this method replaces the content with one plain style and synchronises 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, whilst 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 leave the original field in place

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 honours 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 serialisation budgets before changing a field; preflight failures leave its previous value and appearance links intact

New objects are owned by the document and written 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 met; 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

Refer to THPDFHeadlessTextAppearanceOptions and HPDFBuildHeadlessTextAppearance for the bounded font and layout contract