Manage Markup Annotations with DevExpress PDF Document API

Apr 29, 2025
8 minutes to read

Markup annotations in PDF files are collaboration tools that allow users to add comments, highlights, and other visual elements to a document. PDF Document API supports the following markup annotation types: text, drawing, stamps, and redactions.

PDF Facade API allows you to create, delete, and flatten annotations, edit their content, and add related comments and reviews. The PdfPageFacade.Annotations property retrieves all page annotation properties. Use the PdfDocumentFacade.Pages property to obtain the PdfPageFacade class.

This help topic contains information about markup annotations. Refer to the following help topics for information on other annotation types:

Annotations in PDF Documents - lists all annotation types and their common features.
Redaction Annotations - describes redaction annotations.

Create Text Markup Annotations

Text markup annotations include the following types:

Text highlight, underline, and strikeout
Free text
Caret
Sticky notes

The table below lists supported text markup annotation types and the API used to create these annotations:

Annotation	Class	Method
Text highlight, underline and strikeout	PdfTextMarkupAnnotationFacade	PdfPageFacade.AddTextMarkupAnnotation
Caret	PdfCaretAnnotationFacade	PdfPageFacade.AddCaretAnnotation
Free Text	PdfFreeTextAnnotationFacade	PdfPageFacade.AddFreeTextAnnotation
Sticky Note	PdfTextAnnotationFacade	PdfPageFacade.AddTextAnnotation

The following code snippet creates a text highlight and a free text annotation:

C#
VB.NET

csharp

using DevExpress.Pdf;
using System;
using System.IO;

