Ordered Rich Text Font Candidate Lists

Rich text can keep an explicit ordered family list and apply 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 via the existing named-family APIs; labels in FontFamilyCandidates neither discover nor download fonts

Selection and preservation

The first affected authored run provides 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 passed over; where 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 non-empty candidate list where one exists; omitting a typed JSON FontFamily selects that match automatically

Fallback changes appearance preparation only: the authored plain value, precise typed size and colour, 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 keep supported comma-separated inline font-family declarations, including inheritance and per-property important priority

Family-aware FDF and XFDF imports enable this preservation when FallbackFontFamilies is enabled in their appearance options; 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 keep 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 governs 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 the context is committed

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

Successful chained form fills and equivalent FDF/XFDF imports keep 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; external style sheets, arbitrary CSS layout, generic-family discovery and Windows callback fallback loading are separate work

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