PDF megjegyzések importálása és exportálása XFDF formátumban Delphiben

A HotPDF a PDF megjegyzéseket (annotations) a jelenleg betöltött dokumentumon működő két függvényen keresztül exportálja és importálja XFDF-ként: ezek az ExportLoadedAnnotationsToXFDF és a ImportLoadedAnnotationsFromXFDF. Az XFDF az ISO 19444-1 szabvány szerint szabványosított XML alapú megjegyzéscsere-formátum, és ez a pár lehetővé teszi egy Delphi vagy C++Builder program számára, hogy átadja megjegyzéseit az Acrobatnak vagy egy harmadik fél véleményező eszközének, majd visszakapja a megjelölt eredményeket, anélkül, hogy átírná az oldaltartalmat, amelyen a megjegyzések ülnek

Képzelje el a két irányt, amelyet ez megold. Egy véleményező megnyitja a generált jelentést az Acrobatban, elhelyez egy piros nyilat egy hibásan igazított ábrán, bekarikáz egy hibás végösszeget, és beír egy jegyzetet a margóra, majd exportálja a megjegyzéseket egy kis XFDF fájlba. Vagy fordítva: a programja maga állítja elő a jelöléseket, és el kell küldenie azokat valakinek, akinek az eszköze nem a HotPDF. Mindkét esetben a megjegyzések mindkét fél által értelmezhető XML formátumban utaznak, a PDF oldalak pedig bájtól bájtra azonosak maradnak azzal, amik voltak

Mi a különbség az FDF és az XFDF között?

Az FDF és az XFDF ugyanazt a hasznos terhet hordozza két különböző szintaxisban, és a különbség abban a pillanatban számít, amikor eldönti, melyik fájlt adja át egy másik eszköznek. Az FDF a régebbi Forms Data Format (űrlapadat-formátum), amelyet maga a PDF-specifikáció határoz meg: PDF objektumszintaxist használ, így egy FDF fájl úgy néz ki, mint egy lecsupaszított PDF, és elolvasásához PDF-tudatos elemzőre van szükség. Az XFDF ugyanazon adatok XML-kifejezése, amelyet függetlenül szabványosítottak ISO 19444-1 néven, ami azt jelenti, hogy bármely platform bármely XML-könyvtára képes megnyitni, diff-elni vagy generálni. Mindkét formátum hordozhat űrlapmező-értékeket egy <fields> fában, amelyet az ISO 19444-1 szabvány 6.3-as pontja szabályoz, és megjegyzéseket egy <annots> fában; a HotPDF megosztja ezeket a felelősségeket: az űrlapadatokat az ExportLoadedFormToXFDF-en keresztül irányítja, a ExportLoadedAnnotationsToXFDF metódust pedig fenntartja az <annots> oldalnak. Ha megjegyzéseket cserél egy webszolgáltatással, egy Java véleményező szerverrel vagy egy szkripttel, az XFDF az a formátum, amely nem kényszeríti a másik oldalt PDF-elemző beágyazására

Hogyan exportálhatók a PDF megjegyzések XFDF-ként Delphiben?

A HotPDF a megjegyzéseket úgy exportálja, hogy végigmegy a betöltött dokumentum minden oldalán, minden támogatott megjegyzéshez egy XFDF elemet bocsát ki, és visszaadja a leírt megjegyzések számát. Először töltse be a PDF-et, majd hívja meg az ExportLoadedAnnotationsToXFDF metódust a célútvonallal. Az egész szám eredmény a szerializált megjegyzések száma; a nulla vagy az alatti eredmény azt jelenti, hogy semmit sem exportáltak, és nem írtak fájlt, ami azt jelzi, hogy a dokumentum nem tartalmazott támogatott altípusú megjegyzéseket

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;

Az XFDF, ami kijön, egyszerű, olvasható XML. A HotPDF egy <xfdf> gyökeret ír az ISO 19444-1 névtérben, egy <annots> konténert, és oldalak szerint egy-egy gyermekelemet a támogatott megjegyzéseknek a 0-alapú oldalindexszel, színnel és geometriával attribútumokként vagy gyermekelemekként. Egy sárga kitöltésű, nyitott nyílhegyű vonal egy kitöltött sokszög mellett így szerializálódik:

<?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>

Hogyan képeződnek le a megjegyzés-altípusok XFDF elemekre

Minden megjegyzés-altípus egy konkrét ISO 19444-1 elemre képeződik le a saját geometriai konvenciójával, és a HotPDF követi ezeket a struktúrákat ahelyett, hogy sajátot találna ki. A vonalmegjegyzések egy start és egy end attribútumot hordoznak, amelyek a két végpont koordinátapárját tartalmazzák közvetlenül a megjegyzés L tömbjéből véve, míg a LE vonalvégződési stílusok head és tail attribútumokká válnak. A sokszög (polygon) és törtvonal (polyline) megjegyzések a pontlistájukat egy <vertices> gyermekelembe helyezik pontosvesszővel elválasztott x,y párokként, nem pedig attribútumként, mivel a gyermekelemet váró olvasó csendben eldobná a máshol elrejtett pontokat. A tintarajz (ink) megjegyzések, amelyek több különálló vonást is tartalmazhatnak, egy <inklist> elemet ágyaznak be vonásonként egy-egy <gesture> gyermekelemmel, így a többvonásos aláírás különálló gesztusokként éli túl az utat, nem pedig egyetlen összevont foltként

