PDF anotacije v Delphiju s HotPDF: Vrste in pravokotniki

Anotacija ni vsebina strani. Ko kličete TextOut ali narišete pravokotnik, oznake postanejo del toka vsebine strani, vgrajene v bajte, ki jih izriše izrisovalnik. Anotacija je ločen slovar, ki je pritrjen na stran prek njenega polja /Annots, z lastnim pravokotnikom, lastnim videzom in lastnim življenjskim ciklom. Bralnik jo lahko odpre, premakne, skrije ali odstrani ne da bi se dotaknil enega samega glifa na podkladni strani. Ta ločitev je celoten razlog za obstoj anotacij in hkrati vir dveh stvari, ki sprva presenečajo: kje pristane anotacija in kako izgleda, ko jo dobi določen pregledovalnik

HotPDF izpostavlja podtipe anotacij ISO 32000 prek družine klicev AddXxxAnnotation na objektu strani. Vsi imajo enako obliko: pravokotnik, ki pritrdi anotacijo na stran v prostoru uporabnika PDF, neko koristno vsebino (besedilo, ime štampiljke, par točk) in barvo. Pravilno nastavite pravokotnik in večina dela je opravljena. Preostalo je vedeti, kateri podtipi nosijo lasten videz in kateri se opirajo na pregledovalnik, da jih nariše

Pravokotnik je anotacija, ne besedilo

Vsak klic anotacije sprejme TRect, in ta pravokotnik pomeni nekaj drugega od koordinat, ki jih posredujete TextOut. Za besedilno opombo je to klikabilno vroče področje - majhna regija, kjer sedi ikona opombe in kjer klik odpre komentar. Za kvadrat ali polje prostega besedila je to vidni obseg oznake. Za štampiljko je to okno, v katerega se skalira umetnina štampiljke. Številke so točke v prostoru uporabnika PDF, merjene od levega spodnjega kota strani z Y, ki narašča navzgor - enaka konvencija, ki jo uporablja preostali del HotPDF

Besedilna opomba je najlažji podtip. Podate ji telo besedila, pravokotnik za ikono, zastavico za privzeto odprtost, ime ikone in barvo

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

Pravokotnik je tukaj namerno majhen - okrog dvajset točk na vsaki strani - ker je besedilna opomba do klika le ikona. Naredite pravokotnik velik in ne dobite velike opombe; dobite preveliko klikno tarčo z ikono, pritrjeno na en kot. Zastavica Open nadzoruje, ali je pojavno okno vidno ob nalaganju dokumenta. Nastavite peščico opomb na True in se kopičijo ena nad drugo in nad vsebino, zato to rezervirajte za eno opombo, ki jo bralec dejansko želi takoj videti

Ime ikone prihaja iz THPDFTextAnnotationType, ki se preslika na standardne ikone opomb: taComment, taKey, taNote, taHelp, taParagraph, taNewParagraph in taInsert. Ikona je edina stvar, ki jo vrsta spremeni. Ne spremeni vedenja in vredno je vedeti, da ne vsak pregledovalnik nariše vseh sedem; varni, ki delujejo pri starih in novih bralnikih, so taComment, taNote in taHelp

Prosto besedilo piše na stran, a ostane anotacija

Anotacija prostega besedila izgleda kot vsebina, ker je besedilo vidno brez klika in sedi v svojem pravokotniku kot napis. Še vedno je anotacija z vsemi implikacijami ločljivosti - kar je točno tisto, kar želite za žig pregleda ali oznako osnutka, ki bi jo moral nekdo moči pozneje odstraniti. Podpis zamenja ikono in zastavico za odprtost z vrednostjo poravnave

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

Tukaj je pravokotnik bolj pomemben kot pri besedilni opombi, ker se besedilo prelomi in poravna znotraj njega. Naredite okno prekratko in besedilo bo odrezano pri spodnjem robu; premajhno in bo prelomljeno na mestih, ki jih niste nameravali. Poravnava prihaja iz THPDFFreeTextAnnotationJust in ima le tri vrednosti. Ker je prosto besedilo oznakovna anotacija, jo lahko bralnik v urejevalniku izbere, premakne ali izbriše kot enoto - to je razlika, ki odloči, ali posežete po prostem besedilu ali besede preprosto narišete z TextOut. Če mora biti oznaka trajna, jo narišite. Če je uredniška in je namenjena odstranitvi, naredite anotacijo

Geometrijske oznake in črtne oznake za kazanje na stvari

Kvadrati, krogi in črte so oznake, ki jih uporabljate za kazanje na regijo namesto njenega opisovanja z besedami. AddCircleSquareAnnotation pokriva dve kvadratni obliki prek THPDFCSAnnotationType vrednosti csCircle ali csSquare, pri čemer pravokotnik podaja meje oblike

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

