Σχολιασμοί PDF στο Delphi με το HotPDF: Τύποι και Ορθογώνια (Rects)

Ένας σχολιασμός (annotation) δεν είναι περιεχόμενο σελίδας. Όταν καλείτε το TextOut ή σχεδιάζετε ένα ορθογώνιο, τα σημάδια γίνονται μέρος της ροής περιεχομένου της σελίδας (content stream), ψημένα στα bytes που ζωγραφίζει ένας αποδότης. Ένας σχολιασμός είναι ένα ξεχωριστό λεξικό που εξαρτάται από τη σελίδα μέσω του πίνακά του /Annots, με το δικό του ορθογώνιο, τη δική του εμφάνιση και τον δικό του κύκλο ζωής. Ένας αναγνώστης μπορεί να τον ανοίξει, να τον μετακινήσει, να τον κρύψει ή να τον αφαιρέσει χωρίς να αγγίξει ούτε ένα γλυφικό της υποκείμενης σελίδας. Αυτός ο διαχωρισμός είναι ο κύριος λόγος για τον οποίο υπάρχουν οι σχολιασμοί, και είναι επίσης η πηγή των δύο πραγμάτων που εκπλήσσουν τους ανθρώπους πρώτα: πού προσγειώνεται ένας σχολιασμός, και πώς φαίνεται μόλις τον αναλάβει ένας συγκεκριμένος προβολέας

Το HotPDF εκθέτει τους υποτύπους σχολιασμών ISO 32000 μέσω μιας οικογένειας κλήσεων AddXxxAnnotation στο αντικείμενο της σελίδας. Όλοι τους μοιράζονται το ίδιο σχήμα: ένα ορθογώνιο που σταθεροποιεί τον σχολιασμό στη σελίδα στον χώρο χρήστη (user space) του PDF, κάποιο ωφέλιμο φορτίο (payload) (κείμενο, ένα όνομα σφραγίδας, ένα ζεύγος σημείων) και ένα χρώμα. Αν πετύχετε το ορθογώνιο, το μεγαλύτερο μέρος της δουλειάς έχει γίνει. Το υπόλοιπο είναι να γνωρίζετε ποιοι υπότυποι φέρουν τη δική τους εμφάνιση και ποιοι στηρίζονται στον προβολέα για να τους σχεδιάσει

Το ορθογώνιο είναι ο σχολιασμός, όχι το κείμενο

Κάθε κλήση σχολιασμού παίρνει ένα TRect, και αυτό το ορθογώνιο σημαίνει κάτι διαφορετικό από τις συντεταγμένες που περνάτε στο TextOut. Για μια σημείωση κειμένου είναι το hotspot (ενεργό σημείο) που μπορεί να γίνει κλικ, η μικρή περιοχή όπου βρίσκεται το εικονίδιο της σημείωσης και όπου ένα κλικ ανοίγει το σχόλιο. Για ένα τετράγωνο ή πλαίσιο ελεύθερου κειμένου είναι η ορατή έκταση της επισήμανσης (markup). Για μια σφραγίδα (stamp) είναι το κουτί στο οποίο κλιμακώνεται η τέχνη της σφραγίδας. Οι αριθμοί είναι στιγμές (points) στον χώρο χρήστη του PDF, μετρούμενες από την κάτω αριστερή γωνία της σελίδας με το Y να αυξάνεται προς τα πάνω, την ίδια σύμβαση που χρησιμοποιεί το υπόλοιπο HotPDF

Μια σημείωση κειμένου είναι ο ελαφρύτερος υπότυπος. Της δίνετε το κείμενο του σώματος, ένα ορθογώνιο για το εικονίδιο, μια σημαία για το αν ανοίγει από προεπιλογή, ένα όνομα εικονιδίου και ένα χρώμα

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