using (PdfDocumentProcessor processor = new PdfDocumentProcessor()) {

    // Load a document
    processor.LoadDocument("..\\..\\Document.pdf");

    // Access the first page's properties
    PdfPageFacade pageFacade = processor.DocumentFacade.Pages[0];

    // Find the phrase to highlight
    string annotatedText =
    "We estimate that each component of Ounce provides independent pseudorandom theory.";
   PdfTextSearchResults searchResults = pdfDocumentProcessor.FindText(annotatedText);

   if (searchResults.Status == PdfTextSearchStatus.Found) {
    // Highlight found text
    PdfTextMarkupAnnotationFacade textMarkupAnnotation =
        page.AddTextMarkupAnnotation(searchResults.Rectangles, PdfTextMarkupAnnotationType.Highlight);

    // Specify annotation properties
    textMarkupAnnotation.Author = "Bill Smith";
    textMarkupAnnotation.Subject = "Important!";
    textMarkupAnnotation.Contents = "Please, fact-check this diagram";
    textMarkupAnnotation.Color = new PdfRGBColor(0.10, 0.85, 1.00);
  }

    // Specify a free text annotation area
    PdfRectangle freeTextRectangle = new PdfRectangle(14, 321, 145, 340);

    // Create a free text annotation in this area
    PdfFreeTextAnnotationFacade freeTextAnnotation =
       pageFacade.AddFreeTextAnnotation(freeTextRectangle, "Free Text Annotation");
    freeTextAnnotation.Author = "Rayn Anita W";

    // Add a callout line
    freeTextAnnotation.SetCallout(PdfAnnotationLineEndingStyle.OpenArrow, new PdfPoint(152,351));

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

Imports DevExpress.Pdf
Imports System
Imports System.IO

Using processor As New PdfDocumentProcessor()
  ' Load a document
  processor.LoadDocument("..\..\Document.pdf")

  ' Access the first page's properties
  Dim pageFacade As PdfPageFacade = processor.DocumentFacade.Pages(0)

    ' Find the phrase to highlight
  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

  ' Highlight found text
    Dim textMarkupAnnotation As PdfTextMarkupAnnotationFacade =
      page.AddTextMarkupAnnotation(searchResults.Rectangles, PdfTextMarkupAnnotationType.Highlight)

    ' Specify annotation properties
    textMarkupAnnotation.Author = "Bill Smith"
    textMarkupAnnotation.Subject = "Important!"
    textMarkupAnnotation.Contents = "Please, fact-check this diagram"
    textMarkupAnnotation.Color = New PdfRGBColor(0.10, 0.85, 1.00)
  End If

  ' Specify a free text annotation area
  Dim freeTextRectangle As New PdfRectangle(14, 321, 145, 340)

  ' Create a free text annotation
  Dim freeTextAnnotation As PdfFreeTextAnnotationFacade =
     pageFacade.AddFreeTextAnnotation(freeTextRectangle, "Free Text Annotation")
  freeTextAnnotation.Author = "Rayn Anita W"

  ' Add a callout line
  freeTextAnnotation.SetCallout(PdfAnnotationLineEndingStyle.OpenArrow, New PdfPoint(152,351))

  ' Save the result
  processor.SaveDocument("..\..\Result.pdf")
End Using

Create Drawing Annotations

Drawing annotations are predefined or freehand drawings, shapes, polygons, and paths added directly to the document.

The table below lists supported drawing markup annotation types and the API used to create these annotations:

Annotation	Class	Method
Circle	PdfCircleAnnotationFacade	PdfPageFacade.AddCircleAnnotation
Square	PdfSquareAnnotationFacade	PdfPageFacade.AddSquareAnnotation
Line	PdfLineAnnotationFacade	PdfPageFacade.AddLineAnnotation
Polyline	PdfPolyLineAnnotationFacade	PdfPageFacade.AddPolyLineAnnotation
Polygon	PdfPolygonAnnotationFacade	PdfPageFacade.AddPolygonAnnotation
Ink	PdfInkAnnotationFacade	PdfPageFacade.AddInkAnnotation

The following code snippet creates a circle and an ink annotation:

C#
VB.NET

csharp

using DevExpress.Pdf;

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

    // Find the target phrase in the document
    string circleText = "dogfooded";
    PdfTextSearchResults searchResults = processor.FindText(circleText);
    int pageIndex = searchResults.PageNumber - 1;

    if (searchResults.Status == PdfTextSearchStatus.Found)
    {
        // Define an area around the phrase to add an annotation
        PdfRectangle circleRectangle = searchResults.Rectangles[0].BoundingRectangle;

        // Create a circle annotation in this area
        PdfCircleAnnotationFacade circleAnnotation =
            processor.DocumentFacade.Pages[pageIndex].AddCircleAnnotation(circleRectangle);
        circleAnnotation.Author = "Cardle Anita W";
        circleAnnotation.Contents = "It's better to say 'used' in this case";
        circleAnnotation.Color = new PdfRGBColor();
    }

    // Define ink vertices 
    PdfPoint[] points = new PdfPoint[]
    {
      new PdfPoint(100, 100),
      new PdfPoint(120, 100),
      new PdfPoint(130, 110),
      new PdfPoint(130, 110),
      new PdfPoint(140, 100),
      new PdfPoint(150, 150)
    };

    List<IList<PdfPoint>> inks = new List<IList<PdfPoint>> { points };

    // Create an ink annotation
    PdfInkAnnotationFacade inkAnnotation = processor.DocumentFacade.Pages[pageIndex].AddInkAnnotation(inks);
    inkAnnotation.Author = "Brian Zetc";
    inkAnnotation.BorderWidth = 1.0;

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

Imports DevExpress.Pdf

Using processor As New PdfDocumentProcessor()
  ' Load a document
  processor.LoadDocument("C:\\Documents\\Document.pdf")

  ' Find the target phrase in the document
  Dim circleText As String = "dogfooded"
  Dim searchResults As PdfTextSearchResults = processor.FindText(circleText)
  Dim pageIndex As Integer = searchResults.PageNumber - 1

  If searchResults.Status = PdfTextSearchStatus.Found Then
    ' Define an area around the phrase to add an annotation
    Dim circleRectangle As PdfRectangle = searchResults.Rectangles(0).BoundingRectangle

    ' Create a circle annotation in this area
    Dim circleAnnotation As PdfCircleAnnotationFacade = processor.DocumentFacade.Pages(pageIndex).AddCircleAnnotation(circleRectangle)
    circleAnnotation.Author = "Cardle Anita W"
    circleAnnotation.Contents = "It's better to say 'used' in this case"
    circleAnnotation.Color = New PdfRGBColor()
  End If

  ' Define ink vertices 
  Dim points() As PdfPoint = {
    New PdfPoint(100, 100),
    New PdfPoint(120, 100),
    New PdfPoint(130, 110),
    New PdfPoint(130, 110),
    New PdfPoint(140, 100),
    New PdfPoint(150, 150)
  }

  Dim inks As New List(Of IList(Of PdfPoint)) From {points}

  ' Create an ink annotation
  Dim inkAnnotation As PdfInkAnnotationFacade = processor.DocumentFacade.Pages(pageIndex).AddInkAnnotation(inks)
  inkAnnotation.Author = "Brian Zetc"
  inkAnnotation.BorderWidth = 1.0

  ' Save the result
  processor.SaveDocument("..\..\..\Result.pdf")
End Using

Create Rubber Stamp Annotations

Rubber stamp annotations are markup tools that convey various messages or statuses, such as “Approved,” “Draft”, “Confidential,” or “Rejected.” The PDF Document API supports static, dynamic, and custom stamp annotations.

The PdfPageFacade.AddRubberStampAnnotation method creates a rubber stamp annotation at the specified page area.

Create Simple Rubber Stamp Annotations

Pass one of the PdfRubberStampAnnotationIconName class fields as the PdfPageFacade.AddRubberStampAnnotation() method parameter to create a rubber stamp with a built-in static icon.

The following code snippet creates a Top Secret rubber stamp:

C#
VB.NET

csharp

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

    // Access the first page properties
    PdfPageFacade page = processor.DocumentFacade.Pages[0];

    // Define a rubber stamp rectangle
    PdfRectangle rubberStampRectangle = new PdfRectangle(663, 526, 763, 576);

    // Create a rubber stamp in this rectangle
    PdfRubberStampAnnotationFacade rubberStamp =
       page.AddRubberStampAnnotation(rubberStampRectangle, PdfRubberStampAnnotationIconName.TopSecret);
    rubberStamp.Author = "Jesse Faden";
    rubberStamp.Contents = "Made in PDF Document API";
}

