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
Initialize the record with THPDFLoadedTextAppearanceOptions.Default before changing individual fields
| Field | Behavior |
|---|---|
| FontName, FontStyle, FontSize | Primary font, style, and point size; defaults are Arial, regular, and 12 points |
| TextColor, Alignment, Padding | Plain-text color, left/center/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 |
Behavior
AText supplies plain Unicode text; nonempty 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 synchronizes /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