PDF-Anmerkungen in Delphi mit HotPDF: Typen und Rechtecke

Eine Anmerkung ist kein Seiteninhalt. Wenn Sie TextOut aufrufen oder ein Rechteck zeichnen, werden die Markierungen Teil des Inhaltsstroms der Seite, fest in die Bytes eingebrannt, die ein Renderer malt. Eine Anmerkung ist ein separates Wörterbuch, das über sein /Annots-Array an der Seite hängt, mit einem eigenen Rechteck, einem eigenen Erscheinungsbild und einem eigenen Lebenszyklus. Ein Leser kann sie öffnen, verschieben, ausblenden oder entfernen, ohne eine einzige Glyphe der zugrunde liegenden Seite zu berühren. Diese Trennung ist der einzige Grund für die Existenz von Anmerkungen, und sie ist auch die Quelle für die beiden Dinge, die die Leute anfangs überraschen: wo eine Anmerkung landet und wie sie aussieht, sobald ein bestimmter Viewer sie in die Hände bekommt

HotPDF stellt die Anmerkungs-Untertypen von ISO 32000 über eine Familie von AddXxxAnnotation-Aufrufen auf dem Seitenobjekt zur Verfügung. Sie alle haben dieselbe Form: ein Rechteck, das die Anmerkung auf der Seite im PDF-Benutzerraum fixiert, eine gewisse Nutzlast (Text, ein Stempelname, ein Punktepaar) und eine Farbe. Wenn Sie das Rechteck richtig hinbekommen, ist der Großteil der Arbeit erledigt. Der Rest ist das Wissen, welche Untertypen ihr eigenes Erscheinungsbild mitbringen und welche sich auf den Viewer stützen, um sie zu zeichnen

Das Rechteck ist die Anmerkung, nicht der Text

Jeder Anmerkungsaufruf nimmt ein TRect an, und dieses Rechteck bedeutet etwas anderes als die Koordinaten, die Sie an TextOut übergeben. Bei einer Textnotiz ist es der anklickbare Hotspot, der kleine Bereich, in dem das Notizsymbol sitzt und in dem ein Klick den Kommentar öffnet. Bei einem Quadrat oder einem Freitextfeld ist es die sichtbare Ausdehnung der Markierung. Für einen Stempel ist es der Kasten, in den das Stempelbild skaliert wird. Die Zahlen sind Punkte im PDF-Benutzerraum, gemessen von der unteren linken Ecke der Seite, wobei Y nach oben zunimmt – dieselbe Konvention, die der Rest von HotPDF verwendet

Eine Textnotiz ist der leichteste Untertyp. Sie geben ihm den Haupttext, ein Rechteck für das Symbol, ein Flag, ob er standardmäßig geöffnet wird, einen Symbolnamen und eine Farbe

var
  Rect: TRect;
begin
  Rect := Bounds(72, 600, 24, 24);
  Pdf.CurrentPage.AddTextAnnotation('Please verify this figure.',
    Rect, False, taComment, clBlue);

Das Rechteck hier ist bewusst klein, etwa zwanzig Punkte pro Seite, denn eine Textnotiz ist nur ein Symbol, bis jemand darauf klickt. Machen Sie das Rechteck groß und Sie erhalten keine große Notiz; Sie erhalten ein übergroßes Klickziel mit dem Symbol in einer Ecke angeheftet. Das Open-Flag steuert, ob das Popup beim Laden des Dokuments angezeigt wird. Wenn Sie eine Handvoll Notizen auf True setzen, stapeln sie sich übereinander und über den Inhalt. Reservieren Sie dies also für die eine Notiz, die der Leser tatsächlich sofort sehen soll

Der Symbolname stammt von THPDFTextAnnotationType, was auf die Standard-Notizsymbole abbildet: taComment, taKey, taNote, taHelp, taParagraph, taNewParagraph und taInsert. Das Symbol ist das einzige, was der Typ ändert. Er ändert das Verhalten nicht, und es ist gut zu wissen, dass nicht jeder Viewer alle sieben zeichnet; die sicheren für alte und neue Leser sind taComment, taNote und taHelp

Freier Text schreibt auf die Seite, bleibt aber eine Anmerkung

