Annotations

  • 6 minutes to read

The PDF Document API supports the following annotation types:

  • Text annotation, or sticky note - a note attached to a point.
  • Text markup annotation - text highlight.

You can create and delete annotations, edit their content, and add related comments.

Create an Annotation

Use the following API to create annotations:

Method Description
PdfDocumentProcessor.AddTextAnnotation Creates a text annotation at the specified point or area. The returned PdfTextAnnotationData object allows you to specify annotation parameters.
PdfDocumentProcessor.AddTextMarkupAnnotation Creates a text markup annotation for the text located at the specified area or between two points. The returned PdfTextMarkupAnnotationData object allows you to specify annotation parameters. If a specified page area does not contain text, the annotation is not created and the method returns null.

The code sample below highlights text with blue and adds a sticky note at the page corner.

image

using DevExpress.Pdf;
//...
using (PdfDocumentProcessor processor = new PdfDocumentProcessor())
{
    //Load a document:
    processor.LoadDocument("..\\..\\Document.pdf");

    //Highlight the specified text:
    string annotatedText =
     "We estimate that each component of Ounce provides independent pseudorandom theory.";
    PdfTextSearchResults searchResults = pdfDocumentProcessor.FindText(annotatedText);
    if (searchResults.Status == PdfTextSearchStatus.Found)
    {
        PdfTextMarkupAnnotationData textMarkup =
        pdfDocumentProcessor.AddTextMarkupAnnotation(searchResults.PageNumber, searchResults.Rectangles,
         PdfTextMarkupAnnotationType.Highlight);

        if (textMarkup != null)
        {
            //Specify the annotation properties:
            textMarkup.Author = "Bill Smith";
            textMarkup.Contents = "Important!";
            textMarkup.Color = new PdfRGBColor(0.8, 0.2, 0.1);
        }
    }


    //Add a sticky note at the first page:
    PdfTextAnnotationData textAnnotation =
    processor.AddTextAnnotation(1, new PdfPoint(100, 300));

    //Specify the annotation parameters:
    textAnnotation.Author = "Nancy Davolio";
    textAnnotation.Checked = true;
    textAnnotation.Color = new PdfRGBColor(0.8, 0.2, 0.1);
    textAnnotation.Contents = "Please proofread this document";
    textAnnotation.IconName = PdfTextAnnotationIconName.Check;

    //Save the result:
    processor.SaveDocument("..\\..\\Result.pdf");
}

Edit an Annotation

The following API allows you to change annotation settings:

API Description
PdfDocumentProcessor.GetMarkupAnnotationData Returns all markup annotations from the specified page. Use the PdfMarkupAnnotationDataExtensions class methods to retrieve specific type of annotations.
PdfMarkupAnnotationData.Author Gets or sets the annotation's author.
PdfMarkupAnnotationData.Subject Specifies a subject that the annotation addresses.
PdfAnnotationData.Contents Specifies the annotation's text or alternative description.
PdfAnnotationData.Color Defines the annotation's color.
PdfMarkupAnnotationData.Opacity Gets or sets the annotation's opacity.
PdfTextAnnotationData.IconName Specifies an icon used to display a text annotation. Use the PdfTextAnnotationIconName class fields to specify one of the built-in icons.

The code sample below changes the markup style for annotations made by a specific author and changes the icon for all text annotations:

image

using DevExpress.Pdf;
using System;
using System.Collections.Generic;
//...
private static void EditAnnotations(PdfDocumentProcessor processor)
{
    //Retrieve annotations made by the specified author:
    var textMarkups =
        processor.GetMarkupAnnotationData(1).
        Where(annotation => annotation.Author.Contains("Cardle Anita L"));
    foreach (PdfMarkupAnnotationData markup in textMarkups)
    {
        //Get all text markup annotations from the retrieved list:
        PdfTextMarkupAnnotationData pdfTextMarkup =
         markup.AsTextMarkupAnnotation();
        if (pdfTextMarkup != null)
            //Change the annotation's markup type:
            pdfTextMarkup.MarkupType = PdfTextMarkupAnnotationType.Squiggly;
    }

    var annotations = processor.GetMarkupAnnotationData(1);
    foreach (PdfMarkupAnnotationData annotation in annotations)
    {
        //Get all text annotations:
        PdfTextAnnotationData textAnnotation = annotation.AsTextAnnotation();
        if (textAnnotation != null)

            //Change the annotation icon:
            textAnnotation.IconName = PdfTextAnnotationIconName.Note;
    }
}

Add a Review to the Annotation

Call the PdfMarkupAnnotationData.AddReview method to add a review to the annotation. The PdfMarkupAnnotationComment.Reviews property obtains all annotation reviews.

The code sample below gets all annotations and adds a review to the first annotation:

using (PdfDocumentProcessor processor = new PdfDocumentProcessor())
{
    processor.LoadDocument("..\\..\\Document.pdf");

    var annotations = processor.GetMarkupAnnotationData(1);
    annotations[0].AddReview("Borman Aaron Lewis", PdfAnnotationReviewStatus.Completed);
}

To remove all reviews, call the PdfMarkupAnnotationData.ClearReviews() method.

Add Comments to the Annotation

The table below lists API used to add annotation comments:

API Description
PdfMarkupAnnotationData.AddReply Adds a comment to the annotation. This method returns the PdfMarkupAnnotationComment object. Use this class' members to change the reply's author, subject and text.
PdfMarkupAnnotationData.Replies Obtains all annotation comments.
PdfMarkupAnnotationComment.AddReply Creates a nested comment.
PdfMarkupAnnotationComment.Replies Gets all nested comments added to the comment.
PdfMarkupAnnotationComment.AddReview Add a review to the comment. Use thePdfMarkupAnnotationData.Reviews property to get all reviews.

The code sample below creates two nested comments and adds a review to the second comment (the document is opened in DevExpress WinForms PDF Viewer):

annotations-comment

private static void AddAnnotationComments(PdfMarkupAnnotationData annotation)
{
    PdfMarkupAnnotationComment comment =
    annotation.AddReply("Reviewer", "Done");
    comment.Subject = "Proofread";

    PdfMarkupAnnotationComment nestedComment =
    comment.AddReply(annotation.Author, "Thanks");
    nestedComment.Subject = "Reviewed";
}

The PdfMarkupAnnotationData.RemoveReply method removes the specified comment. To remove the specified nested comment, call the PdfMarkupAnnotationComment.RemoveReply method.

Delete the Annotation

Call the PdfDocumentProcessor.DeleteMarkupAnnotations method to remove all markup annotations from the specified page.

To delete a specific annotation, call the PdfDocumentProcessor.DeleteMarkupAnnotation method. Pass the target PdfMarkupAnnotationData object as a parameter to this method.

This example shows how to delete text markup annotations created by a specific author.

using DevExpress.Pdf;
using System.Linq;
//...
private static void DeleteAnnotations(PdfDocumentProcessor processor)
{
    for (int i = 0; i <= processor.Document.Pages.Count; i++)
    {
        //Remove Borman Aaron Lewis's markup annotations from a page.
        processor.DeleteMarkupAnnotations(processor.GetMarkupAnnotationData(i)
        .Where(annotation => annotation.Author.Contains("Borman Aaron Lewis")));
    }
}