losLab logo

HotPDF Developer Reference

Delphi and C++Builder PDF component help

Home Contents Overview

AcroForm Support

Overview

Since HotPDF v2.5.0 the library can emit interactive forms (AcroForm) per PDF 1.7 ISO 32000-1 section 12.7. Each form field is created as a Widget annotation merged with the field dictionary and is automatically registered with the document so the global /AcroForm entry is added to the Catalog when the document is finalized in EndDoc.

Supported field types

  • Text fields (/FT /Tx) via THPDFPage.AddTextField. Supports single-line, multi-line, password, comb, file-select, rich-text, scroll and spell-check options through THPDFFormFieldFlags.
  • Check boxes (/FT /Btn, no Pushbutton/Radio bits) via THPDFPage.AddCheckBox with a configurable export value name and initial checked state.
  • Radio buttons (/FT /Btn /Ff Radio) via THPDFPage.AddRadioButton. Multiple calls with the same group name are merged under a shared parent field with a /Kids array, exactly as required by 12.7.4.2.
  • Combo boxes (/FT /Ch /Ff Combo) via THPDFPage.AddComboBox. Pass an open array of options.
  • List boxes (/FT /Ch) via THPDFPage.AddListBox. ffMultiSelect enables multi-select.
  • Push buttons (/FT /Btn /Ff Pushbutton) via THPDFPage.AddPushButton with optional caption (/MK /CA). Since HotPDF v2.31.0, THPDFPage.AddPushButtonWithAction attaches a PDF action dictionary to the widget so clicking the button runs /SubmitForm (post field values to a URL, PDF 1.2 12.7.5.2), /ResetForm (PDF 1.2 12.7.5.3), /JavaScript (run a JS snippet, PDF 1.3 12.6.4.16) or /URI (open a URL in the system browser, PDF 1.1 12.6.4.7).
  • Signature placeholder fields (/FT /Sig) via THPDFPage.AddSignatureField since HotPDF v2.12.0. The AcroForm dictionary automatically gains /SigFlags 3 (SignaturesExist + AppendOnly) when at least one signature field is present. The field is left unsigned so external tools (Adobe Acrobat, Foxit, dedicated CMS / PKCS#7 signing libraries) can attach the actual cryptographic signature after the file is saved.
  • In-place signing workflow via THPDFPage.AddSignedSignatureField + THotPDF.PreparePDFForSigning + THotPDF.InsertSignatureHex since HotPDF v2.23.0. The first call reserves a /V signature dictionary with /ByteRange and /Contents placeholders. After saving the document the host application calls PreparePDFForSigning to patch /ByteRange and learn which file ranges to hash. After producing a CMS / PKCS#7 detached signature externally (Windows CryptoAPI, OpenSSL, dedicated signing libraries), it calls InsertSignatureHex to drop the signature hex into the placeholder without disturbing any other byte in the file.

Appearance generation

By default the emitted /AcroForm dictionary sets /NeedAppearances true and delegates appearance-stream rendering to the consuming viewer (Adobe Reader, Foxit, Chrome, browsers, Apple Preview). Set THotPDF.AutoFormAppearances to true before adding fields and HotPDF will pre-build /AP /N Form XObjects (PDF 1.7 8.10) for every text field, push button, choice (combo / list) and the Yes / Off states of every checkbox / radio kid. The AcroForm dictionary then carries /NeedAppearances false and a /DR default resources entry referencing the standard 14 base fonts (Helv Helvetica, ZaDb ZapfDingbats), so renderers that ignore /NeedAppearances still draw the field content correctly. Available since HotPDF v2.28.0.

Field flag reference (THPDFFormFieldFlags)

  • ffReadOnly, ffRequired, ffNoExport — common Table 227 flags applicable to every field type.
  • ffMultiline, ffPassword, ffFileSelect, ffDoNotSpellCheck, ffDoNotScroll, ffComb, ffRichText — Tx-specific (Table 228).
  • ffEdit, ffSort, ffMultiSelect, ffDoNotSpellCheck, ffCommitOnSelChange — Ch-specific (Table 230).

Pascal example

HPDF.BeginDoc;
HPDF.AddPage;
HPDF.CurrentPage.AddTextField('Name', '', Rect(50, 100, 250, 120));
HPDF.CurrentPage.AddCheckBox('Agree', 'Yes', Rect(50, 130, 70, 145), True);
HPDF.CurrentPage.AddRadioButton('Color', 'Red',   Rect(50, 160, 70, 175), True);
HPDF.CurrentPage.AddRadioButton('Color', 'Green', Rect(80, 160, 100, 175));
HPDF.CurrentPage.AddRadioButton('Color', 'Blue',  Rect(110, 160, 130, 175));
HPDF.CurrentPage.AddComboBox('Country', 'CN',
                             ['CN', 'US', 'JP'], Rect(50, 190, 250, 210));
HPDF.EndDoc;

Limitations

  • The AutoFormAppearances generator currently lays out ASCII / WinAnsi-encodable values only; for fields whose /V contains multi-byte (UTF-8) text the stored /AP renders an empty rectangle until the host viewer regenerates the appearance.
  • Down (/D) and rollover (/R) sub-states are not generated; only the normal (/N) state is produced.
  • Field name uniqueness is the caller's responsibility; HotPDF does not enforce it.

See Also