Using processor As New PdfDocumentProcessor()
  'Load a document.
  processor.LoadDocument("..\..\Document.pdf")

  ' Access the first page properties.
  Dim page As PdfPageFacade = processor.DocumentFacade.Pages(0)

  ' Define a rubber stamp rectangle
  Dim rubberStampRectangle As New PdfRectangle(663, 526, 763, 576)

  ' Create a rubber stamp in this rectangle
  Dim rubberStamp As PdfRubberStampAnnotationFacade =
     page.AddRubberStampAnnotation(rubberStampRectangle, PdfRubberStampAnnotationIconName.TopSecret)
  rubberStamp.Author = "Jesse Faden"
  rubberStamp.Contents = "Made in PDF Document API"

End Using

Create Dynamic Rubber Stamp Annotations

Specify one of the following icon names as the PdfPageFacade.AddRubberStampAnnotation method parameter to create a dynamic rubber stamp:

Icon Name	Rubber Stamp
DReviewed
DRevised
DApproved
DConfidential
DReceived

Use the Author and ModificationDate properties to specify the author and the date displayed in the rubber stamp.

The following code snippet creates a Reviewed dynamic stamp:

C#
VB.NET

csharp

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

    // Access the first page's properties
    PdfPageFacade page = processor.DocumentFacade.Pages[0];

    // Define a rubber stamp rectangle
    PdfRectangle rubberStampRectangle = new PdfRectangle(663, 526, 763, 576);

    // Create a "Top Secret" rubber stamp annotation
    PdfRubberStampAnnotationFacade rubberStamp =
       page.AddRubberStampAnnotation(rubberStampRectangle, PdfRubberStampAnnotationIconName.DReviewed);
    rubberStamp.Author = "Jesse Faden";
}

Using processor As New PdfDocumentProcessor()
  ' Load a document
  processor.LoadDocument("..\..\Document.pdf")

  ' Access the first page's properties
  Dim page As PdfPageFacade = processor.DocumentFacade.Pages(0)

  ' Define a rubber stamp rectangle
  Dim rubberStampRectangle As New PdfRectangle(663, 526, 763, 576)

  ' Create a "Top Secret" rubber stamp
  Dim rubberStamp As PdfRubberStampAnnotationFacade =
     page.AddRubberStampAnnotation(rubberStampRectangle, PdfRubberStampAnnotationIconName.DReviewed)
  rubberStamp.Author = "Jesse Faden"
End Using

Create an Annotation with a Custom Stamp

You can generate a stamp that displays another document’s page. Pass the path to a file and a page number as the PdfPageFacade.AddRubberStampAnnotation method parameters to create a custom stamp.

The following code snippet generates a custom stamp from another document:

C#
VB.NET

csharp

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

    // Access the first page's properties
    PdfPageFacade page = processor.DocumentFacade.Pages[0];

    // Define a a rubber stamp rectangle
    PdfRectangle rubberStampRectangle = new PdfRectangle(663, 526, 763, 576);

    // Specify a document to use as a custom stamp
    string customStampFile = "..\\..\\Demo.pdf";

    // Create a rubber stamp annotation
    PdfRubberStampAnnotationFacade rubberStamp =
       page.AddRubberStampAnnotation(rubberStampRectangle, customStampFile, 2);
    rubberStamp.Author = "Jesse Faden";

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

}

Using processor As New PdfDocumentProcessor()
  ' Load a document
  processor.LoadDocument("..\..\Document.pdf")

  ' Access the first page's properties
  Dim page As PdfPageFacade = processor.DocumentFacade.Pages(0)

  ' Define a rubber stamp rectangle
  Dim rubberStampRectangle As New PdfRectangle(663, 526, 763, 576)

  ' Specify a document to use as a custom stamp
  Dim customStampFile As String = "..\..\Demo.pdf"

  ' Create a rubber stamp annotation
  Dim rubberStamp As PdfRubberStampAnnotationFacade =
     page.AddRubberStampAnnotation(rubberStampRectangle, customStampFile, 2)
  rubberStamp.Author = "Jesse Faden"

  ' Save the result
  processor.SaveDocument("..\..\Result.pdf")
End Using