Ordered Rich Text Font Candidate Lists

Rich text can retain an explicit ordered family list and use that order when selecting genuine supplied font programs for a complete Unicode grapheme

Run:= THPDFHeadlessRichTextRun.Default;
Run.Text:= 'A' + WideChar($03A9) + 'B';
Run.FontFamily:= 'Primary';
SetLength(Run.FontFamilyCandidates, 3);
Run.FontFamilyCandidates[0]:= 'Primary';
Run.FontFamilyCandidates[1]:= 'Serif';
Run.FontFamilyCandidates[2]:= 'Sans';
Options:= THPDFHeadlessTextAppearanceOptions.Default;
Options.FallbackFontFamilies:= True;

Supply the actual family and style programs through the existing named-family APIs; labels in FontFamilyCandidates do not discover or download fonts

Selection and preservation

The first affected authored run supplies the list for a whole grapheme, including style seams and combining marks; each configured candidate must cover every styled part with its actual regular, bold, italic or bold-italic program

Unknown labels and candidates with missing style programs are skipped; if no declared candidate covers the grapheme, the existing selected-family and supplied-array fallback rules apply

FontFamily must match the first configured label in a nonempty candidate list when one exists; omitting a typed JSON FontFamily selects that match automatically

Fallback changes appearance preparation only: the authored plain value, precise typed size and color, and original candidate ordering remain in V and RV; the resolver never rewrites the caller's runs

Inline XHTML and interchange

Set THPDFHeadlessRichTextDecodeOptions.PreserveFontFamilyLists to True with configured FontFamilyNames to retain supported comma-separated inline font-family declarations, including inheritance and per-property important priority

Family-aware FDF and XFDF imports enable this preservation when their appearance options enable FallbackFontFamilies; strict default decoding keeps the existing first-configured-family selection

Lists contain at most sixteen labels, each bounded to 128 UTF-16 code units with valid Unicode, no controls, surrounding whitespace, quotes, backslashes, commas or semicolons; duplicate and unknown declared labels retain their authored order

Native Linux JSON

{"schemaVersion":1,"type":"forms.fill",
 "fontFamilies":["Primary","Sans","Serif"],"fallbackFontFamilies":true,
 "fields":[{"name":"Input","richTextRuns":[
   {"text":"A\u03a9B","fontFamily":"Primary",
    "fontFamilyCandidates":["Primary","Serif","Sans"]}
 ]}]}

The declared Serif-before-Sans order controls fallback even when the operation configures Sans before Serif; the existing Fontconfig provider supplies actual named programs under the same aggregate font and memory limits

Typed run candidate arrays require configured fontFamilies and enabled fallbackFontFamilies; malformed arrays or labels, missing whole-grapheme coverage, exhausted budgets and cancellation fail transactionally before context commit

The formData.richFontFamilyCandidates capability and maxFontFamilyCandidates=16 advertise this bounded option through the unchanged V1 callbacks and exported symbol versions

Successful chained form fills and equivalent FDF/XFDF imports retain their committed document and source snapshot; output or result callback failures preserve the preceding committed revision

Scope

This profile covers supplied candidate labels and supported inline declarations; Windows jobs and versioned callbacks also preserve ordered supplied-family fallback; external style sheets, arbitrary CSS layout, generic-family discovery and the older loaded-job handle/font callback extension remain separate work

Fallback behavior · Typed run record · Decode options · Native Linux binding