Anotasi PDF di Delphi dengan HotPDF: Jenis dan Rect

Anotasi bukan konten halaman. Ketika Anda memanggil TextOut atau menggambar persegi panjang, tanda-tanda tersebut menjadi bagian dari aliran konten halaman, terpatri dalam byte yang dilukis renderer. Anotasi adalah kamus terpisah yang digantung pada halaman melalui larik /Annots-nya, dengan persegi panjangnya sendiri, tampilannya sendiri, dan siklus hidupnya sendiri. Pembaca dapat membukanya, memindahkannya, menyembunyikannya, atau menghapusnya tanpa menyentuh satu glyph pun dari halaman yang mendasarinya. Pemisahan itulah seluruh alasan keberadaan anotasi, dan itu juga sumber dari dua hal yang paling mengejutkan orang pertama kali: di mana anotasi mendarat, dan seperti apa tampilannya setelah penampil tertentu mengambil alihnya

HotPDF mengekspos subtipe anotasi ISO 32000 melalui sekelompok pemanggilan AddXxxAnnotation pada objek halaman. Semuanya memiliki bentuk yang sama: sebuah persegi panjang yang menetapkan anotasi di halaman dalam ruang pengguna PDF, beberapa payload (teks, nama stempel, sepasang titik), dan sebuah warna. Dapatkan persegi panjang yang benar dan sebagian besar pekerjaan sudah selesai. Sisanya adalah mengetahui subtipe mana yang membawa tampilannya sendiri dan mana yang bergantung pada penampil untuk menggambarnya

Persegi panjang adalah anotasinya, bukan teksnya

Setiap pemanggilan anotasi mengambil TRect, dan persegi panjang tersebut memiliki arti yang berbeda dari koordinat yang Anda berikan ke TextOut. Untuk catatan teks, itu adalah hotspot yang bisa diklik, wilayah kecil tempat ikon catatan berada dan di mana klik membuka komentar. Untuk kotak persegi atau teks bebas, itu adalah batas yang terlihat dari markup. Untuk stempel, itu adalah kotak tempat seni stempel diskalakan. Angka-angkanya dalam poin ruang pengguna PDF, diukur dari sudut kiri bawah halaman dengan Y meningkat ke atas, konvensi yang sama yang digunakan HotPDF selebihnya

Catatan teks adalah subtipe yang paling ringan. Anda memberikannya teks isi, persegi panjang untuk ikon, flag apakah terbuka secara default, nama ikon, dan warna

Pdf.CurrentPage.AddTextAnnotation(
  'Reviewer: confirm the totals on this line before sign-off.',
  Rect(120, 700, 140, 720),   // icon hotspot, ~20pt square
  False,                      // closed until the reader clicks it
  taComment,                  // bubble icon
  clBlue);

Persegi panjang di sini sengaja dibuat kecil, sekitar dua puluh poin per sisi, karena catatan teks hanyalah ikon sampai seseorang mengkliknya. Buat persegi panjang besar dan Anda tidak mendapatkan catatan yang besar; Anda mendapatkan target klik yang terlalu besar dengan ikon yang ditambatkan ke satu sudut. Flag Open mengontrol apakah popup ditampilkan saat dokumen dimuat. Tetapkan beberapa catatan ke True dan mereka akan bertumpuk di atas satu sama lain dan di atas konten, jadi simpan untuk satu catatan yang benar-benar ingin Anda tunjukkan langsung kepada pembaca

Nama ikon berasal dari THPDFTextAnnotationType, yang memetakan ke ikon catatan standar: taComment, taKey, taNote, taHelp, taParagraph, taNewParagraph, dan taInsert. Ikon adalah satu-satunya hal yang diubah jenis tersebut. Ini tidak mengubah perilaku, dan perlu diketahui bahwa tidak setiap penampil menggambar semua tujuh; yang aman di seluruh pembaca lama dan baru adalah taComment, taNote, dan taHelp

Teks bebas menulis ke halaman, tetapi tetap sebagai anotasi

Anotasi teks bebas terlihat seperti konten karena teksnya terlihat tanpa klik, duduk di persegi panjangnya seperti keterangan. Ini tetap anotasi, dengan semua kemampuan pemisahan yang tersirat, yang persis apa yang Anda inginkan untuk stempel tinjauan atau label draf yang harus bisa dihapus seseorang nanti. Tanda tangannya menukar ikon dan flag terbuka dengan nilai justifikasi

