PDF anotace (Annotations) v Delphi s HotPDF: Typy a obdélníky (Rects)

Anotace není obsah stránky. Když zavoláte TextOut nebo nakreslíte obdélník, tyto značky se stanou součástí datového toku obsahu stránky, zapečené do bajtů, které renderer vykreslí. Anotace je samostatný slovník, který visí na stránce prostřednictvím jejího pole /Annots, s vlastním obdélníkem, vlastním vzhledem a vlastním životním cyklem. Čtečka jej může otevřít, přesunout, skrýt nebo odstranit, aniž by se dotkla jediného glyfu podkladové stránky. Tato oddělenost je celý důvod, proč anotace existují, a je také zdrojem dvou věcí, které čtenáře nejvíc překvapí: kam anotace přistane a jak vypadá poté, co se jí zmocní konkrétní prohlížeč

HotPDF zpřístupňuje podtypy anotací dle ISO 32000 prostřednictvím rodiny volání AddXxxAnnotation na objektu stránky. Všechny sdílejí stejný tvar: obdélník, který ukotví anotaci na stránce v uživatelském prostoru PDF, nějaký obsah (text, název razítka, dvojice bodů) a barvu. Nastavíte-li obdélník správně, je hotová většina práce. Zbytek je vědět, které podtypy nesou vlastní vzhled a které se spoléhají na to, že je nakreslí prohlížeč

Obdélník je anotace, ne text

Každé volání anotace přijímá TRect, a tento obdélník znamená něco jiného než souřadnice, které předáváte funkci TextOut. U textové poznámky je to klikatelná aktivní oblast, malá plocha, kde sedí ikona poznámky a kde klik otevře komentář. U čtverce nebo pole volného textu je to viditelný rozsah označení. U razítka je to box, do kterého se grafika razítka škáluje. Čísla jsou body v uživatelském prostoru PDF, měřené od levého dolního rohu stránky s Y rostoucím nahoru, stejná konvence, jakou používá zbytek HotPDF

Textová poznámka je nejlehčí podtyp. Zadáte jí text těla, obdélník pro ikonu, příznak, zda se má standardně otevírat, název ikony a barvu

Pdf.CurrentPage.AddTextAnnotation(
  'Reviewer: confirm the totals on this line before sign-off.',
  Rect(120, 700, 140, 720),   // aktivní oblast ikony, čtverec ~20 bodů
  False,                      // zavřeno, dokud čtenář neklikne
  taComment,                  // ikona bubliny
  clBlue);

Obdélník je zde záměrně malý, kolem dvaceti bodů na stranu, protože textová poznámka je jen ikona, dokud na ni někdo neklikne. Uděláte-li obdélník velký, nezískáte velkou poznámku; získáte předimenzovaný klikací cíl s ikonou přišpendlenou do jednoho rohu. Příznak Open řídí, zda je vyskakovací okno zobrazené při načtení dokumentu. Nastavíte-li True u hrstky poznámek, naskládají se na sebe a na obsah, takže to vyhraďte pro tu jednu poznámku, kterou opravdu chcete, aby čtenář uviděl okamžitě

Název ikony pochází z THPDFTextAnnotationType, který se mapuje na standardní ikony poznámek: taComment, taKey, taNote, taHelp, taParagraph, taNewParagraph a taInsert. Ikona je jediné, co typ mění. Neovlivňuje chování, a stojí za to vědět, že ne každý prohlížeč vykreslí všech sedm; bezpečné napříč staršími i novějšími čtečkami jsou taComment, taNote a taHelp

Volný text píše na stránku, ale zůstává anotací

Anotace volného textu vypadá jako obsah, protože text je viditelný bez kliknutí, sedí ve svém obdélníku jako popisek. Přesto je to stále anotace, se vší oddělitelností, kterou to implikuje, což je přesně to, co chcete pro razítko posouzení nebo štítek konceptu, který by měl někdo později moci odstranit. Signatura vymění ikonu a příznak otevření za hodnotu zarovnání

Pdf.CurrentPage.AddFreeTextAnnotation(
  'DRAFT - not for distribution',
  Rect(200, 210, 400, 235),   // box, do kterého se text vkládá
  ftCenter,                   // ftLeftJust / ftCenter / ftRightJust
  clRed);

Zde na obdélníku záleží víc než u textové poznámky, protože se v něm text zalamuje a zarovnává. Uděláte-li box příliš nízký, text se dole ořízne; příliš úzký, a zalomí se na místech, která jste nezamýšleli. Zarovnání pochází z THPDFFreeTextAnnotationJust a má jen tři hodnoty. Protože volný text je anotace typu markup, čtenář, který otevře soubor v editoru, jej může vybrat, přesunout nebo smazat jako celek, a to je rozdíl, který rozhoduje, zda sáhnete po volném textu, nebo jen nakreslíte slova pomocí TextOut. Pokud má být štítek trvalý, nakreslete jej. Pokud je editorský a má se později odstranit, udělejte z něj anotaci

Geometrická a čárová označení pro ukazování na věci

Čtverce, kruhy a čáry jsou označení, které použijete k ukázání na oblast namísto jejího popsání slovy. AddCircleSquareAnnotation pokrývá oba tvary boxů prostřednictvím THPDFCSAnnotationType hodnoty csCircle nebo csSquare, přičemž obdélník udává hranice tvaru

