HotPDF eksporterer og importerer PDF-merknader (annotations) som XFDF via to funksjoner som opererer på det for øyeblikket innlastede dokumentet: ExportLoadedAnnotationsToXFDF og ImportLoadedAnnotationsFromXFDF. XFDF er XML-formatet for utveksling av merknader standardisert som ISO 19444-1, og dette paret lar et Delphi- eller C++Builder-program overlevere kommentarer til Acrobat eller et tredjeparts evalueringsverktøy og ta de markerte resultatene tilbake, alt uten å skrive om sideinnholdet merknadene ligger på
Se for deg de to retningene dette løser. En evaluator åpner din genererte rapport i Acrobat, legger til en rød pil på en feilplassert figur, tegner en sirkel rundt en feil totalsum og skriver et notat i margen, for deretter å eksportere kommentarene to en liten XFDF-fil. Eller omvendt: Programmet ditt produserer markeringene selv, og du må sende dem til noen som ikke bruker HotPDF. Uansett overføres merknadene som XML som begge parter forstår, og PDF-sidene forblir uendret byte-for-byte
Hva er forskjellen mellom FDF og XFDF?
Hvordan eksporterer du PDF-merknader som XFDF i Delphi?
HotPDF eksporterer merknader ved å gå gjennom hver side i det innlastede dokumentet, opprette ett XFDF-element for hver støttede merknad, og returnere antallet merknader som ble skrevet. Last inn PDF-en først, og kall deretter ExportLoadedAnnotationsToXFDF med en mål-filbane. Heltallsresultatet er antallet serialiserte merknader; et resultat på null eller mindre betyr at ingenting ble eksportert og ingen fil ble skrevet, noe som er signalet på at dokumentet ikke inneholdt noen merknader av en støttet undertype
var
Pdf: THotPDF;
Written: Integer;
begin
Pdf := THotPDF.Create(nil);
try
if Pdf.LoadFromFile('report-reviewed.pdf', '') > 0 then
begin
// Write one XFDF element per supported annotation on every page
Written := Pdf.ExportLoadedAnnotationsToXFDF('comments.xfdf');
if Written <= 0 then
ShowMessage('No supported annotations were found');
end;
finally
Pdf.Free;
end;
end;XFDF-en som kommer ut er ren, lesbar XML. HotPDF skriver en <xfdf>-rot i ISO 19444-1-navnerommet, en <annots>-beholder, og ett underelement per merknad med dens nullbaserte sideindeks, farge og geometri som attributter eller underordnede elementer. En linje med et gult fyll og en åpen pilspiss, som ligger ved siden av et fylt polygon, serialiseres slik
<?xml version="1.0" encoding="UTF-8"?>
<xfdf xmlns="http://ns.adobe.com/xfdf/">
<annots>
<line page="0" start="72,700" end="220,700"
color="#FF0000" interior-color="#FFFF00"
head="OpenArrow" tail="None">
<contents-richtext>Baseline looks off</contents-richtext>
</line>
<polygon page="0" color="#0000FF" interior-color="#CCE5FF">
<vertices>72,120;180,120;180,200;72,200</vertices>
</polygon>
</annots>
</xfdf>Hvordan undertyper av merknader kartlegges til XFDF-elementer
Hver merknadsundertype kartlegges til et spesifikt ISO 19444-1-element med sin egen geometrikonvensjon, og HotPDF følger disse strukturene i stedet for å finne opp sine egne. Linjemerknader har et start- og et end-attributt som inneholder de to koordinatparene for endepunktene, hentet direkte fra merknadens L-tabell, mens LE-linjeendestilene blir til head- og tail-attributter. Polygon- og polylinjemerknader flytter punktlisten sin inn i et underelement <vertices> som semikolonseparerte x,y-par, ikke et attributt, fordi et leserprogram som forventer underelementet i det stille vil forkaste punkter som er gjemt andre steder. Blekkmerknader (ink annotations), som kan inneholde flere separate strøk, nester et <inklist>-element med ett <gesture>-underelement per strøk, slik at en signatur med flere strøk overlever reisen som distinkte bevegelser i stedet for én sammenslått klump (blob)
Formatering av rik tekst, farge og kantlinjestiler overlever sammen med geometrien. Et notats brødtekst i rik tekst skrives som et <contents-richtext>-underelement; det innvendige fyllet som PDF lagrer i IC-tabellen (malingen inni en sirkel, firkant, polygon eller linjepil, samt fyllet i en sladdingsboks) overføres som et interior-color-attributt i #RRGGBB-form; og kantlinjebredde, stiplet mønster (dash pattern) og en sky-lignende (cloudy) kantlinjeeffekt kartlegges til attributtene width, dashes, style og intensity, slik at en sky-konturert bildetekst (callout) fortsatt leses som sky-konturert i den andre enden. HotPDF bevarer også popup-vinduet som er knyttet til en markeringsmerknad (markup annotation), ved å importere popup-underelementets geometri og dets åpne eller lukkede tilstand inn i merknadens Popup-ordbok, og den overfører tekstmerknadens åpnings- og vurderingstilstander, slik at et vurdert dokument ikke bare beholder formene sine, men også arbeidsflyt-metadataene evaluatorene er avhengige av
Importere XFDF tilbake til et innlastet dokument
HotPDF importerer XFDF ved å analysere XML-koden, opprette en ny merknad for hvert element via NewLoadedAnnotation, koble den til siden elementet navngir, og returnere hvor mange merknader den la til. Arbeidsflyten er symmetrisk med eksport: last inn base-PDF-en, kall ImportLoadedAnnotationsFromXFDF med evaluatorens fil, og lagre deretter det innlastede dokumentet for å bevare de nye markeringene. Hvis filen mangler eller XML-koden ikke kan analyseres, returnerer funksjonen null og det innlastede dokumentet forblir uendret
var
Pdf: THotPDF;
Added: Integer;
begin
Pdf := THotPDF.Create(nil);
try
if Pdf.LoadFromFile('report.pdf', '') > 0 then
begin
Added := Pdf.ImportLoadedAnnotationsFromXFDF('comments.xfdf');
if Added > 0 then
Pdf.SaveLoadedDocument('report-annotated.pdf');
end;
finally
Pdf.Free;
end;
end;Siden hvert XFDF-element har sin egen sideindeks, vil merknadene havne på sidene de opprinnelig ble skrevet på, selv om du importerer flere filer etter hverandre. Dette gjør det trygt å samle kommentarer fra mer enn én evaluator på samme innlastede dokument før du lagrer. Eksempelet nedenfor slår sammen kommentarer fra to evaluatorer til én enkelt fil. For å opprette og redigere merknadsobjekter direkte i kode i stedet for å utveksle dem via filer, se hvordan HotPDF oppretter og redigerer PDF-merknadsobjekter direkte i Delphi
var
Pdf: THotPDF;
Total, I: Integer;
Files: array[0..1] of string;
begin
Files[0] := 'alice-comments.xfdf';
Files[1] := 'bob-comments.xfdf';
Pdf := THotPDF.Create(nil);
try
if Pdf.LoadFromFile('master.pdf', '') > 0 then
begin
Total := 0;
for I := Low(Files) to High(Files) do
Inc(Total, Pdf.ImportLoadedAnnotationsFromXFDF(Files[I]));
if Total > 0 then
Pdf.SaveLoadedDocument('master-merged.pdf');
end;
finally
Pdf.Free;
end;
end;Hva som overføres rent frem og tilbake, og hva som ikke gjør det
HotPDF overfører de merknadsundertypene som ISO 19444-1 har støtte for, og hopper bevisst over resten i stedet for å sende ut noe et leserprogram kan feiltolke. Det støttede settet dekker markeringstypene som dominerer reelt evalueringsarbeid: tekstnotater, fritext, linje, firkant, sirkel, polygon, polylinje, de fire tekstmarkeringstypene (utheving, understreking, gjennomstreking og bølgestrek), stempel, blekk og caret, pluss filvedlegg, lyd, sladding og lenke — atten undertyper totalt. En merknad med en undertype som faller utenfor denne listen blir hoppet over ved eksport, og fordi den blir hoppet over i stedet for å bli skrevet tom, vil den ikke øke antallet funksjonen returnerer
Rik tekst er den ærlige advarselen. HotPDF bevarer <contents-richtext>-kroppen slik at den formaterte teksten og det enkle innholdet blir med på reisen, men XFDF bærer en kommentars tekst- og stilmarkering, ikke en rendret utseendestrøm, slik at det mottakende programmet tegner opp popup-vinduet på nytt med sine egne skrifttyper og layout i stedet for å gjenskape HotPDFs nøyaktige piksler. Behandle overføringen frem og tilbake som trofast mot innhold og hensikt, ikke mot skjermrendring ned til minste piksel. Hvis det formaterte innholdet ditt ligger i XFA-skjemadata i stedet for merknadsstrømmer, gjelder andre regler, og hvordan HotPDF håndterer XFA exData, rik tekst og hyperlenker dekker den separate banen
Håndteringen på tegnnivå er strengere enn den ser ut til, noe som er akkurat det du ønsker. HotPDF bruker ISO 19444-1 klausul 5.8.2 sine maskeringsregler (escaping rules) når den skriver tekst, og koder XML-signifikante tegn og kontrollbyte slik at en kommentar som inneholder et og-tegn (ampersand), en vinkelparentes eller et linjeskift produserer en velformet XML som enhver kompatibel parser godtar, og den snur de samme reglene ved import. Det er grunnen til at et notat limt inn fra et regneark, med tegnsetting og alt, kommer intakt tilbake i stedet for å korrumpere filen
Utveksling av merknader er bare en del av hva API-et for innlastede dokumenter gjør, og det fungerer sammen med resten: importer en evaluators XFDF, juster sidene eller rediger dokumentets metadata, flat ut eller endre filens tillatelser, og eksporter deretter en ny XFDF for neste runde. Alt dette leveres i standard HotPDF Component for Delphi og C++Builder, der referansen dokumenterer den fulle dekningen av merknadsundertyper og de tilhørende skjemadata-XFDF-funksjonene