THotPDF.SetLoadedFreeTextText Method
Replaces the normal appearance of a loaded FreeText annotation using embedded Unicode fonts, optional rich text and an atomic graph transaction
Declaration
procedure SetLoadedFreeTextText(PageIndex, AnnotationIndex: Integer;
const AText: UnicodeString; const Options: THPDFLoadedTextAppearanceOptions;
const RichContent: AnsiString = ''; const DefaultStyle: AnsiString = '');Options
Initialise the record with THPDFLoadedTextAppearanceOptions.Default before changing individual fields
| Field | Behaviour |
|---|---|
| FontName, FontStyle, FontSize | Primary font, style and point size; defaults are Arial, regular and 12 points |
| TextColor, Alignment, Padding | Plain-text colour, left/centre/right alignment and point padding; defaults are black, left and 2 points |
| Opacity, Rotation | Opacity in [0,1] and rotation in multiples of 90 degrees |
| OverflowPolicy | THPDFLoadedTextOverflowPolicy: ltopReject rejects overflow, ltopClip clips it and ltopShrinkToFit retries smaller fonts |
| MinFontSize | Lower bound for shrinking, default 4 points |
| MaxTextUnits | Input and plain-text budget, default 1,048,576 UTF-16 units; rich input is limited to four times this budget |
Behaviour
AText supplies plain Unicode text; non-empty UTF-8 RichContent instead uses the HTML importer and optional CSS DefaultStyle, then derives /Contents from the generated text
The generated appearance copies embedded fonts and ToUnicode mappings into the loaded document, so saving, flattening and text extraction retain its Unicode text
The method inherits configured font fallback chains, ShapingFeatures, the Arabic, Syriac, N'Ko, Adlam, and Hanifi Rohingya auto-shaping switches, and the GSUB script and language selections; every shrink-to-fit retry uses the same settings without changing the caller's configuration
It preserves supported background, solid/dashed border, rectangle insets and two/three-point callout geometry, and synchronises /AP, /Contents, /RC, /DS, /CA, /Q and rotation metadata
Invalid geometry, unresolved plain-text glyphs, cloudy borders, resource limits and rejected overflow raise an exception and roll back the entire update; existing outer graph transactions remain active
Rich text follows the supported HTML/CSS subset; external resources are disabled and fixed CSS font sizes may prevent shrink-to-fit from reducing individual runs
Each appearance writer accepts at most 256 distinct shaping font selections and 64 MiB of cumulative raw font data; exceeding either limit rejects the update and preserves the original annotation
Related APIs
- SetLoadedFreeTextRichText uses this appearance pipeline with clip overflow
- SetLoadedFreeTextPlainText retains its original ASCII contract
- SetLoadedAnnotationContents edits only stored content