Opazite, da anotacija črte prekinja vzorec pravokotnika: sprejme dva zapisa THPDFCurrPoint - začetek in konec - ker je črta definirana s svojimi krajišči in ne z omejevalnim oknom. Barva nastavi črto. Če želite puščice, ima HotPDF preobremenitve AddLineAnnotation, ki sprejemajo sloge koncev črt, a navadna oblika s tremi argumenti nariše golo črto, kar je navadno tisto, kar klic chce

Podtipi oznak besedila delujejo na regiji, ki ste jo že razporedili. AddHighlightAnnotation sprejme pravokotnik, neobvezno vsebino in barvo, ki je privzeto rumena, ter zabarva področje tako, kot bi to naredilo označevalno pero. Namenjena je, da leži nad resničnim besedilom, zato mora pravokotnik ustrezati mejam besed, ki ste jih narisali - kar pomeni, da ga navadno izračunate iz enakih koordinat, ki ste jih posredovali TextOut, namesto da ugibate

Štampiljke se opirajo na pregledovalnik za izris

Anotacija štampiljke je tista, ki bo najverjetneje izgledala drugače v enem bralniku kot v drugem, in razlog je vredno razumeti. AddStampAnnotation poimenuje standardno štampiljko prek THPDFStampAnnotationType, z vrednostmi kot so satApproved, satConfidential, satFinal, satDraft in satForComment

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

Ime štampiljke je zahteva. PDF definira nabor standardnih imen štampiljk, ne pa umetniških del za njimi, zato vsak pregledovalnik prihaja z lastnim izrisom "APPROVED" ali "CONFIDENTIAL", in nekateri ne narišejo ničesar za imena, ki jih ne prepoznajo. Pravokotnik nadzoruje okno, v katerega se skalira umetnina, barva pa je namig, ki ga pregledovalnik morda upošteva ali ne. Če mora štampiljka izgledati enako povsod, zanesljiva pot ni standardna štampiljka: narišite oznako sami z TextOut in klici za izrisovanje ali jo postavite kot anotacijo prostega besedila, katere videz nadzorujete. Po standardno štampiljko posežite, ko želite znani videz pregledovalnika in lahko tolerira razlike

Priponke sledijo enaki obliki pravokotnika in koristne vsebine. AddFileAttachmentAnnotation sprejme opis, pot datoteke za vgraditev, pravokotnik za ikono sponke in barvo. Datoteka potuje znotraj PDF, ikona pa je ročaj, ki ga bralnik uporabi za ekstrakcijo

Kako se anotacije razlikujejo od polj AcroForm

Zmeda, ki vzame največ časa, je obravnavanje anotacije kot obrazčnega polja. Oba sta pritrjena na stran prek /Annots, obrazčno polje pa je dejansko poseben podtip anotacije (gradnik) - zato se zdita sorodna. Nista zamenljiva. Obrazčno polje hrani vrednost, ima ime, sodeluje v vrstnem redu tabulatorja in se ga da oddati, ponastaviti ali skriptirati; takšna ustvarite s klici AddTextField, AddCheckBox in AddPushButton, ne s klici anotacij na tej strani. Oznakovna anotacija hrani komentar ali obliko, nima vrednosti za oddajo in je napačno orodje v trenutku, ko morate zbirati vhod

Praktični preizkus je preprost. Če naj bi uporabnik tipkal, izbiral ali klikal in dokument to pomniti, želite polje AcroForm. Če pustite opombo, označujete regijo ali žigate status, ki potuje z datoteko, a ni podatek, želite anotacijo. Njihovo mešanje ustvari dokumente, ki izgledajo pravilno in se obnašajo napačno: "polje", ki ga nihče ne more izpolniti, ali komentar, ki izgine pri ponastavitvi obrazca. Interaktivna stran z vrstami polj, preverjanjem veljavnosti in dejanji oddaje je lastna tema, obravnavana v vodičem po poljih in dejanjih AcroForm

Sestavljanje strani

Deli se sestavljajo tako, kot preostali del HotPDF. Nastavite lastnosti dokumenta, pokličite BeginDoc, narišite katero koli vsebino strani s klici za besedilo in grafiko, dodajte anotacije na vrhu in zaključite z EndDoc. Anotacije se pritrdijo na CurrentPage, zato po AddPage pristanejo na novi strani - in opomba, namenjena strani ena, bo tiho prikazana na strani dve, če jo dodate po prelomu

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;

Zadnji refleks, ki ga je vredno vzgojiti, ko izpis izgleda napačno: odprite datoteko v več kot enem pregledovalniku, preden se odločite, da je koda pokvarjena. Štampiljke in redkejše ikone opomb so navadni krivci, in ker je anotacija zahteva bralniku in ne naslikani piksli, je razlika med Acrobatom in lahkim pregledovalnikom pogosto specifikacija v delovanju in ne napaka v vašem klicu

Klici anotacij, prikazani tukaj, so del komponente HotPDF za Delphi in C++Builder