Pdf.CurrentPage.AddFreeTextAnnotation(
  'DRAFT - not for distribution',
  Rect(200, 210, 400, 235),   // the box the text is laid into
  ftCenter,                   // ftLeftJust / ftCenter / ftRightJust
  clRed);

Di sini persegi panjang lebih penting daripada untuk catatan teks, karena teks membungkus dan sejajar di dalamnya. Ukuran kotak terlalu pendek dan teks terpotong di tepi bawah; terlalu sempit dan teks membungkus di tempat yang tidak Anda maksudkan. Justifikasi berasal dari THPDFFreeTextAnnotationJust dan hanya memiliki tiga nilai. Karena teks bebas adalah anotasi markup, pembaca yang membuka file dalam editor dapat memilihnya, memindahkannya, atau menghapusnya sebagai satu unit, yang merupakan perbedaan yang menentukan apakah Anda menggunakan teks bebas atau sekadar menggambar kata-kata dengan TextOut. Jika labelnya harus permanen, gambarlah. Jika bersifat editorial dan dimaksudkan untuk dihapus, jadikan anotasi

Markup geometris dan garis untuk menunjuk ke sesuatu

Persegi panjang, lingkaran, dan garis adalah markup yang Anda gunakan untuk menunjuk ke suatu wilayah daripada mendeskripsikannya dengan kata-kata. AddCircleSquareAnnotation mencakup dua bentuk kotak melalui THPDFCSAnnotationType berupa csCircle atau csSquare, dengan persegi panjang memberikan batas bentuk

// A box drawn around a figure that needs attention
Pdf.CurrentPage.AddCircleSquareAnnotation(
  'Check this region against the source data',
  Rect(50, 300, 120, 360),
  csSquare,
  clGreen);

// A line, given two points rather than a rectangle
var
  StartPt, EndPt: THPDFCurrPoint;
begin
  StartPt.X := 130; StartPt.Y := 360;
  EndPt.X   := 250; EndPt.Y   := 320;
  Pdf.CurrentPage.AddLineAnnotation(
    'Points from the note to the figure',
    StartPt, EndPt,
    clBlue);
end;

Perhatikan bahwa anotasi garis memutus pola persegi panjang: ia mengambil dua record THPDFCurrPoint, awal dan akhir, karena garis didefinisikan oleh titik-titik ujungnya, bukan oleh kotak pembatas. Warna menetapkan stroke. Jika Anda menginginkan kepala panah, HotPDF memiliki overload AddLineAnnotation yang menerima gaya ujung garis, tetapi form tiga argumen polos menggambar garis kosong, yang biasanya diinginkan callout

Subtipe markup teks bekerja pada wilayah yang sudah Anda tata. AddHighlightAnnotation mengambil persegi panjang, konten opsional, dan warna yang defaultnya kuning, serta mewarnai area seperti pena stabilo. Ini dimaksudkan untuk duduk di atas teks asli, jadi persegi panjang harus cocok dengan batas kata-kata yang Anda gambar, yang berarti Anda biasanya menghitungnya dari koordinat yang sama yang Anda berikan ke TextOut daripada menebak

Stempel bergantung pada penampil untuk merendernya

Anotasi stempel adalah yang paling mungkin terlihat berbeda dari satu pembaca ke pembaca lain, dan alasannya layak dipahami. AddStampAnnotation menamai stempel standar melalui THPDFStampAnnotationType, dengan nilai seperti satApproved, satConfidential, satFinal, satDraft, dan satForComment

Pdf.CurrentPage.AddStampAnnotation(
  'Approved for release on review',
  Rect(50, 400, 200, 440),
  satApproved,
  clGreen);

Nama stempel adalah permintaan. PDF mendefinisikan kumpulan nama stempel standar tetapi bukan karya seni di baliknya, sehingga setiap penampil mengirimkan renderingnya sendiri tentang "APPROVED" atau "CONFIDENTIAL," dan beberapa tidak merender apa pun sama sekali untuk nama yang tidak mereka kenali. Persegi panjang mengontrol kotak tempat seni diskalakan, dan warna adalah petunjuk yang mungkin atau tidak diikuti penampil. Jika stempel harus terlihat identik di mana-mana, rute yang andal bukan stempel standar sama sekali: gambarlah tanda sendiri dengan TextOut dan pemanggilan gambar, atau tempatkan sebagai anotasi teks bebas yang tampilannya Anda kendalikan. Gunakan stempel standar ketika Anda menginginkan tampilan familiar penampil dan bisa menerima variasi tersebut

