Annotations

Feb 01, 2022
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.

View Example: How to Manage Annotations in a PDF Document

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

C#
VB.NET

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

Imports DevExpress.Pdf
'...
Using processor As New PdfDocumentProcessor()

    'Load a document:
    processor.LoadDocument("..\..\Document.pdf")

    'Highlight the specified text:
    Dim annotatedText As String =
     "We estimate that each component of Ounce provides independent pseudorandom theory."
    Dim searchResults As PdfTextSearchResults = pdfDocumentProcessor.FindText(annotatedText)
    If searchResults.Status = PdfTextSearchStatus.Found Then
        Dim textMarkup As PdfTextMarkupAnnotationData = pdfDocumentProcessor.AddTextMarkupAnnotation(searchResults.PageNumber, searchResults.Rectangles,
         PdfTextMarkupAnnotationType.Highlight)

        If textMarkup IsNot Nothing Then
            'Specify the annotation properties:
            textMarkup.Author = "Bill Smith"
            textMarkup.Contents = "Important!"
            textMarkup.Color = New PdfRGBColor(0.8, 0.2, 0.1)
        End If
    End If

    'Add a sticky note at the first page:
    Dim textAnnotation As PdfTextAnnotationData =
    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")
End Using

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:

Program.cs
Program.vb

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

Imports DevExpress.Pdf
Imports System
Imports System.Collections.Generic
'...

Private Shared Sub EditAnnotations(ByVal processor As PdfDocumentProcessor)
    'Retrieve annotations made by the specified author:
    Dim textMarkups = processor.GetMarkupAnnotationData(1).Where(Function(annotation) annotation.Author.Contains("Cardle Anita L"))
    For Each markup As PdfMarkupAnnotationData In textMarkups
        'Get all text markup annotations from the retrieved list:
        Dim pdfTextMarkup As PdfTextMarkupAnnotationData = markup.AsTextMarkupAnnotation()
        If pdfTextMarkup IsNot Nothing Then
            'Change the annotation's markup type:
            pdfTextMarkup.MarkupType = PdfTextMarkupAnnotationType.Squiggly
        End If
    Next markup

    Dim annotations = processor.GetMarkupAnnotationData(1)
    For Each annotation As PdfMarkupAnnotationData In annotations
        'Get all text annotations:
        Dim textAnnotation As PdfTextAnnotationData = annotation.AsTextAnnotation()
        If textAnnotation IsNot Nothing Then

            'Change the annotation icon:
            textAnnotation.IconName = PdfTextAnnotationIconName.Note
        End If
    Next annotation
End Sub

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:

C#
VB.NET

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

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

Using processor As New PdfDocumentProcessor()
    processor.LoadDocument("..\..\Document.pdf")

    Dim annotations = processor.GetMarkupAnnotationData(1)
    annotations(0).AddReview("Borman Aaron Lewis", PdfAnnotationReviewStatus.Completed)
End Using

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

C#
VB.NET

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";
}

Private Shared Sub AddAnnotationComments(ByVal annotation As PdfMarkupAnnotationData)
    Dim comment As PdfMarkupAnnotationComment = annotation.AddReply("Reviewer", "Done")
    comment.Subject = "Proofread"

    Dim nestedComment As PdfMarkupAnnotationComment = comment.AddReply(annotation.Author, "Thanks")
    nestedComment.Subject = "Reviewed"
End Sub

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.

Program.cs
Program.vb

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

Imports DevExpress.Pdf
Imports System.Linq
'...
Private Shared Sub DeleteAnnotations(ByVal processor As PdfDocumentProcessor)
    For i As Integer = 0 To processor.Document.Pages.Count
        'Remove Borman Aaron Lewis's markup annotations from a page.
        processor.DeleteMarkupAnnotations(processor.GetMarkupAnnotationData(i).Where(Function(annotation) annotation.Author.Contains("Borman Aaron Lewis")))
    Next i
End Sub

Controls

Tools

Controls and Extensions

Tools

Maintenance Mode

Controls

Tools

Controls and Extensions

Tools

Maintenance Mode

Create an Annotation

Edit an Annotation

Add a Review to the Annotation

Add Comments to the Annotation

Delete the Annotation