Anotácie PDF v Delphi s HotPDF: Typy a obdĺžniky (rects)

Anotácia nie je obsahom stránky. Keď zavoláte TextOut alebo nakreslíte obdĺžnik, značky sa stanú súčasťou prúdu obsahu (content stream) stránky, zapísané priamo do bajtov, ktoré vykresľuje prehliadač. Anotácia je samostatný slovník (dictionary), ktorý je pripojený k stránke prostredníctvom jej poľa /Annots, s vlastným obdĺžnikom, vlastným vzhľadom a vlastným životným cyklom. Používateľ ju môže otvoriť, presunúť, skryť alebo odstrániť bez toho, aby sa dotkol jediného znaku na pôvodnej stránke. Toto oddelenie je hlavným dôvodom, prečo anotácie existujú, a je tiež zdrojom dvoch vecí, ktoré vývojárov často prekvapia: kde presne sa anotácia zobrazí a ako vyzerá, keď ju spracuje konkrétny prehliadač PDF.

HotPDF sprístupňuje podtypy anotácií podľa štandardu ISO 32000 prostredníctvom rodiny volaní AddXxxAnnotation nad objektom stránky. Všetky zdieľajú rovnaký tvar: obdĺžnik, ktorý umiestňuje anotáciu na stránke v používateľskom priestore PDF (user space), samotný obsah (text, názov pečiatky, dvojica bodov) a farbu. Ak správne nastavíte obdĺžnik, väčšina práce je hotová. Zvyšok spočíva v tom, že musíte vedieť, ktoré podtypy majú vlastný vzhľad a ktoré sa pri vykresľovaní spoliehajú na prehliadač.

Obdĺžnik definuje anotáciu, nie text

Každé volanie anotácie prijíma parameter TRect, pričom tento obdĺžnik znamená niečo iné ako súradnice, ktoré odovzdávate metóde TextOut. Pri textovej poznámke ide o klikateľnú oblasť (hotspot), teda malú zónu, kde sa zobrazuje ikona poznámky a kde kliknutie otvorí komentár. Pri štvorci alebo poli s voľným textom je to viditeľný rozsah samotnej značky. Pri pečiatke predstavuje rámec, do ktorého sa prispôsobí grafika pečiatky. Hodnoty sú vyjadrené v bodoch používateľského priestoru PDF, merané od ľavého dolného rohu stránky, pričom os Y rastie smerom nahor, čo je rovnaká konvencia, akú používa aj zvyšok knižnice HotPDF.

Textová poznámka je najjednoduchší podtyp. Odovzdávate jej text tela, obdĺžnik pre ikonu, príznak, či sa má predvolene otvoriť, názov ikony a farbu.

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

Obdĺžnik je tu zámerne malý, približne dvadsať bodov na každú stranu, pretože textová poznámka je iba ikonou, kým na ňu niekto neklikne. Ak vytvoríte veľký obdĺžnik, nezískate veľkú poznámku, ale len nadmerne veľkú klikateľnú plochu s ikonou prichytenou v jednom rohu. Príznak Open určuje, či sa vyskakovacie okno zobrazí hneď pri načítaní dokumentu. Ak nastavíte viacero poznámok na hodnotu True, prekryjú sa navzájom aj samotný obsah stránky, preto túto možnosť ukladajte len pre tú poznámku, ktorú má čitateľ vidieť okamžite.

Názov ikony pochádza z THPDFTextAnnotationType, čo zodpovedá štandardným ikonám poznámok: taComment, taKey, taNote, taHelp, taParagraph, taNewParagraph a taInsert. Typ mení iba samotnú ikonu, nemení správanie. Stojí za zmienku, že nie každý prehliadač dokáže vykresliť všetkých sedem typov; najbezpečnejšie a najkompatibilnejšie v starých aj nových prehliadačoch sú taComment, taNote a taHelp.

Voľný text píše priamo na stránku, no zostáva anotáciou

