THPDFHeadlessDocument.SaveRichTextFieldUpdatesToFile
function SaveRichTextFieldUpdatesToFile(const FileName: string;
const Updates: THPDFHeadlessRichTextFieldUpdates;
const Options: THPDFHeadlessFormDataOptions): Integer;Prepare and atomically publish one independent PDF containing scalar text, choice and button updates together with original typed rich-text runs; return the number of changed fields while keeping the loaded document graph unchanged
The current graph is serialized into a private authenticated revision before updates are applied; existing unsaved page and field edits, AES R5/R6 credentials, encryption identifiers and signed source prefixes remain available to the candidate
Typed runs generate appearances directly, without a rich XML encode/decode round trip; /V and /RV describe the authored text and styles, while /AP retains the existing appearance engine's PDF numeric precision for the original typed sizes and colors
A typed no-op requires equivalent plain and rich values plus equal generated appearance streams and resolved font/resource graphs for every widget; comparison decrypts existing streams and normalizes indirect object references, rather than trusting quantized /RV colors alone
This permits genuinely unchanged read-only or signature-locked fields; a different actual paint color, size, supplied font or widget appearance follows normal read-only, FieldMDP and DocMDP restrictions even when the serialized rich value happens to be identical
Comparison is conservative about existing appearances: externally authored PDFs with equivalent visual results but a different operator or resource representation may require an ordinary protected update
When every requested field is unchanged and the loaded graph has no pending edits, the published PDF is byte-for-byte identical to the loaded source, including existing AES encryption bytes and authenticated signature revisions; an empty update array follows the same rule, subject to the existing source compatibility checks
Pending edits in the caller graph are serialized into the candidate once even when this method returns zero field changes; unrelated unsaved page or field changes are preserved, and the original loaded graph remains unchanged
Zero-update publication still performs permission and signature validation, source/destination alias checks, output budget checks, cancellation and atomic destination replacement; read-only and locked fields require genuine value and appearance equivalence
This byte-preserving behavior applies to this transactional method; the general SaveToFile method and separate FDF/XFDF import APIs retain their existing save behavior
Field count, duplicate names, Unicode, value sizes and aggregate text capacities use Options; typed run count, aggregate glyph units, supplied font bytes, rich value bytes, generated objects and appearance comparison bytes also use the loaded document limits
A shared managed font byte array is counted once across updates; distinct allocations consume separate input font capacity even when their bytes match, while generated PDF object and output budgets still cover all appearances
Use the document's cancellation token for form and appearance options; invalid fields, malformed values, permissions, failed signature authentication, cancellation or budget failures leave the previous destination intact, and source/destination aliases are rejected
The API covers native mixed transactions; Windows JSON typed-rich filling, the older job callback extension, annotation interchange and embedded or incremental FDF data are separate workflows