PDF anotacije u Delphiju uz HotPDF: Tipovi i pravougaonici

Anotacija nije sadržaj stranice. Kada pozovete TextOut ili iscrtate pravougaonik, te oznake postaju deo toka sadržaja stranice, zapečene u bajtove koje softver za renderovanje iscrtava. Anotacija je poseban rečnik (dictionary) koji je prikačen na stranicu putem njenog niza /Annots, sa sopstvenim pravougaonikom, izgledom i životnim ciklusom. Čitač je može otvoriti, premestiti, sakriti ili ukloniti, a da pritom ne dotakne nijedan glif na samoj stranici. To razdvajanje je razlog zašto anotacije uopšte postoje i to je ujedno i izvor dve stvari koje obično prvo iznenade korisnike: gde anotacija završi i kako izgleda kada je određeni program za pregled obradi

HotPDF izlaže ISO 32000 podtipove anotacija kroz porodicu poziva AddXxxAnnotation na objektu stranice. Svi oni dele isti oblik: pravougaonik koji fiksira anotaciju na stranici u korisničkom prostoru PDF-a, određeni sadržaj (tekst, naziv pečata, par tačaka) i boju. Kada postavite pravi pravougaonik, veći deo posla je obavljen. Ostatak je znati koji podtipovi nose sopstveni izgled, a koji se oslanjaju na program za pregled da ih iscrta

Pravougaonik je anotacija, a ne tekst

Svaki poziv za anotaciju uzima TRect, a taj pravougaonik označava nešto drugačije od koordinata koje prosleđujete TextOut-u. Za tekstualnu belešku to je oblast na koju se može kliknuti, mala regija u kojoj se nalazi ikona beleške i gde klik otvara komentar. Za kvadrat ili okvir slobodnog teksta to je vidljivi opseg oznake. Za pečat, to je okvir unutar kojeg će grafika pečata biti prilagođena. Brojevi su tačke u korisničkom prostoru PDF-a, merene od donjeg levog ugla stranice, pri čemu Y raste nagore, ista konvencija koju koristi ostatak HotPDF-a

Tekstualna beleška je najlakši podtip. Dajete joj tekst tela, pravougaonik za ikonu, oznaku da li se podrazumevano otvara, naziv ikone i boju

Pdf.CurrentPage.AddTextAnnotation(
  'Reviewer: confirm the totals on this line before sign-off.',
  Rect(120, 700, 140, 720),   // hotspot ikone, kvadrat od ~20pt
  False,                      // zatvoreno dok čitač ne klikne
  taComment,                  // ikona oblačića
  clBlue);

Pravougaonik ovde je namerno mali, oko dvadeset tačaka sa svake strane, jer je tekstualna beleška samo ikona dok neko ne klikne na nju. Ako napravite pravougaonik velikim, ne dobijate veliku belešku; dobijate preveliku metu za klik sa ikonom zakačenom za jedan ugao. Open oznaka kontroliše da li je iskačući prozor prikazan kada se dokument učita. Postavite nekoliko beleški na True i one će se složiti jedna na drugu i preko sadržaja, tako da rezervišite to za onu jednu belešku koju zaista želite da čitalac odmah vidi

Ime ikone dolazi iz THPDFTextAnnotationType, koji se mapira na standardne ikone beleški: taComment, taKey, taNote, taHelp, taParagraph, taNewParagraph i taInsert. Ikona je jedino što se menja kod ovog tipa. Ne menja ponašanje, i vredi znati da ne crta svaki program svih sedam ikona; najsigurniji izbor za starije i novije čitače su taComment, taNote i taHelp

Slobodan tekst se piše po stranici, ali ostaje anotacija

Anotacija slobodnog teksta (free text) izgleda kao sadržaj jer je tekst vidljiv bez klika, nalazeći se u svom pravougaoniku kao natpis. To je i dalje anotacija, sa svom odvojivošću koju to podrazumeva, a to je upravo ono što želite za pregledni pečat ili oznaku za nacrt koju bi neko kasnije mogao da ukloni. Njena signatura zamenjuje ikonu i oznaku za otvaranje za vrednost poravnanja

Pdf.CurrentPage.AddFreeTextAnnotation(
  'DRAFT - not for distribution',
  Rect(200, 210, 400, 235),   // kutija unutar koje će tekst biti smešten
  ftCenter,                   // ftLeftJust / ftCenter / ftRightJust
  clRed);

Ovde je pravougaonik bitniji nego kod tekstualne beleške, jer se tekst prelama i poravnava unutar njega. Ako je okvir prekratak, tekst će se iseći na donjoj ivici; ako je preuzak, prelomiće se tamo gde to niste nameravali. Poravnanje dolazi iz THPDFFreeTextAnnotationJust i ima samo tri vrednosti. Pošto je slobodan tekst u stvari oznaka (markup), čitalac koji otvori fajl u uređivaču može je odabrati, premestiti ili izbrisati kao celinu, što je razlika koja odlučuje da li ćete posegnuti za slobodnim tekstom ili ćete samo ispisati reči pomoću TextOut-a. Ako natpis mora da bude trajan, nacrtajte ga. Ako je urednički i namenjen za uklanjanje, napravite ga kao anotaciju

Geometrijske i linijske oznake za usmeravanje pažnje

Kvadrati, krugovi i linije su oznake koje koristite da usmerite pažnju na određenu regiju, a ne da je opišete rečima. AddCircleSquareAnnotation pokriva dva oblika okvira kroz THPDFCSAnnotationType koji može biti csCircle ili csSquare, pri čemu pravougaonik predstavlja granice tog oblika