Το ορθογώνιο εδώ είναι σκόπιμα μικρό, γύρω στις είκοσι στιγμές σε κάθε πλευρά, επειδή μια σημείωση κειμένου είναι μόνο ένα εικονίδιο μέχρι κάποιος να κάνει κλικ σε αυτό. Αν κάνετε το ορθογώνιο μεγάλο δεν παίρνετε μια μεγάλη σημείωση. παίρνετε έναν υπερμεγέθη στόχο κλικ με το εικονίδιο καρφιτσωμένο σε μια γωνία. Η σημαία Open ελέγχει εάν το αναδυόμενο παράθυρο εμφανίζεται κατά τη φόρτωση του εγγράφου. Ρυθμίστε αρκετές σημειώσεις σε True και στοιβάζονται η μία πάνω στην άλλη και πάνω στο περιεχόμενο, επομένως κρατήστε το για τη μία σημείωση που θέλετε πραγματικά να δει αμέσως ο αναγνώστης

Το όνομα του εικονιδίου προέρχεται από το THPDFTextAnnotationType, το οποίο αντιστοιχίζεται στα τυπικά εικονίδια σημειώσεων: taComment, taKey, taNote, taHelp, taParagraph, taNewParagraph και taInsert. Το εικονίδιο είναι το μόνο πράγμα που αλλάζει ο τύπος. Δεν αλλάζει τη συμπεριφορά, και αξίζει να γνωρίζετε ότι δεν σχεδιάζει κάθε προβολέας και τα επτά. τα ασφαλή σε παλιούς και νέους αναγνώστες είναι τα taComment, taNote και taHelp

Το ελεύθερο κείμενο γράφει στη σελίδα, αλλά παραμένει σχολιασμός

Ένας σχολιασμός ελεύθερου κειμένου μοιάζει με περιεχόμενο επειδή το κείμενο είναι ορατό χωρίς κλικ, καθισμένο στο ορθογώνιό του σαν λεζάντα. Εξακολουθεί να είναι ένας σχολιασμός, με όλη τη διαχωρισιμότητα που αυτό συνεπάγεται, το οποίο είναι ακριβώς αυτό που θέλετε για μια σφραγίδα αναθεώρησης (review stamp) ή μια ετικέτα προσχεδίου (draft label) που κάποιος θα πρέπει να μπορεί να αφαιρέσει αργότερα. Η υπογραφή αλλάζει το εικονίδιο και την ανοιχτή σημαία (open flag) με μια τιμή στοίχισης

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

Εδώ το ορθογώνιο έχει μεγαλύτερη σημασία από ό,τι για μια σημείωση κειμένου, επειδή το κείμενο αναδιπλώνεται και στοιχίζεται μέσα σε αυτό. Αν κάνετε το κουτί πολύ κοντό το κείμενο κόβεται στο κάτω άκρο. πολύ στενό και αναδιπλώνεται σε μέρη που δεν σκοπεύατε. Η στοίχιση προέρχεται από το THPDFFreeTextAnnotationJust και έχει μόνο τις τρεις τιμές. Επειδή το ελεύθερο κείμενο είναι ένας σχολιασμός επισήμανσης (markup annotation), ένας αναγνώστης που ανοίγει το αρχείο σε έναν επεξεργαστή μπορεί να το επιλέξει, να το μετακινήσει ή να το διαγράψει ως ενιαία μονάδα, η οποία είναι η διαφορά που αποφασίζει αν θα χρησιμοποιήσετε το ελεύθερο κείμενο ή απλά θα σχεδιάσετε τις λέξεις με το TextOut. Αν η ετικέτα πρέπει να είναι μόνιμη, σχεδιάστε την. Αν είναι συντακτική και προορίζεται να βγει, κάντε την σχολιασμό

Γεωμετρικές και γραμμικές επισημάνσεις (line markups) για να δείχνετε πράγματα

Τα τετράγωνα, οι κύκλοι και οι γραμμές είναι η επισήμανση που χρησιμοποιείτε για να δείξετε μια περιοχή αντί να την περιγράψετε με λέξεις. Το AddCircleSquareAnnotation καλύπτει τα δύο σχήματα κουτιών μέσω ενός THPDFCSAnnotationType του csCircle ή csSquare, με το ορθογώνιο να δίνει τα όρια του σχήματος

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