Eine Freitextanmerkung sieht aus wie Inhalt, da der Text ohne Klick sichtbar ist und wie eine Bildunterschrift in seinem Rechteck sitzt. Es handelt sich immer noch um eine Anmerkung mit all der damit verbundenen Trennbarkeit, was genau das ist, was Sie für einen Überprüfungsstempel oder ein Entwurfsetikett wünschen, das jemand später entfernen können sollte. Die Signatur tauscht das Symbol und das Öffnen-Flag gegen einen Ausrichtungswert aus

  Rect := Bounds(300, 600, 150, 40);
  Pdf.CurrentPage.AddFreeTextAnnotation('Draft for internal review only',
    Rect, tjCenter, clRed);

Hier spielt das Rechteck eine größere Rolle als bei einer Textnotiz, da der Text darin umbrochen und ausgerichtet wird. Ist das Feld zu kurz, wird der Text an der Unterkante abgeschnitten; ist es zu schmal, wird er an Stellen umbrochen, die Sie nicht beabsichtigt haben. Die Ausrichtung kommt von THPDFFreeTextAnnotationJust und hat nur die drei Werte. Da es sich bei freiem Text um eine Markup-Anmerkung handelt, kann ein Leser, der die Datei in einem Editor öffnet, sie als Einheit auswählen, verschieben oder löschen, was den Unterschied ausmacht, der entscheidet, ob Sie zu freiem Text greifen oder die Wörter einfach mit TextOut zeichnen. Wenn das Etikett dauerhaft sein muss, zeichnen Sie es. Wenn es redaktionell ist und wieder entfernt werden soll, machen Sie es zu einer Anmerkung

Geometrische und Linienmarkierungen zum Zeigen auf Dinge

Quadrate, Kreise und Linien sind Markierungen, mit denen Sie auf einen Bereich hinweisen, anstatt ihn in Worten zu beschreiben. AddCircleSquareAnnotation deckt die beiden Kastenformen über einen THPDFCSAnnotationType von csCircle oder csSquare ab, wobei das Rechteck die Grenzen der Form angibt

  Rect := Bounds(72, 450, 200, 100);
  Pdf.CurrentPage.AddCircleSquareAnnotation(csSquare, '', Rect, clMaroon);

Beachten Sie, dass die Linienanmerkung das Rechteck-Muster bricht: Sie nimmt zwei THPDFCurrPoint-Records auf, einen Anfang und ein Ende, da eine Linie durch ihre Endpunkte und nicht durch einen Begrenzungsrahmen definiert ist. Die Farbe bestimmt die Kontur. Wenn Sie Pfeilspitzen wünschen, verfügt HotPDF über Überladungen von AddLineAnnotation, die Zeilenendstile akzeptieren, aber die einfache Form mit drei Argumenten zeichnet eine nackte Linie, was bei einer Callout-Box normalerweise gewünscht ist

var
  P1, P2: THPDFCurrPoint;
begin
  P1.X := 72; P1.Y := 450;
  P2.X := 272; P2.Y := 550;
  Pdf.CurrentPage.AddLineAnnotation('', P1, P2, clGreen);

Text-Markup-Untertypen arbeiten mit einem Bereich, den Sie bereits angelegt haben. AddHighlightAnnotation verwendet ein Rechteck, optionale Inhalte und eine Farbe, die standardmäßig gelb ist, und tönt den Bereich wie ein Textmarker. Es ist so gedacht, dass es über echtem Text liegt, sodass das Rechteck den Grenzen der von Ihnen gezeichneten Wörter entsprechen sollte, was bedeutet, dass Sie es im Allgemeinen aus denselben Koordinaten berechnen, die Sie an TextOut übergeben haben, anstatt zu raten

Stempel hängen davon ab, dass der Viewer sie rendert

Eine Stempelanmerkung wird von einem Leser zum nächsten am wahrscheinlichsten unterschiedlich aussehen, und es lohnt sich, den Grund dafür zu verstehen. AddStampAnnotation benennt einen Standardstempel über THPDFStampAnnotationType mit Werten wie satApproved, satConfidential, satFinal, satDraft und satForComment

  Rect := Bounds(400, 50, 120, 40);
  Pdf.CurrentPage.AddStampAnnotation(satApproved, Rect, clGreen);

