AcroForm Support

Overview

HotPDF v2.5.0부터 라이브러리에서 PDF 1.7 ISO 32000-1 12.7절에 따른 대화형 양식(AcroForm)을 출력할 수 있습니다. 각 양식 필드는 필드 사전과 병합된 Widget 주석으로 생성되며 문서에 자동 등록되어 Catalog에 전역 /AcroForm 항목이 추가되며, 이 작업은 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.
체크박스(/FT /Btn, Pushbutton/Radio 비트 없음): THPDFPage.AddCheckBox로 만들며, export 값 이름과 초기 체크 상태를 지정할 수 있습니다
라디오 버튼(/FT /Btn /Ff Radio): THPDFPage.AddRadioButton로 만듭니다. 같은 그룹 이름으로 여러 번 호출하면 12.7.4.2의 요구대로 /Kids 배열을 가진 공유 부모 필드 아래에 병합됩니다
콤보 상자(/FT /Ch /Ff Combo): THPDFPage.AddComboBox로 만듭니다. 옵션은 open array로 전달합니다
List boxes (/FT /Ch) via THPDFPage.AddListBox. ffMultiSelect enables multi-select.
푸시 버튼(/FT /Btn /Ff Pushbutton): THPDFPage.AddPushButton으로 만들며, 캡션(/MK /CA)은 선택 사항입니다. HotPDF v2.31.0부터 THPDFPage.AddPushButtonWithAction으로 위젯에 PDF 액션 사전을 연결할 수 있어, 버튼을 클릭하면 /SubmitForm(필드 값을 URL로 전송, PDF 1.2 12.7.5.2), /ResetForm(PDF 1.2 12.7.5.3), /JavaScript(JS 스니펫 실행, PDF 1.3 12.6.4.16), /URI(시스템 브라우저에서 URL 열기, PDF 1.1 12.6.4.7) 중 하나가 실행됩니다
서명 자리 표시자 필드(/FT /Sig): HotPDF v2.12.0부터 THPDFPage.AddSignatureField로 만들 수 있습니다. 서명 필드가 하나 이상 있으면 AcroForm 사전에 /SigFlags 3(SignaturesExist + AppendOnly)이 자동으로 추가됩니다. 필드는 서명되지 않은 상태로 남으므로, 파일을 저장한 뒤 외부 도구(Adobe Acrobat, Foxit, 전용 CMS / PKCS#7 서명 라이브러리)가 실제 암호화 서명을 붙일 수 있습니다
In-place 서명 워크플로우: HotPDF v2.23.0부터 THPDFPage.AddSignedSignatureField + THotPDF.PreparePDFForSigning + THotPDF.InsertSignatureHex를 사용합니다. 첫 번째 호출은 /ByteRange와 /Contents 자리 표시자를 가진 /V 서명 사전을 예약합니다. 문서를 저장한 뒤 호스트 애플리케이션이 PreparePDFForSigning을 호출해 /ByteRange를 패치하고 해시할 파일 범위를 확인합니다. 외부(Windows CryptoAPI, OpenSSL, 전용 서명 라이브러리)에서 CMS / PKCS#7 detached 서명을 만든 다음 InsertSignatureHex를 호출하면, 파일의 다른 바이트를 건드리지 않고 서명 hex를 자리 표시자에 채워 넣습니다

Creation-time field wrappers

HotPDF v2.292.12부터 THPDFPage.CreateTextField, CreateCheckBox, CreateRadioButton, CreateComboBox, CreateListBox 헬퍼는 기존 Add... 메서드와 동일한 AcroForm 위젯을 만들고, 바로 설정할 수 있는 경량 THPDFAcroFormField 래퍼를 반환합니다

HotPDF v2.292.26부터 THotPDF.SetFormFieldTooltip으로 PDF /TU 사용자 힌트를 필드 이름 기준으로 지정할 수 있으며, 대상은 기존 Add... 메서드로 만든 필드입니다. 래퍼 수준의 THPDFAcroFormField.SetTooltip 워크플로우와 동일하게 동작합니다

HotPDF v2.298.0부터 생성 시점 필드 API와 로드된 문서의 필드 생성 API는 위젯을 등록하기 전에 루트 필드 이름이 중복되면 진단 예외를 발생시킵니다. 같은 그룹 이름으로 AddRadioButton을 반복 호출하는 것은 여전히 유효한데, 하나의 부모 필드를 공유하고 그 /Kids 배열 아래에 자식 위젯이 추가되기 때문입니다

래퍼는 체이닝 가능한 setter를 제공합니다. /TU 툴팁, 공통 필드 플래그(SetReadOnly, SetRequired, SetNoExport), /DA 기본 모양 문자열, /AA /K, /AA /F, /AA /V, /AA /C 같은 필드 수준 추가 액션, 그리고 THPDFActionBuilder를 통한 위젯 마우스 / 포커스 액션을 설정할 수 있습니다

Creation-time wrapper Pascal example

Field := HPDF.CurrentPage.CreateTextField('Email', '', Rect(50, 80, 250, 104));
Action := THPDFActionBuilder.JavaScript('event.rc = event.value.indexOf("@") > 0;');
try
  Field.SetTooltip('Email address');
  Field.SetRequired(True);
  Field.SetReadOnly(False);
  Field.SetAdditionalAction(fatValidate, Action);
finally
  Action.Free;
  Field.Free;
end;

Loaded form-field inspection and updates

HotPDF v2.121.9부터 애플리케이션에서 기존 AcroForm PDF를 THotPDF.LoadFromFile로 로드하고, 필드를 열거하고, 이름 / 타입 / 값을 읽고, 필드 값을 변경하고, 읽기 전용 플래그를 전환한 뒤, 로드된 객체 그래프를 THotPDF.SaveLoadedDocument로 저장할 수 있습니다. 이 경로는 이미 로드된 문서의 편집 내용을 저장하기 위한 것입니다. 로드한 필드 값 변경을 저장하려고 BeginDoc / EndDoc을 호출하지 마십시오

필드 헬퍼는 GetFormFieldCount, GetFormFieldName, GetFormFieldType, GetFormFieldValue, SetFormFieldValue, SetFormFieldReadOnly입니다. 필드 조회에는 0부터 시작하는 필드 인덱스 또는 정규화된 전체 필드 이름을 사용할 수 있습니다. 반환되는 THPDFLoadedFormFieldType 값은 lfftText, lfftButton, lfftChoice, lfftSignature, lfftUnknown 중 하나입니다

Loaded-field Pascal example

HPDF.LoadFromFile('InputForm.pdf');
for I := 0 to HPDF.GetFormFieldCount - 1 do
  Writeln(HPDF.GetFormFieldName(I), ' = ', HPDF.GetFormFieldValue(I));

HPDF.SetFormFieldValue('CustomerName', 'Bob');
HPDF.SetFormFieldValue('Plan', 'Premium');
HPDF.SetFormFieldReadOnly('CustomerName', True);
HPDF.SaveLoadedDocument('UpdatedForm.pdf');

Field additional actions

래퍼 AttachFieldKeyStrokeAction, AttachFieldFormatAction, AttachFieldValidateAction, AttachFieldCalculateAction은 필드의 /AA 사전에 PDF /K, /F, /V, /C 트리거용 JavaScript를 연결합니다. 같은 트리거에서 재사용 가능한 액션 체인을 실행해야 한다면 SetFormFieldAdditionalAction 또는 이름이 붙은 THPDFActionBuilder 래퍼를 사용하십시오. 체인에는 JavaScript, ResetForm, SubmitForm, URI, Hide, ImportData, 또는 연결된 /Next 액션이 들어갈 수 있습니다. 위젯 수준의 마우스 및 포커스 트리거도 SetFormFieldAnnotationAction과 이름이 붙은 마우스 / 포커스 헬퍼로 필드 이름 기준으로 설정할 수 있으며, 대응하는 clear 헬퍼는 /AA 사전의 나머지 항목은 그대로 두고 트리거 하나만 제거합니다

Appearance generation

기본적으로 출력되는 /AcroForm 사전은 /NeedAppearances true를 설정하고, 모양 스트림 렌더링을 이를 소비하는 뷰어(Adobe Reader, Foxit, Chrome, 브라우저, Apple Preview)에 맡깁니다. 필드를 추가하기 전에 THotPDF.AutoFormAppearances를 true로 설정하면 HotPDF가 /AP /N Form XObject(PDF 1.7 8.10)를 모든 텍스트 필드, 푸시 버튼, 선택 필드(콤보 / 리스트), 그리고 모든 체크박스 / 라디오 자식의 Yes / Off 상태에 대해 미리 생성합니다. 그러면 AcroForm 사전에 /NeedAppearances false와 /DR 기본 리소스 항목이 함께 기록되며, 이 항목은 표준 14개 기본 글꼴(Helv Helvetica, ZaDb ZapfDingbats)을 참조하므로, /NeedAppearances를 무시하는 렌더러도 필드 내용을 올바르게 그립니다. 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.SetFormFieldTooltip('Name', 'Customer name');
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

AutoFormAppearances 생성기는 현재 ASCII / WinAnsi로 인코딩할 수 있는 값만 배치합니다. /V에 멀티바이트(UTF-8) 텍스트가 들어 있는 필드는 호스트 뷰어가 모양을 다시 생성하기 전까지 저장된 /AP가 빈 사각형으로 렌더링됩니다
Down(/D)과 rollover(/R) 하위 상태는 생성되지 않으며, 일반(/N) 상태만 생성됩니다
새 AcroForm 위젯을 만들 때 루트 항목의 필드 이름 중복 여부를 검사합니다. 라디오 부모 / 위젯 패턴을 넘어서는 계층적 partial name 구성은 여전히 '호출자의 책임'입니다

See Also