Anotácia voľného textu vyzerá ako bežný obsah stránky, pretože text je viditeľný bez kliknutia a nachádza sa vo svojom obdĺžniku ako popisok. Stále je to však anotácia so všetkými výhodami oddeliteľnosti, čo je presne to, čo potrebujete pre korektorské pečiatky alebo označenie konceptu, ktoré by malo byť neskôr možné odstrániť. Definícia metódy nahrádza ikonu a príznak otvorenia hodnotou zarovnania.

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

V tomto prípade na obdĺžniku záleží viac než pri textovej poznámke, pretože text sa v ňom zalomí a zarovná. Ak určíte príliš nízky rámček, text sa na spodnom okraji odreže; ak bude príliš úzky, zalomí sa na miestach, kde ste to neplánovali. Zarovnanie pochádza z THPDFFreeTextAnnotationJust a má iba tri hodnoty. Keďže voľný text je pripomienkovou anotáciou, čitateľ, ktorý otvorí súbor v editore, ho môže označiť, presunúť alebo vymazať ako celok. To je zásadný rozdiel pri rozhodovaní, či použiť voľný text, alebo len vykresliť slová pomocou TextOut. Ak má byť nápis trvalý, vykreslite ho. Ak je redakčný a má sa dať odstrániť, urobte z neho anotáciu.

Geometrické značky a čiary na ukazovanie na objekty

Štvorce, kruhy a čiary sú značky, ktoré používate na označenie oblasti namiesto jej opisovania slovami. Metóda AddCircleSquareAnnotation pokrýva tieto dva tvary prostredníctvom typu THPDFCSAnnotationType s hodnotami csCircle alebo csSquare, kde obdĺžnik definuje hranice tvaru.

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

Všimnite si, že anotácia čiary sa vymyká vzoru obdĺžnika: vyžaduje dva záznamy THPDFCurrPoint (začiatok a koniec), pretože čiara je definovaná svojimi koncovými bodmi, nie ohraničujúcim rámcom. Farba nastavuje ťah pera. Ak chcete šípky na koncoch čiar, HotPDF ponúka preťaženia metódy AddLineAnnotation, ktoré prijímajú štýly zakončenia čiary, ale základná trojargumentová forma vykreslí jednoduchú čiaru, čo pre bežné ukazovatele zvyčajne postačuje.

Podtypy pre zvýrazňovanie textu pracujú nad oblastami, ktoré ste už na stránke vytvorili. Metóda AddHighlightAnnotation prijíma obdĺžnik, voliteľný obsah a farbu, ktorá je predvolene žltá, a vyfarbí danú oblasť podobne ako zvýrazňovač. Je navrhnutá tak, aby prekrývala skutočný text, takže obdĺžnik by mal presne zodpovedať hraniciam vykreslených slov. To znamená, že súradnice spravidla vypočítate z hodnôt odovzdaných metóde TextOut, namiesto toho, aby ste ich odhadovali.

Pečiatky závisia od toho, ako ich vykreslí prehliadač

Anotácia pečiatky je podtypom, ktorý bude najpravdepodobnejšie vyzerať odlišne v rôznych prehliadačoch, pričom dôvod tohto správania je dôležité pochopiť. Metóda AddStampAnnotation špecifikuje štandardnú pečiatku prostredníctvom typu THPDFStampAnnotationType, s hodnotami ako satApproved, satConfidential, satFinal, satDraft a satForComment.

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