// Kutija nacrtana oko figure na koju treba obratiti pažnju
Pdf.CurrentPage.AddCircleSquareAnnotation(
  'Check this region against the source data',
  Rect(50, 300, 120, 360),
  csSquare,
  clGreen);

// Linija, definisana sa dve tačke umesto pravougaonikom
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;

Primetite da linijska anotacija prekrši obrazac sa pravougaonikom: uzima dve THPDFCurrPoint evidencije (record), početak i kraj, jer je linija definisana svojim krajnjim tačkama, a ne graničnim okvirom. Boja postavlja crtu (stroke). Ako želite vrhove strelica, HotPDF ima preopterećenja za AddLineAnnotation koja prihvataju stilove završetka linije, ali običan oblik sa tri argumenta crta čistu liniju, što je najčešće ono što Vam treba kod ovakvih prozivki

Podtipovi tekstualnih oznaka rade na regiji koju ste već rasporedili. AddHighlightAnnotation uzima pravougaonik, opcione sadržaje i boju koja je podrazumevano žuta, i nijansira to područje onako kako bi to uradio marker. Namenjen je da stoji preko pravog teksta, pa pravougaonik treba da odgovara granicama reči koje ste ispisali, što znači da ga obično izračunavate na osnovu istih koordinata koje ste prosledili TextOut-u, a ne da nagađate

Pečati se oslanjaju na program za pregled da bi se prikazali

Anotacija pečata (stamp) je ta za koju je najverovatnije da će izgledati drugačije od jednog do drugog čitača, a razlog vredi razumeti. AddStampAnnotation imenuje standardni pečat preko THPDFStampAnnotationType, sa vrednostima kao što su satApproved, satConfidential, satFinal, satDraft i satForComment

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

Ime pečata je zapravo zahtev. PDF definiše set standardnih imena za pečate, ali ne i umetnička dela (grafiku) iza njih, tako da svaki program isporučuje sopstveni vizuelni prikaz za "APPROVED" (Odobreno) ili "CONFIDENTIAL" (Poverljivo), a neki ne renderuju ništa za imena koja ne prepoznaju. Pravougaonik kontroliše okvir unutar kojeg se umetničko delo razmerava, a boja je nagoveštaj koji program za pregled može ili ne mora da uvaži. Ako pečat mora da izgleda isto svuda, pouzdan put uopšte nije standardni pečat: nacrtajte oznaku sami koristeći TextOut i pozive za iscrtavanje, ili je postavite kao anotaciju slobodnog teksta čiji izgled Vi kontrolišete. Koristite standardni pečat kada želite poznat izgled programa za pregled i kada Vam ne smetaju varijacije

Prilozi u obliku fajlova prate isti obrazac sa pravougaonikom i sadržajem. AddFileAttachmentAnnotation uzima opis, putanju do fajla koji će biti ugrađen, pravougaonik za ikonu spajalice i boju. Fajl putuje unutar PDF-a, a ikona je ručka koju čitalac koristi za njegovo izdvajanje

Po čemu se anotacije razlikuju od AcroForm polja

Zabuna koja oduzima najviše vremena jeste tretiranje anotacije kao da je polje forme (form field). I jedno i drugo su zakačeni za stranicu preko /Annots, a polje forme zapravo i jeste poseban podtip anotacije (widget), zbog čega izgledaju srodno. Međutim, nisu zamenljivi. Polje forme sadrži vrednost, ima ime, učestvuje u redosledu pritiskanja Tab tastera, i može biti poslato (submit), resetovano ili skriptovano; te elemente kreirate pomoću poziva AddTextField, AddCheckBox i AddPushButton, a ne pozivima za anotacije sa ove stranice. Anotacija tipa oznake drži komentar ili oblik, nema vrednost za slanje, i pogrešan je alat onog momenta kada morate da prikupite unos korisnika

Praktični test je jednostavan. Ako je predviđeno da korisnik unese tekst, izabere opciju ili klikne i da dokument to zapamti, potrebno Vam je AcroForm polje. Ako ostavljate belešku, obeležavate regiju ili udarate pečat o statusu koji ide uz dokument ali nije podatak, potrebna Vam je anotacija. Njihovo mešanje daje dokumente koji izgledaju ispravno ali se ponašaju pogrešno: "polje" koje niko ne može da popuni, ili komentar koji nestane kada se forma resetuje. Interaktivna strana, sa tipovima polja, validacijom i akcijama slanja, posebna je tema obrađena u AcroForm polja i akcije vodiču

Sastavljanje stranice

Delovi se slažu onako kako to radi ostatak HotPDF-a. Postavite svojstva dokumenta, pozovite BeginDoc, nacrtajte sav potreban sadržaj na stranici korišćenjem poziva za tekst i grafiku, dodajte anotacije povrh toga i završite sa EndDoc. Anotacije se kače na CurrentPage, tako da će posle AddPage završiti na novoj stranici, pa će se beleška koju ste namenili za prvu stranicu tiho pojaviti na drugoj stranici ako je dodate nakon preloma

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;

Poslednji refleks koji vredi izgraditi kada izlazni rezultat izgleda pogrešno: otvorite fajl u više od jednog programa za pregled pre nego što zaključite da Vam kod ne valja. Pečati i ređe ikone beleški obično su krivci, a pošto je anotacija zahtev za čitač a ne obojeni piksel, razlika između Acrobat-a i nekog laganog programa često znači da standard radi onako kako je dizajnirano, a nije greška u Vašem pozivu

Pozivi za anotacije prikazani ovde su deo HotPDF komponente za Delphi i C++Builder