Παρατηρήστε ότι ο σχολιασμός γραμμής σπάει το μοτίβο του ορθογωνίου: παίρνει δύο εγγραφές THPDFCurrPoint, μια αρχή και ένα τέλος, επειδή μια γραμμή ορίζεται από τα τελικά της σημεία, όχι από ένα οριακό κουτί (bounding box). Το χρώμα ορίζει την πινελιά. Αν θέλετε αιχμές βελών, το HotPDF έχει υπερφορτώσεις (overloads) του AddLineAnnotation που δέχονται στυλ κατάληξης γραμμής, αλλά η απλή μορφή με τα τρία ορίσματα σχεδιάζει μια γυμνή γραμμή, που είναι συνήθως αυτό που θέλει μια επεξήγηση (callout)

Οι υπότυποι επισήμανσης κειμένου (Text-markup) λειτουργούν σε μια περιοχή που έχετε ήδη διατάξει. Το AddHighlightAnnotation παίρνει ένα ορθογώνιο, προαιρετικά περιεχόμενα και ένα χρώμα που από προεπιλογή είναι κίτρινο, και χρωματίζει την περιοχή με τον τρόπο που θα έκανε ένας μαρκαδόρος υπογράμμισης (highlighter). Προορίζεται να καθίσει πάνω από πραγματικό κείμενο, οπότε το ορθογώνιο θα πρέπει να ταιριάζει με τα όρια των λέξεων που σχεδιάσατε, το οποίο σημαίνει ότι γενικά το υπολογίζετε από τις ίδιες συντεταγμένες που περάσατε στο TextOut αντί να μαντεύετε

Οι σφραγίδες εξαρτώνται από τον προβολέα (viewer) για την απόδοσή τους

Ένας σχολιασμός σφραγίδας είναι αυτός που έχει τις περισσότερες πιθανότητες να φαίνεται διαφορετικός από τον έναν αναγνώστη στον άλλον, και ο λόγος αξίζει να κατανοηθεί. Το AddStampAnnotation ονομάζει μια τυπική σφραγίδα μέσω του THPDFStampAnnotationType, με τιμές όπως satApproved, satConfidential, satFinal, satDraft και satForComment

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

Το όνομα της σφραγίδας είναι ένα αίτημα. Το PDF ορίζει το σύνολο των τυπικών ονομάτων σφραγίδων αλλά όχι το γραφικό (artwork) πίσω από αυτά, οπότε κάθε προβολέας αποστέλλει τη δική του απόδοση των "APPROVED" (ΕΓΚΕΚΡΙΜΕΝΟ) ή "CONFIDENTIAL" (ΕΜΠΙΣΤΕΥΤΙΚΟ), και μερικοί δεν αποδίδουν απολύτως τίποτα για ονόματα που δεν αναγνωρίζουν. Το ορθογώνιο ελέγχει το κουτί στο οποίο κλιμακώνεται το γραφικό, και το χρώμα είναι ένας υπαινιγμός που ο προβολέας μπορεί να τιμήσει ή όχι. Αν μια σφραγίδα πρέπει να φαίνεται πανομοιότυπη παντού, η αξιόπιστη διαδρομή δεν είναι καθόλου μια τυπική σφραγίδα: σχεδιάστε το σημάδι μόνοι σας με το TextOut και τις κλήσεις σχεδίασης, ή τοποθετήστε το ως σχολιασμό ελεύθερου κειμένου του οποίου την εμφάνιση ελέγχετε. Επιλέξτε την τυπική σφραγίδα όταν θέλετε τη γνώριμη εμφάνιση του προβολέα και μπορείτε να ανεχτείτε την παραλλαγή

Τα συνημμένα αρχεία ακολουθούν το ίδιο σχήμα ορθογωνίου-συν-ωφέλιμου-φορτίου. Το AddFileAttachmentAnnotation παίρνει την περιγραφή, τη διαδρομή του αρχείου προς ενσωμάτωση, ένα ορθογώνιο για το εικονίδιο συνδετήρα και ένα χρώμα. Το αρχείο ταξιδεύει μέσα στο PDF, και το εικονίδιο είναι η λαβή που χρησιμοποιεί ένας αναγνώστης για να το εξαγάγει

Πώς οι σχολιασμοί διαφέρουν από τα πεδία του AcroForm

