THotPDF.SetFormUnicodeFontDict 메서드

Caller-supplied Unicode font를 AcroForm default-resources dict에 등록하여 HotPDF의 auto-appearance-stream generator(PDF 1.7 ISO 32000-1 12.7.4.3)가 v2.46.0 empty-AP placeholder를 emit하는 대신 non-ASCII Tx widget initial value를 /AP로 직접 렌더링할 수 있게 합니다. Populate할 indirect font dict를 allocate하려면 CreateIndirectFontDict와 함께 사용하십시오

procedure SetFormUnicodeFontDict(const LogicalName: AnsiString; FontDict: THPDFDictionaryObject);

void SetFormUnicodeFontDict(const AnsiString& LogicalName, THPDFDictionaryObject* FontDict);

Once both LogicalName and FontDict are populated, three things change in subsequent emission: (a) the AcroForm-level /DA string switches from '/Helv 12 Tf 0 0 0 rg' to '/<LogicalName> 12 Tf 0 0 0 rg'; (b) the AcroForm /DR /Font sub-dict gains an entry /<LogicalName> <FontDict-indirect-ref> alongside the existing /Helv + /ZaDb; (c) every Tx widget added through AddTextField or AddRichTextField gets its per-field /DA set the same way. When AutoFormAppearances is on and the widget's initial value contains any byte >= 0x80, GenerateTextFieldAP emits a real /AP /N Form XObject whose content stream selects the registered font via Tf and renders the text as a CID hex-string Tj operator; the Form's /Resources/Font sub-dict references the same indirect font so the AP is self-contained.

Registered font가 RegisterUnicodeTTF에서 온 경우 supplementary-plane Unicode character(예: U+1F600)는 UTF-16 surrogate pair를 두 개의 Identity-H CID로 분할하는 대신 내부적으로 allocate된 단일 CID를 통해 emit됩니다. HotPDF는 finalization time에 생성된 /CIDToGIDMap, /W, /ToUnicode stream을 refresh하여 internal CID가 실제 font glyph로 mapping되고 text extraction이 original UTF-16BE surrogate pair로 되돌아가도록 합니다

ASCII Tx field는 계속 /Helv를 사용하며 v2.46.0 caller와 byte-identical한 /AP output을 emit합니다. Registration을 clear하고 /Helv-only behavior로 되돌리려면 empty LogicalName + nil FontDict를 전달하십시오. Typical workflow는 BeginDoc 직후, 어떤 AddTextField보다 먼저 SetFormUnicodeFontDict를 한 번 호출하는 것입니다. 이전에 생성된 widget은 retroactively update되지 않습니다

LogicalName - /DR/Font의 key 및 /DA string 안의 Tf operand로 사용되는 PDF Name입니다. Typical value는 'F0'입니다. Register할 때 비어 있으면 안 됩니다. Non-nil FontDict와 empty name을 함께 전달하면 raise합니다

FontDict - an indirect THPDFDictionaryObject holding a valid PDF Font resource. The caller is responsible for building the font dict correctly - typically a Type 0 / CIDFontType2 + Identity-H + ToUnicode CMap composite font; for stroked-only or simple display use a Type 1 / TrueType subset works too. HotPDF does not validate the contents; it just serializes the reference.

Scope - v2.56.0 covers single-line Tx widgets only. Multi-line (ffMultiline) and comb (ffComb) Tx widgets with non-ASCII initial values still emit the v2.46.0 empty-AP placeholder; the Unicode-AP extension for those branches is scheduled for v2.57.0+. RTL bidi shaping (Arabic / Hebrew) requires Unicode Bidi Algorithm (UAX #9) + Arabic contextual joining; also v2.57.0+ scope.

Code Example

// Register a Type 0 / CIDFontType2 + Identity-H composite font for
// AcroForm Tx widget AP rendering. (Real production code adds a
// /FontFile2 stream and a ToUnicode CMap so the glyphs actually
// render - omitted here for brevity.)
var
  F0, Descendant, FontDescriptor, CIDSysInfo: THPDFDictionaryObject;
  Descendants: THPDFArrayObject;
  R: TRect;
begin
  HPDF.BeginDoc;
  HPDF.AutoFormAppearances := True;

  F0 := HPDF.CreateIndirectFontDict;          // empty indirect dict
  F0.AddNameValue('Type', 'Font');
  F0.AddNameValue('Subtype', 'Type0');
  F0.AddNameValue('BaseFont', 'MyCJK');
  F0.AddNameValue('Encoding', 'Identity-H');

  CIDSysInfo := THPDFDictionaryObject.Create(nil);
  CIDSysInfo.AddStringValue('Registry', 'Adobe');
  CIDSysInfo.AddStringValue('Ordering', 'Identity');
  CIDSysInfo.AddNumericValue('Supplement', 0);

  FontDescriptor := THPDFDictionaryObject.Create(nil);
  FontDescriptor.AddNameValue('Type', 'FontDescriptor');
  // ... fill required Ascent / Descent / FontBBox / etc

  Descendant := THPDFDictionaryObject.Create(nil);
  Descendant.AddNameValue('Type', 'Font');
  Descendant.AddNameValue('Subtype', 'CIDFontType2');
  Descendant.AddNameValue('BaseFont', 'MyCJK');
  Descendant.AddValue('CIDSystemInfo', CIDSysInfo);
  Descendant.AddValue('FontDescriptor', FontDescriptor);
  Descendant.AddNumericValue('DW', 1000);

  Descendants := THPDFArrayObject.Create(nil);
  Descendants.AddObject(Descendant);
  F0.AddValue('DescendantFonts', Descendants);

  HPDF.SetFormUnicodeFontDict('F0', F0);

  R.Left := 60; R.Top := 60; R.Right := 280; R.Bottom := 100;
  HPDF.CurrentPage.AddTextField('Greeting', '你好世界', R);

  HPDF.EndDoc;
end;