Der Stempelname ist eine Bitte. PDF definiert den Satz von Standard-Stempelnamen, aber nicht das Artwork dahinter, sodass jeder Viewer seine eigene Wiedergabe von "APPROVED" oder "CONFIDENTIAL" liefert, und einige rendern überhaupt nichts für Namen, die sie nicht erkennen. Das Rechteck steuert den Kasten, in den das Bild skaliert wird, und die Farbe ist ein Hinweis, den der Viewer beachten kann oder nicht. Wenn ein Stempel überall identisch aussehen muss, ist der zuverlässige Weg gar kein Standardstempel: Zeichnen Sie die Markierung selbst mit TextOut und den Zeichenaufrufen oder platzieren Sie sie als Freitextanmerkung, deren Erscheinungsbild Sie steuern. Greifen Sie auf den Standardstempel zurück, wenn Sie das vertraute Aussehen des Viewers wünschen und die Abweichung tolerieren können

Dateianhänge folgen demselben Muster aus Rechteck und Nutzlast. AddFileAttachmentAnnotation akzeptiert die Beschreibung, den Pfad der einzubettenden Datei, ein Rechteck für das Büroklammer-Symbol und eine Farbe. Die Datei reist im PDF mit, und das Symbol ist der Griff, den ein Leser verwendet, um sie zu extrahieren

Wie sich Anmerkungen von AcroForm-Feldern unterscheiden

Die Verwirrung, die am meisten Zeit kostet, ist die Behandlung einer Anmerkung, als wäre sie ein Formularfeld. Beide hängen über /Annots an der Seite, und ein Formularfeld ist tatsächlich ein spezieller Anmerkungs-Untertyp (ein Widget), weshalb sie verwandt aussehen. Sie sind nicht austauschbar. Ein Formularfeld enthält einen Wert, hat einen Namen, nimmt an der Tab-Reihenfolge teil und kann gesendet, zurückgesetzt oder per Skript bearbeitet werden. Diese erstellen Sie mit den Aufrufen AddTextField, AddCheckBox und AddPushButton, nicht mit den Anmerkungsaufrufen auf dieser Seite. Eine Markup-Anmerkung enthält einen Kommentar oder eine Form, hat keinen zu übermittelnden Wert und ist in dem Moment, in dem Sie Eingaben sammeln müssen, das falsche Werkzeug

Der Praxistest ist einfach. Wenn ein Benutzer tippen, auswählen oder klicken und sich das Dokument daran erinnern soll, benötigen Sie ein AcroForm-Feld. Wenn Sie eine Notiz hinterlassen, einen Bereich markieren oder einen Status stempeln, der mit der Datei reist, aber keine Daten ist, möchten Sie eine Anmerkung. Wenn Sie sie verwechseln, entstehen Dokumente, die richtig aussehen und sich falsch verhalten: ein "Feld", das niemand ausfüllen kann, oder ein Kommentar, der verschwindet, wenn ein Formular zurückgesetzt wird. Die interaktive Seite mit Feldtypen, Validierung und Übermittlungsaktionen ist ein eigenes Thema, das in der Durchführung von AcroForm-Feldern und -Aktionen behandelt wird

Zusammenstellen einer Seite

Die Teile setzen sich genauso zusammen wie der Rest von HotPDF. Legen Sie Dokumenteigenschaften fest, rufen Sie BeginDoc auf, zeichnen Sie den gewünschten Seiteninhalt mit den Text- und Grafikaufrufen, fügen Sie oben Anmerkungen hinzu und schließen Sie mit EndDoc. Anmerkungen hängen an CurrentPage, also landen sie nach einem AddPage auf der neuen Seite, und eine Notiz, die Sie für Seite eins vorgesehen hatten, erscheint stillschweigend auf Seite zwei, wenn Sie sie nach dem Umbruch hinzufügen

Ein letzter Reflex, den es sich aufzubauen lohnt, wenn die Ausgabe falsch aussieht: Öffnen Sie die Datei in mehr als einem Viewer, bevor Sie entscheiden, dass der Code kaputt ist. Stempel und die selteneren Notizsymbole sind die üblichen Übeltäter, und da die Anmerkung eine Bitte an den Leser und keine gemalten Pixel ist, ist ein Unterschied zwischen Acrobat und einem leichtgewichtigen Viewer oft die Spezifikation, die wie vorgesehen funktioniert, kein Fehler in Ihrem Aufruf

Die hier gezeigten Anmerkungsaufrufe sind Teil der HotPDF-Komponente für Delphi und C++Builder