Η σύγχυση που κοστίζει τον περισσότερο χρόνο είναι η αντιμετώπιση ενός σχολιασμού σαν να ήταν πεδίο φόρμας. Και τα δύο προσκολλώνται στη σελίδα μέσω του /Annots, και ένα πεδίο φόρμας είναι στην πραγματικότητα ένας ειδικός υπότυπος σχολιασμού (ένα widget), πράγμα που εξηγεί γιατί φαίνονται συγγενικά. Δεν είναι εναλλάξιμα. Ένα πεδίο φόρμας κρατά μια τιμή, έχει ένα όνομα, συμμετέχει στη σειρά tab (tab order), και μπορεί να υποβληθεί, να επαναφερθεί ή να δεχτεί σενάρια (scripts). δημιουργείτε αυτά με τις κλήσεις AddTextField, AddCheckBox και AddPushButton, όχι με τις κλήσεις σχολιασμού σε αυτήν τη σελίδα. Ένας σχολιασμός επισήμανσης (markup annotation) κρατά ένα σχόλιο ή ένα σχήμα, δεν έχει καμία τιμή προς υποβολή, και είναι το λάθος εργαλείο τη στιγμή που χρειάζεστε να συλλέξετε εισαγωγή δεδομένων

Η πρακτική δοκιμή είναι απλή. Αν ένας χρήστης πρόκειται να πληκτρολογήσει, να επιλέξει ή να κάνει κλικ και το έγγραφο να το θυμάται, θέλετε ένα πεδίο AcroForm. Αν αφήνετε μια σημείωση, επισημαίνετε μια περιοχή ή σφραγίζετε μια κατάσταση που ταξιδεύει με το αρχείο αλλά δεν είναι δεδομένα, θέλετε έναν σχολιασμό. Η ανάμειξή τους παράγει έγγραφα που φαίνονται σωστά και συμπεριφέρονται λάθος: ένα "πεδίο" που κανείς δεν μπορεί να συμπληρώσει, ή ένα σχόλιο που εξαφανίζεται όταν γίνεται επαναφορά μιας φόρμας. Η διαδραστική πλευρά, με τους τύπους πεδίων, την επικύρωση και τις ενέργειες υποβολής, είναι το δικό της ξεχωριστό θέμα που καλύπτεται στο άρθρο για τα πεδία και τις ενέργειες AcroForm

Συγκροτώντας μια σελίδα

Τα κομμάτια συνθέτονται με τον τρόπο που το κάνει το υπόλοιπο HotPDF. Ορίστε τις ιδιότητες του εγγράφου, καλέστε το BeginDoc, σχεδιάστε οποιοδήποτε περιεχόμενο σελίδας χρειάζεστε με τις κλήσεις κειμένου και γραφικών, προσθέστε σχολιασμούς από πάνω, και κλείστε με το EndDoc. Οι σχολιασμοί προσκολλώνται στην CurrentPage (Τρέχουσα Σελίδα), οπότε μετά από ένα AddPage προσγειώνονται στη νέα σελίδα, και μια σημείωση που προορίζατε για τη σελίδα ένα θα εμφανιστεί αθόρυβα στη σελίδα δύο αν την προσθέσετε μετά την αλλαγή σελίδας

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;

Ένα τελευταίο αντανακλαστικό που αξίζει να χτίσετε όταν η έξοδος φαίνεται λάθος: ανοίξτε το αρχείο σε περισσότερους από έναν προβολείς πριν αποφασίσετε ότι ο κώδικας είναι σπασμένος. Οι σφραγίδες και τα σπανιότερα εικονίδια σημειώσεων είναι οι συνήθεις ένοχοι, και επειδή ο σχολιασμός είναι ένα αίτημα προς τον αναγνώστη αντί για ζωγραφισμένα pixels, μια διαφορά μεταξύ του Acrobat και ενός ελαφρύτερου προβολέα είναι συχνά η προδιαγραφή που λειτουργεί όπως έχει σχεδιαστεί, όχι ένα σφάλμα στην κλήση σας

Οι κλήσεις σχολιασμών που παρουσιάζονται εδώ αποτελούν μέρος του HotPDF Component για Delphi και C++Builder