Lampiran file mengikuti bentuk persegi panjang-plus-payload yang sama. AddFileAttachmentAnnotation mengambil deskripsi, jalur file yang akan disematkan, persegi panjang untuk ikon penjepit kertas, dan warna. File menumpang di dalam PDF, dan ikon adalah pegangan yang digunakan pembaca untuk mengekstraknya

Cara anotasi berbeda dari field AcroForm

Kebingungan yang paling banyak memakan waktu adalah memperlakukan anotasi seolah-olah itu field formulir. Keduanya menempel pada halaman melalui /Annots, dan field formulir sebenarnya adalah subtipe anotasi khusus (widget), itulah mengapa keduanya terlihat terkait. Mereka tidak bisa dipertukarkan. Field formulir menyimpan nilai, memiliki nama, berpartisipasi dalam urutan tab, dan bisa dikirim, direset, atau di-skrip; Anda membuat ini dengan pemanggilan AddTextField, AddCheckBox, dan AddPushButton, bukan pemanggilan anotasi di halaman ini. Anotasi markup menyimpan komentar atau bentuk, tidak memiliki nilai untuk dikirim, dan merupakan alat yang salah begitu Anda perlu mengumpulkan input

Uji praktisnya sederhana. Jika pengguna dimaksudkan untuk mengetik, memilih, atau mengklik dan dokumen harus mengingatnya, Anda menginginkan field AcroForm. Jika Anda meninggalkan catatan, menandai wilayah, atau mencap status yang menyertai file tetapi bukan data, Anda menginginkan anotasi. Mencampurnya menghasilkan dokumen yang terlihat benar dan berperilaku salah: "field" yang tidak bisa diisi siapa pun, atau komentar yang menghilang saat formulir direset. Sisi interaktif, dengan jenis field, validasi, dan aksi submit, adalah subjek tersendiri yang dibahas dalam panduan field dan aksi AcroForm

Menyatukan halaman

Potongan-potongan ini tersusun seperti HotPDF selebihnya. Atur properti dokumen, panggil BeginDoc, gambar konten halaman apa pun yang Anda butuhkan dengan pemanggilan teks dan grafis, tambahkan anotasi di atasnya, dan tutup dengan EndDoc. Anotasi menempel pada CurrentPage, jadi setelah AddPage mereka mendarat di halaman baru, dan catatan yang Anda maksudkan untuk halaman satu akan muncul diam-diam di halaman dua jika Anda menambahkannya setelah jeda

Pdf := THotPDF.Create(nil);
try
  Pdf.FileName := 'annotated.pdf';
  Pdf.Compression := cmFlateDecode;
  Pdf.FontEmbedding := True;
  Pdf.BeginDoc;

  Pdf.CurrentPage.SetFont('Arial', [], 11);
  Pdf.CurrentPage.TextOut(50, 740, 0, 'Quarterly figures, draft for review');

  Pdf.CurrentPage.AddTextAnnotation(
    'Confirm the totals before sign-off.',
    Rect(50, 720, 70, 740), False, taComment, clBlue);
  Pdf.CurrentPage.AddFreeTextAnnotation(
    'DRAFT', Rect(450, 720, 540, 745), ftCenter, clRed);
  Pdf.CurrentPage.AddStampAnnotation(
    'For comment', Rect(50, 660, 180, 695), satForComment, clGreen);

  Pdf.EndDoc;
finally
  Pdf.Free;
end;

Satu refleks terakhir yang layak dibangun ketika keluaran terlihat salah: buka file di lebih dari satu penampil sebelum Anda memutuskan kodenya rusak. Stempel dan ikon catatan yang lebih jarang adalah tersangka biasa, dan karena anotasi adalah permintaan ke pembaca daripada piksel yang dilukis, perbedaan antara Acrobat dan penampil ringan sering kali merupakan spec yang bekerja sebagaimana mestinya, bukan bug dalam pemanggilan Anda

Pemanggilan anotasi yang ditampilkan di sini adalah bagian dari HotPDF Component untuk Delphi dan C++Builder