PDF bilješke u Delphiju uz HotPDF: vrste i pravokutnici

Bilješka (annotation) nije sadržaj stranice. Kada pozovete TextOut ili nacrtate pravokutnik, oznake postaju dio toka sadržaja stranice, ugrađene u bajtove koje renderer iscrtava. Bilješka je zaseban rječnik (dictionary) koji se povezuje sa stranicom putem njezina polja /Annots, sa svojim vlastitim pravokutnikom, vlastitim izgledom i životnim ciklusom. Preglednik je može otvoriti, premjestiti, sakriti ili ukloniti bez utjecaja na ijedan znak same stranice. To je razdvajanje cijeli razlog zašto bilješke postoje, a ujedno je i izvor dviju stvari koje najprije iznenade ljude: gdje bilješka završava i kako izgleda kada je određeni preglednik prikaže.

HotPDF izlaže podvrste bilješki prema ISO 32000 standardu kroz obitelj poziva AddXxxAnnotation na objektu stranice. Svi oni dijele isti oblik: pravokutnik koji fiksira bilješku na stranici u korisničkom prostoru PDF-a, sadržaj (tekst, naziv pečata, par točaka) i boju. Postavite pravokutnik ispravno i većina posla je obavljena. Ostatak se svodi na prepoznavanje koje podvrste nose vlastiti izgled, a koje se oslanjaju na preglednik da ih iscrta.

Pravokutnik je bilješka, a ne tekst

Svaki poziv bilješke prima TRect, a taj pravokutnik znači nešto posve drugo od koordinata koje prosljeđujete u TextOut. Za tekstualnu bilješku to je aktivno područje (hotspot) na koje se može kliknuti, mali prostor gdje se nalazi ikona bilješke i gdje klik otvara prozorčić s komentarom. Za kvadrat ili okvir sa slobodnim tekstom to je vidljivi raspon oznake. Za pečat to je okvir unutar kojeg se slika pečata skalira. Vrijednosti su točke u korisničkom prostoru PDF-a, mjerene od donjeg lijevog kuta stranice s osi Y koja raste prema gore, što je ista konvencija koju koristi i ostatak HotPDF-a.

Tekstualna bilješka je najjednostavnija podvrsta. Dajete joj tekst sadržaja, pravokutnik za ikonu, oznaku treba li se otvoriti po zadanim postavkama, naziv ikone i boju.

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);

Pravokutnik je ovdje namjerno malen, otprilike dvadesetak točaka po stranici, ove tekstualna bilješka je samo ikona dok netko na nju ne klikne. Ako pravokutnik učinite velikim, nećete dobiti veliku bilješku, već preveliko područje za klik s ikonom prikovanom za jedan kut. Zastavica Open kontrolira prikazuje li se skočni prozorčić pri učitavanju dokumenta. Ako postavite nekoliko bilješki na True, one će se naslagati jedna preko druge i preko sadržaja stranice, pa to sačuvajte samo za onu bilješku koju doista želite da čitatelj odmah uoči.

Naziv ikone dolazi iz THPDFTextAnnotationType, koji se preslikava na standardne ikone bilješki: taComment, taKey, taNote, taHelp, taParagraph, taNewParagraph i taInsert. Ikona je jedina stvar koju vrsta mijenja; ona ne utječe na ponašanje i vrijedi znati da ne prikazuje svaki preglednik svih sedam ikona. Najsigurnije za korištenje u starim i novim čitačima su taComment, taNote i taHelp.

Slobodan tekst piše po stranici, ali ostaje bilješka

Bilješka sa slobodnim tekstom (free text annotation) izgleda kao dio sadržaja jer je tekst vidljiv bez klika, smješten u svom pravokutniku poput natpisa. Ipak, to je i dalje bilješka sa svim prednostima odvojenosti koje to donosi, što je upravo ono što želite za oznaku pregleda ili nacrta koju bi netko kasnije trebao moći ukloniti. Deklaracija metode zamjenjuje ikonu i zastavicu otvaranja vrijednošću poravnanja.

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

Ovdje je pravokutnik važniji nego kod tekstualne bilješke jer se tekst prelama i poravnava unutar njega. Ako je okvir prekratak, tekst će se odsjeći na donjem rubu; ako je preusko, prelomit će se na mjestima koja niste željeli. Poravnanje dolazi iz THPDFFreeTextAnnotationJust i nudi samo tri vrijednosti. Budući da je slobodan tekst bilješka za označavanje (markup), čitatelj koji otvori datoteku u uređivaču može je odabrati, pomaknuti ili obrisati kao cjelinu, što je ključna razlika koja odlučuje hoćete li upotrijebiti slobodan tekst ili jednostavno ispisati riječi pomoću TextOut. Ako oznaka mora biti trajna, nacrtajte je. Ako je urednička i predviđena za uklanjanje, učinite je bilješkom.

Geometrijske i linijske oznake za pokazivanje na elemente

Kvadrati, krugovi i linije su oznake koje koristite za pokazivanje na područje umjesto opisivanja riječima. AddCircleSquareAnnotation pokriva ova dva oblika kroz THPDFCSAnnotationType vrijednosti csCircle ili csSquare, pri čemu pravokutnik određuje granice oblika.

// 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;