A formázott szöveg (rich text), a szín- és a szegélystílusok túlélnek a geometria mellett. A jegyzet formázott szöveges törzse <contents-richtext> gyermekelemként íródik; a belső szín, amelyet a PDF az IC tömbben tárol – a kör, négyzet, sokszög vagy vonal nyílhegy belsejének festése és a redakciós doboz kitöltése –, interior-color attribútumként jelenik meg #RRGGBB formában; a szegélyszélesség, a szaggatott minta és a felhős szegélyhatás pedig a width, dashes, style és intensity attribútumokra képeződik le, így a felhőkörvonalas kiemelés továbbra is felhősként olvasható a túloldalon. A HotPDF megőrzi a jelölő megjegyzéshez csatolt felugró ablakot is, importálva a felugró gyermekgeometriát és annak nyitott vagy zárt állapotát a megjegyzés Popup szótárába, és hordozza a szöveges megjegyzések nyitott és ellenőrzési állapotait, így az ellenőrzött dokumentum nemcsak a formáit tartja meg, hanem a munkafolyamat metaadatait is, amelyekre a véleményezők támaszkodnak

XFDF visszahozatala a betöltött dokumentumra

A HotPDF az XML elemzésével importálja az XFDF-et, létrehozva egy friss megjegyzést minden elemhez a NewLoadedAnnotation segítségével, hozzácsatolva azt az elem által megnevezett oldalhoz, és visszaadva az általa hozzáadott megjegyzések számát. A munkafolyamat szimmetrikus az exportálással: töltse be az alap PDF-et, hívja meg az ImportLoadedAnnotationsFromXFDF metódust a véleményező fájljával, majd mentse el a betöltött dokumentumot az új jelölések megőrzéséhez. Ha a fájl hiányzik, vagy az XML nem elemezhető, a függvény nullát ad vissza, a betöltött dokumentum pedig érintetlen marad

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;

Mivel minden XFDF elem megnevezi a saját oldalindexét, a megjegyzések azokra az oldalakra kerülnek, amelyeken létrehozták őket, még akkor is, ha több fájlt importál egymás után, ami biztonságossá teszi a több véleményezőtől származó megjegyzések összegyűjtését ugyanarra a betöltött dokumentumra egyetlen mentés előtt. Az alábbi példa két véleményezőt von össze egyetlen egyesített másolatba. A megjegyzés-objektumok kódban történő felépítéséhez és szerkesztéséhez ahelyett, hogy fájlként cserélné ki őket, nézze meg, hogyan hozza létre és szerkeszti a HotPDF a PDF megjegyzés-objektumokat közvetlenül Delphiből

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;

Mi megy át tisztán az oda-vissza úton, és mi nem

A HotPDF azokat a megjegyzés-altípusokat viszi át oda-vissza, amelyeknek az ISO 19444-1 otthont ad, a többit pedig szándékosan kihagyja, ahelyett, hogy olyasmit bocsátana ki, amit az olvasó félreértene. A támogatott készlet lefedi a valós véleményezési munkát uraló jelölési típusokat: szöveges jegyzetek, szabad szöveg, vonal, négyzet, kör, sokszög, törtvonal, a négy szövegjelölési típus (kiemelés, aláhúzás, áthúzás és hullámos), bélyegző, tinta és caret, valamint fájlmelléklet, hang, redakció és link, összesen tizennyolc altípus. A listán kívül eső altípusú megjegyzéseket az exportálás figyelmen kívül hagyja, és mivel kihagyja őket ahelyett, hogy üresen írná le őket, nem növeli a függvény által visszaadott számlálót

A formázott szöveg (rich text) az őszinte figyelmeztetés. A HotPDF megőrzi a <contents-richtext> törzset, így a formázott szöveg és a sima tartalom is megteszi az utat, de az XFDF a megjegyzés szövegét és stílusjelölését hordozza, nem pedig a renderelt megjelenítési folyamatot, így a fogadó alkalmazás a saját betűtípusaival és elrendezésével rajzolja újra a felugró ablakot, ahelyett, hogy a HotPDF pontos pixeleit reprodukálná. Tekintse az oda-vissza utat a tartalomhoz és a szándékhoz hűnek, nem pedig a képernyő pixelpontos renderelésének. Ha a formázott tartalom XFA űrlapadatokban él, nem pedig megjegyzésfolyamokban, a szabályok eltérnek, és a hogyan kezeli a HotPDF az XFA exData, formázott szöveg és hiperhivatkozásokat cikk ezt a különálló útvonalat tárgyalja

A karakterszintű kezelés szigorúbb, mint amilyennek látszik, és pontosan ez az, amit szeretne. A HotPDF az ISO 19444-1 szabvány 5.8.2-es pontjának escape-elési szabályait alkalmazza a szöveg írásakor, kódolva az XML-szignifikáns karaktereket és vezérlőbájtokat, így az ampersandot, szögletes zárójelet vagy soremelést tartalmazó megjegyzés jól formázott XML-t eredményez, amelyet bármely megfelelő elemző elfogad, és ugyanezeket a szabályokat fordítja meg importáláskor. Ezért tér vissza épen egy táblázatból másolt jegyzet, az összes írásjellel együtt, ahelyett, hogy megrontaná a fájlt

A megjegyzések cseréje csak egy része annak, amit a betöltött dokumentum API végez, és összehangolható a többivel: importálhatja a véleményező XFDF-jét, módosíthatja az oldalakat vagy szerkesztheti a dokumentum metaadatait, lapíthatja vagy újraengedélyezheti a fájlt, majd exportálhat egy friss XFDF-et a következő körhöz. Mindez megtalálható a standard HotPDF Component-ben Delphihez és C++Builderhez, amelynek referenciája dokumentálja a teljes megjegyzés-altípus lefedettséget és a kísérő űrlapadat-XFDF függvényeket