Annotations

edit

Add markup annotations

The methods of PdfPage.Annotations add the annotations a reviewer adds to a document:

var annotations = page.Annotations;
var note = annotations.AddNote(new PdfPoint(40, 700), "Check this paragraph");
note.Author = "Reviewer";
annotations.AddTextMarkup(PdfTextMarkupKind.Highlight, [new PdfRectangle(72, 697, 175, 710)]);
annotations.AddFreeText(new PdfRectangle(300, 690, 500, 730), "Free text drawn on the page", fontSize: 10);
annotations.AddStamp(new PdfRectangle(400, 750, 550, 800), "APPROVED", PdfColor.FromRgb(0, 0.5, 0));
MethodAnnotation
AddNoteA note: an icon that opens a text
AddTextMarkupA highlight, an underline, a squiggly underline or a strikeout of regions of the page, one rectangle per line
AddFreeTextA text in a box, drawn on the page, in a standard font
AddStampA word in a frame with rounded corners, such as APPROVED or DRAFT
AddLineA straight line, with endings such as arrows
AddSquare, AddCircleA rectangle or an ellipse, with a border and an optional fill
AddPolygon, AddPolyLineA closed shape, or connected lines with endings
AddInkFreehand strokes, as drawn with a pen
AddCaretA symbol that marks where text is to be inserted
AddRedactionRegions to remove, applied later: see Redaction
  • Each annotation has an appearance stream, so that every viewer shows and prints it the same way. A highlight is multiplied with the content, so that the text under it stays readable.
  • The markup annotations have an Author, a Subject, a CreationDate and an Opacity.
  • Color is the color of any annotation: the border of a shape, the color of a line or of a text markup.

Shapes, lines and ink

The shapes, the lines and the ink are drawn from their geometry. The lines and the polylines can end with arrows, circles, squares... (PdfLineEnding):

var annotations = page.Annotations;
var arrow = annotations.AddLine(new PdfPoint(100, 600), new PdfPoint(250, 680), endEnding: PdfLineEnding.ClosedArrow);
arrow.Contents = "Look here";
annotations.AddSquare(new PdfRectangle(260, 660, 400, 720), PdfColor.FromRgb(0, 0, 0.8), interiorColor: PdfColor.FromRgb(0.9, 0.9, 1));
annotations.AddCircle(new PdfRectangle(100, 450, 200, 520), width: 2);
annotations.AddPolygon([new PdfPoint(300, 450), new PdfPoint(400, 450), new PdfPoint(350, 530)]);
annotations.AddInk([[new PdfPoint(100, 300), new PdfPoint(150, 350), new PdfPoint(200, 300)]], PdfColor.FromRgb(0, 0.6, 0), width: 3);

// A reply in the thread of the arrow, and the window that shows its text
annotations.AddReply(arrow, "Fixed in the next version", author: "Author");
annotations.AddPopup(arrow, new PdfRectangle(260, 560, 460, 640));

The rectangle of a line, a polygon or an ink annotation is computed from its points, with room for its width and its endings.

Read the annotations of a file

Each annotation of a page is an instance of the class of its type, so a pattern match gives its properties:

Type (/Subtype)ClassProperties
TextPdfTextAnnotationThe icon, whether it is open, the review state
FreeTextPdfFreeTextAnnotationThe default appearance, the alignment, the callout line
LinePdfLineAnnotationThe start and the end, the endings, the leader lines
Square, CirclePdfSquareAnnotation, PdfCircleAnnotationThe interior color
Polygon, PolyLinePdfPolygonAnnotation, PdfPolyLineAnnotationThe vertices, the endings of a polyline
InkPdfInkAnnotationThe strokes
Highlight, Underline, Squiggly, StrikeOutPdfTextMarkupAnnotationThe kind, the regions
StampPdfStampAnnotationThe name of the stamp
CaretPdfCaretAnnotationWhether it is a paragraph symbol
RedactPdfRedactAnnotationThe regions, the color and the text that replace them
PopupPdfPopupAnnotationThe parent, whether it is open
WidgetPdfWidgetAnnotationThe appearance state, the highlight mode, the colors and captions (AppearanceCharacteristics)
LinkPdfLinkAnnotationThe URI or the destination: see Outline and links
FileAttachmentPdfFileAttachmentAnnotationThe file: see Embedded files

The sound annotations are PdfMarkupAnnotation, and the annotations of other types PdfAnnotation: read their Dictionary.

Change an annotation

The properties read and write the annotation dictionary. Every annotation also has a UniqueName, a ModificationDate and a Border: its width, its style (solid, dashed, beveled, inset, underline), its dashes and its cloudy effect.

Viewers draw the appearance of an annotation, not its properties: after changing the geometry, the colors or the border of an annotation, call UpdateAppearance to draw it again. It draws the shapes, the lines, the ink, the text markups, the notes, the free texts, the stamps, the carets and the redactions, and returns false for the other types (links, file attachments, sounds...), whose appearance is left as it is. The rectangle of a line, a polygon, a polyline or an ink annotation is computed again from its points. The widget of a text or a choice field gets the appearance of the value of its field; the widgets of buttons keep theirs, whose states are the values of their fields.

Replies and pop-ups

A markup annotation can have a pop-up window that shows its text, and replies, which viewers list in its thread:

  • AddPopup adds the pop-up window of an annotation and sets its Popup.
  • AddReply adds a note in reply to an annotation. The reply has an empty appearance, so that it does not draw a second icon.
  • InReplyTo and ReplyType give the annotation a reply answers, and GetReplies the replies of an annotation on its page.

Flatten the annotations

Flattening draws the appearance of annotations in the content of their page and removes them, so that they become content that cannot be changed:

// The markup annotations become content of the page; the links are kept
var flattened = document.FlattenAnnotations();
  • PdfDocument.FlattenAnnotations flattens every page, PdfPage.FlattenAnnotations one page.
  • By default, the markup annotations are flattened, except the redactions. Filter selects others, such as the links or the widgets. The widgets of signed signature fields are never flattened.
  • The annotations hidden for the Intent are removed without being drawn: those with the NoView flag for the screen, those without the Print flag for printing.
  • The appearance is drawn with the opacity of the annotation, as a whole (a transparency group), and in its optional content (its layer). An annotation without an appearance gets the one UpdateAppearance draws.
  • The pop-up of a flattened annotation is removed, and its replies no longer point to it.

To flatten the form fields with their values, use PdfInteractiveForm.Flatten: see Forms.

Flags

Flags reads and changes the flags of an annotation: whether it is printed, hidden, shown on the screen, locked... The bits that PdfAnnotationFlags does not name are kept. The annotations the library creates are printed.

Remove an annotation

Remove removes an annotation from its page with what would keep it in a saved file: its pop-up, the references of the other annotations to it (replies, pop-ups), its entry in the structure tree, and, for a widget, its entry in its form field.

The order of the annotations

PdfPage.Annotations reads the annotations once, and again when the annotations of the page change: through the collection or the object model. An annotation is the same instance until then, and an indexed loop does not read them again on each iteration.