Primijetite da linijska bilješka odstupa od uzorka s pravokutnikom: ona prima dva zapisa THPDFCurrPoint, početnu i završnu točku, jer je linija definirana svojim krajevima, a ne okvirnim pravokutnikom. Boja određuje boju linije (stroke). Ako želite strelice na krajevima, HotPDF ima preopterećene (overloaded) verzije AddLineAnnotation koje prihvaćaju stilove završetaka linija, ali običan oblik s tri argumenta crta jednostavnu liniju, što je obično ono što vam treba.

Podvrste za označavanje teksta rade na području koje ste već postavili. AddHighlightAnnotation prima pravokutnik, neobavezni sadržaj i boju koja je prema zadanim postavkama žuta, te boji to područje kao marker. Namijenjen je postavljanju preko stvarnog teksta, pa bi pravokutnik trebao odgovarati granicama riječi koje ste nacrtali, što znači da ga općenito izračunavate iz istih koordinata koje ste proslijedili u TextOut umjesto nagađanja.

Pečati ovise o pregledniku za njihovo renderiranje

Bilješka pečata (stamp annotation) je ona koja će najvjerojatnije izgledati različito u različitim preglednicima, a razlog tome vrijedi razumjeti. Metoda AddStampAnnotation označava standardni pečat kroz THPDFStampAnnotationType s vrijednostima kao što su satApproved, satConfidential, satFinal, satDraft i satForComment.

Naziv pečata je samo zahtjev. PDF definira skup standardnih naziva pečata, ali ne i grafički izgled iza njih, pa svaki preglednik isporučuje vlastiti prikaz za \"APPROVED\" ili \"CONFIDENTIAL\", a neki ne renderiraju ništa za nazive koje ne prepoznaju. Pravokutnik kontrolira okvir u koji se slika skalira, a boja je samo smjernica koju preglednik može, ali i ne mora poštovati. Ako pečat mora izgledati identično svugdje, najsigurniji put uopće nije standardni pečat: nacrtajte oznaku sami pomoću TextOut i grafičkih poziva ili je postavite kao bilješku sa slobodnim tekstom čiji izgled sami kontrolirate. Koristite standardni pečat kada želite prepoznatljiv izgled samog čitača i možete tolerirati varijacije.

Priložene datoteke (file attachments) prate isti oblik pravokutnika i sadržaja. AddFileAttachmentAnnotation prima opis, putanju datoteke koju ugrađuje, pravokutnik za ikonu spajalice i boju. Datoteka se nalazi unutar PDF-a, a ikona je prečac pomoću kojeg je čitatelj može izdvojiti.

Kako se bilješke razlikuju od AcroForm polja

Zabuna koja košta najviše vremena je tretiranje bilješke kao da je polje obrasca. Oboje se povezuje sa stranicom putem /Annots, a polje obrasca je zapravo posebna podvrsta bilješke (widget), zbog čega izgledaju slično. Ipak, oni nisu međusobno zamjenjivi. Polje obrasca sadrži vrijednost, ima naziv, sudjeluje u redoslijedu kartica (tab order) i može se poslati, resetirati ili skriptirati; njih stvarate pozivima AddTextField, AddCheckBox i AddPushButton, a ne pozivima za bilješke na ovoj stranici. Oznaka (markup annotation) sadrži komentar ili oblik, nema vrijednost za slanje i pogrešan je alat ako trebate prikupiti unos korisnika.

Praktični test je jednostavan. Ako korisnik treba upisati tekst, odabrati opciju ili kliknuti tako da dokument to zapamti, trebate AcroForm polje. Ako ostavljate bilješku, označavate područje ili utiskujete status koji putuje s datotekom, ali ne predstavlja podatke, trebate bilješku. Miješanje ovih koncepata proizvodi dokumente koji izgledaju ispravno, ali se ponašaju pogrešno: \"polje\" koje nitko ne može ispuniti ili komentar koji nestane kada se obrazac resetira. Interaktivna strana, s vrstama polja, provjerom valjanosti i akcijama slanja, zasebna je tema pokrivena u pregledu AcroForm polja i akcija.

Sastavljanje stranice

Dijelovi se slažu na isti način kao i ostatak HotPDF-a. Postavite svojstva dokumenta, pozovite BeginDoc, nacrtajte sadržaj stranice pomoću poziva za tekst i grafiku, dodajte bilješke na vrh i zatvorite s EndDoc. Bilješke se dodaju na CurrentPage, pa nakon poziva AddPage one slijeću na nova stranicu, a bilješka koju ste namijenili prvoj stranici tiho će se pojaviti na drugoj ako je dodate nakon prijeloma.

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;

Još jedna navika koju vrijedi izgraditi kada izlaz izgleda pogrešno: otvorite datoteku u više od jednog preglednika prije nego što odlučite da kod ne radi. Pečati i rjeđe ikone bilješki uobičajeni su krivci, a budući da je bilješka samo zahtjev pregledniku, a ne iscrtani pikseli, razlika između Acrobata i nekog jednostavnijeg preglednika često je specifikacija koja radi kako je zamišljeno, a ne bug u vašem kodu.

Pozovi za bilješke prikazani ovdje dio su komponente HotPDF Component za Delphi i C++Builder.