// Box nakreslený kolem obrázku, který vyžaduje pozornost
Pdf.CurrentPage.AddCircleSquareAnnotation(
  'Check this region against the source data',
  Rect(50, 300, 120, 360),
  csSquare,
  clGreen);

// Čára, zadaná dvěma body namísto obdélníku
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šimněte si, že čárová anotace láme vzorec s obdélníkem: přijímá dva záznamy THPDFCurrPoint, počátek a konec, protože čára je definována svými koncovými body, ne ohraničujícím boxem. Barva nastavuje obrys. Pokud chcete šipky, HotPDF má přetížení AddLineAnnotation, která přijímají styly konců čáry, ale prostá tříargumentová forma nakreslí holou čáru, což je obvykle to, co popiska chce

Podtypy textového označení pracují na oblasti, kterou jste už rozvrhli. AddHighlightAnnotation přijímá obdélník, volitelný obsah a barvu, která standardně žloutne, a obarví oblast tak, jak by to udělal zvýrazňovač. Má sedět nad skutečným textem, takže obdélník by měl odpovídat hranicím slov, která jste nakreslili, což znamená, že jej obvykle vypočítáte ze stejných souřadnic, které jste předali funkci TextOut, místo abyste je odhadovali

Razítka závisí na tom, že je vykreslí prohlížeč

Anotace razítka je ta, u které je nejpravděpodobnější, že bude vypadat jinak v jedné čtečce než v druhé, a důvod stojí za pochopení. AddStampAnnotation pojmenuje standardní razítko pomocí THPDFStampAnnotationType, s hodnotami jako satApproved, satConfidential, satFinal, satDraft a satForComment

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

Název razítka je žádost. PDF definuje sadu standardních názvů razítek, ale ne grafiku za nimi, takže každý prohlížeč dodává vlastní ztvárnění „APPROVED“ nebo „CONFIDENTIAL“, a některé pro názvy, které nerozpoznají, nevykreslí vůbec nic. Obdélník řídí box, do kterého se grafika škáluje, a barva je nápověda, kterou prohlížeč může, ale nemusí respektovat. Musí-li razítko vypadat identicky všude, spolehlivou cestou vůbec není standardní razítko: nakreslete značku sami pomocí TextOut a kreslicích volání, nebo ji umístěte jako anotaci volného textu, jejíž vzhled kontrolujete. Sáhněte po standardním razítku, když chcete známý vzhled prohlížeče a snesete tu odchylku

Přílohy souborů se řídí stejným vzorcem obdélník-plus-obsah. AddFileAttachmentAnnotation přijímá popis, cestu k souboru pro vložení, obdélník pro ikonu kancelářské sponky a barvu. Soubor cestuje uvnitř PDF a ikona je úchyt, kterým jej čtenář extrahuje

Jak se anotace liší od polí AcroForm

Záměna, která stojí nejvíc času, je zacházet s anotací, jako by to bylo pole formuláře. Obojí se připojuje ke stránce prostřednictvím /Annots, a pole formuláře je ve skutečnosti zvláštní podtyp anotace (widget), a proto vypadají příbuzně. Nejsou zaměnitelné. Pole formuláře drží hodnotu, má název, účastní se pořadí tabulace a lze jej odeslat, resetovat nebo skriptovat; vytváříte je voláními AddTextField, AddCheckBox a AddPushButton, ne anotačními voláními z této stránky. Anotace typu markup drží komentář nebo tvar, nemá žádnou hodnotu k odeslání a je nesprávným nástrojem ve chvíli, kdy potřebujete sbírat vstup

Praktický test je jednoduchý. Pokud má uživatel psát, vybírat nebo klikat a dokument si to má pamatovat, chcete pole AcroForm. Pokud zanecháváte poznámku, označujete oblast nebo razítkujete stav, který cestuje se souborem, ale není to data, chcete anotaci. Jejich záměna produkuje dokumenty, které vypadají správně, ale chovají se špatně: „pole“, které nikdo nemůže vyplnit, nebo komentář, který zmizí při resetu formuláře. Interaktivní stránka věci, s typy polí, validací a odesílacími akcemi, je samostatné téma pokryté v průvodci poli a akcemi AcroForm

Sestavení stránky dohromady

Jednotlivé části se skládají stejně jako zbytek HotPDF. Nastavte vlastnosti dokumentu, zavolejte BeginDoc, nakreslete jakýkoli obsah stránky, který potřebujete, pomocí textových a grafických volání, přidejte anotace navrch a uzavřete pomocí EndDoc. Anotace se připojují k CurrentPage, takže po AddPage přistanou na nové stránce, a poznámka, kterou jste mysleli pro první stránku, se tiše objeví na druhé stránce, pokud ji přidáte až po zlomu

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;

Poslední reflex, který stojí za vypěstování, když výstup vypadá špatně: otevřete soubor ve více než jednom prohlížeči, než usoudíte, že je kód rozbitý. Obvyklými viníky jsou razítka a vzácnější ikony poznámek, a protože anotace je žádost čtečce, ne vykreslené pixely, rozdíl mezi Acrobatem a odlehčeným prohlížečem je často specifikace fungující tak, jak byla navržena, ne chyba ve vašem volání

Anotační volání ukázaná zde jsou součástí HotPDF Delphi komponenty pro Delphi a C++Builder