Názov pečiatky funguje ako požiadavka. Špecifikácia PDF definuje sadu štandardných názvov pečiatok, ale nie grafiku, ktorá sa za nimi skrýva. Každý prehliadač tak poskytuje vlastné zobrazenie nápisov „APPROVED“ alebo „CONFIDENTIAL“ a niektoré nemusia zobraziť vôbec nič, ak daný názov nerozoznajú. Obdĺžnik určuje rozsah, do ktorého sa grafika prispôsobí, a farba slúži ako odporúčanie, ktoré prehliadač môže, ale nemusí rešpektovať. Ak pečiatka musí vyzerať všade úplne rovnako, spoľahlivým riešením nie je štandardná pečiatka: nakreslite ju ručne pomocou TextOut a kresliacich príkazov, prípadne ju umiestnite ako anotáciu voľného textu, ktorej vzhľad plne ovládate. Po štandardnej pečiatke siahnite vtedy, keď chcete využiť známy vzhľad daného prehliadača a nevadia vám drobné odchýlky.

Prílohy súborov fungujú na rovnakom princípe kombinácie obdĺžnika a obsahu. Metóda AddFileAttachmentAnnotation preberá popis, cestu k súboru na vloženie, obdĺžnik pre ikonu spinky a farbu. Súbor sa uloží priamo do PDF a ikona slúži ako prvok, pomocou ktorého ho čitateľ môže extrahovať.

Ako sa anotácie líšia od polí AcroForm

Zámenou, ktorá vývojárov berie najviac času, je zaobchádzanie s anotáciou, akoby to bolo pole formulára. Obe sa síce pripájajú k stránke cez pole /Annots a pole formulára je v skutočnosti špeciálnym podtypom anotácie (widget), vďaka čomu vyzerajú príbuzne. Nie sú však zameniteľné. Pole formulára uchováva hodnotu, má svoj názov, zúčastňuje sa na poradí tabulátora, môže sa odoslať, vynulovať alebo skriptovať; tieto objekty vytvárate volaniami AddTextField, AddCheckBox a AddPushButton, nie volaniami anotácií opísanými na tejto stránke. Pripomienková anotácia obsahuje len komentár alebo tvar, nemá žiadnu hodnotu na odoslanie a je nesprávnym nástrojom vo chvíli, keď potrebujete získať vstup od používateľa.

Praktický test je jednoduchý. Ak má používateľ niečo napísať, vybrať alebo na niečo kliknúť a dokument si má túto voľbu zapamätať, potrebujete pole AcroForm. Ak pridávate poznámku, označujete oblasť alebo pečiatkujete stav, ktorý sa prenáša so súborom, ale nepredstavuje štruktúrované dáta, potrebujete anotáciu. Ich zámena vedie k dokumentom, ktoré vyzerajú správne, ale správajú sa chybne: napríklad „pole“, ktoré nikto nemôže vyplniť, alebo komentár, ktorý zmizne pri resetovaní formulára. Interaktívna stránka s typmi polí, validáciou a akciami pri odosielaní je samostatnou témou, ktorej sa venuje návod Polia a akcie AcroForm v Delphi.

Skladanie stránky dohromady

Jednotlivé časti sa skladajú rovnakým spôsobom ako vo zvyšku HotPDF. Nastavíte vlastnosti dokumentu, zavoláte BeginDoc, vykreslíte požadovaný obsah stránky pomocou textových a grafických príkazov, navrch pridáte anotácie a dokument uzavriete pomocou EndDoc. Anotácie sa viažu na CurrentPage, takže po volaní AddPage skončia na novej stránke. Poznámka určená pre prvú stránku sa tak po zalomení stránky potichu objaví na druhej.

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;

Užitočný návyk na záver: ak vygenerovaný výstup nevyzerá správne, otvorte súbor vo viacerých prehliadačoch skôr, ako usúdite, že kód je chybný. Pečiatky a menej bežné ikony poznámok bývajú najčastejším problémom. Keďže anotácia je skôr požiadavkou pre čítačku než priamo vykreslenými pixelmi, rozdiel v zobrazení medzi Acrobatom a jednoduchým webovým prehliadačom je často prejavom správnego fungovania špecifikácie, nie chybou vo vašom kóde.

Anotačné volania opísané v tomto článku sú súčasťou knižnice HotPDF Component pre Delphi a C++Builder.