Add Annotations in the DevExpress PDF Viewer for .NET MAUI

• Aug 29, 2024
• 7 minutes to read

The DevExpress PDF Viewer for .NET MAUI allows users to add different annotations to a PDF document. An annotation is an object that is bound to a specific place in a document. The following annotation types are supported:

• Sticky notes (“Text” annotations in a PDF)
• Free text (“FreeText”)
• Free-hand drawing (“Ink”)
• Rectangles (“Square”)
• Ellipses (“Circle”)
• Highlight with a rectangle (“Highlight”)
• Underline with a straight line (“Underline”)
• Underline with a wavy line (“Squiggly”)
• Strikethrough (“StrikeOut”)

For more information about markup text annotations (highlight, underline, squiggle, and strikethrough), refer to the following help topic section: Highlight the Selected Text.

Access Annotation Collection

The PDF viewer stores all document annotations in the Annotations collection. Once you (or a user) add a new annotation, the PDF Viewer control re-sorts the Annotations collection to insert this annotation (insert where) according to its position in the document.

Users can add comments to each annotation in the document. The Author property defines the person who adds the comment.

All annotations with assigned comments are available in the Annotations view. You can tap the icon in the PDF viewer or call the PdfViewerCommands.ToggleAnnotations command to open the Annotations view:

Add Sticky Notes

Follow the steps below to add a sticky note with the PDF viewer UI:

1. Tap the New Note icon () in the edit toolbar.
2. Tap on a document page.
3. Type the sticky note text.

4. Tap Save:

   

You can delete, add a comment, or change the sticky note color in its context menu. To invoke the menu, tap a sticky note:

Add Sticky Notes Programmatically

Use the following API members to add sticky notes with specified settings on a PDF document page:

AddStickyNoteAnnotation

Adds a sticky note with the specified text to the given position in the document.

PdfAnnotationOptions.AllowAddStickyNote

Set this property to False to disable the Sticky Note icon in the edit toolbar. This also disables the AddStickyNoteAnnotation method functionality.

PdfAnnotationOptions.StickyNoteColor

Specifies the fill color of sticky notes.

PdfAnnotationOptions.StickyNoteSubject

Specifies the subject for comments assigned to sticky notes.

XAML

<dx:PdfViewer.AnnotationOptions>
    <dx:PdfAnnotationOptions ...
                              StickyNoteColor="Beige"
                              StickyNoteSubject="Note"/>
</dx:PdfViewer.AnnotationOptions>
<dx:DXButton Clicked="DXButton_Clicked"/>

C#

private void DXButton_Clicked(object sender, EventArgs e) {
    pdfViewer.AddStickyNoteAnnotation(new PdfDocumentPosition(1, new PdfPoint(300, 100)), "Sticky note text");
}

Add Text Labels

Follow the steps below to add a text label with the PDF viewer UI:

1. Tap the Text icon () in the edit toolbar.
2. Draw the label frame on a document page.
3. Type the label text.
4. Type Save.

In the context menu, you can delete, add a comment, change text size and color. To invoke the menu, tap a text label:

Add Text Labels Programmatically

Use the following API members to add text directly to a page and customize text settings:

AddFreeTextAnnotation

Adds a text label to a page.

PdfAnnotationOptions.AllowAddFreeText

Set this property to False to disable the Text icon in the edit toolbar. This change also disables AddFreeTextAnnotation method functionality.

PdfAnnotationOptions.FreeTextColor

Specifies text color.

PdfAnnotationOptions.FreeTextFontSize

Specifies the text font size.

PdfAnnotationOptions.FreeTextSubject

Specifies the subject for comments assigned to free text annotations.

XAML

<dx:PdfViewer.AnnotationOptions>
    <dx:PdfAnnotationOptions ...
                             FreeTextColor="Blue"
                             FreeTextFontSize="10"
                             FreeTextSubject="Subject"/>
</dx:PdfViewer.AnnotationOptions>
<dx:DXButton Clicked="DXButton_Clicked" .../>

C#

private void DXButton_Clicked(object sender, EventArgs e) {
    pdfViewer.AddFreeTextAnnotation(0, new PdfRectangle(0, 0, 100, 100), "Your text");
}

Add Free-Hand Drawings

Follow the steps below to add a drawing with the PDF viewer UI:

1. Tap the Graphics icon () in the edit toolbar.

2. Tap the Draw icon:

   

3. (Optional) Change line thickness and color:

   

4. Draw on the document page.

5. Tap Done to finish.

In the context menu, you can delete a drawing, add a comment, change line thickness and color. To invoke this menu, tap the drawing and select the corresponding option. You can also resize and move the selected drawing.

Add Free-Hand Drawings Programmatically

Use the following API members to add free-hand drawings with specified settings to a PDF document page:

AddInkAnnotation

Adds an ink drawing to a page with the given serial number.

PdfAnnotationOptions.AllowAddInk

Set this property to False to disable the Draw icon in the edit toolbar. This also disables the AddInkAnnotation method functionality.

PdfAnnotationOptions.InkColor

Specifies the ink color.

PdfAnnotationOptions.InkLineWidth

Defines ink line thickness.

PdfAnnotationOptions.InkSubject

Specifies the subject for comments assigned to drawing annotations.

XAML

<dx:PdfViewer.AnnotationOptions>
    <dx:PdfAnnotationOptions ...
                             InkColor="Green"
                             InkLineWidth="2"
                             InkSubject="Ink drawing"/>
</dx:PdfViewer.AnnotationOptions>
<dx:DXButton Clicked="DXButton_Clicked" .../>

C#

private void DXButton_Clicked(object sender, EventArgs e) {
    // The origin point (0,0) is the page's bottom-left corner; coordinates are in document units.
    PdfPoint point1 = new PdfPoint(100, 100);
    PdfPoint point2 = new PdfPoint(110, 110);
    PdfPoint point3 = new PdfPoint(120, 100);
    PdfPoint point4 = new PdfPoint(130, 110);
    PdfPoint point5 = new PdfPoint(140, 100);
    PdfPoint point6 = new PdfPoint(150, 150);
    PdfPoint[] points = new[] { point1, point2, point3, point4, point5, point6 };

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

    pdfViewer.AddInkAnnotation(0, inks);
}

Add Rectangles

Follow the steps below to add a rectangle with the PDF viewer UI:

1. Tap the Graphics icon () in the edit toolbar.

2. Tap the Rectangle icon:

   

3. (Optional) Change outline thickness and color:

   

4. You can draw directly on a document page. Tap where you want to place one of the corners and drag diagonally to mark the opposite corner.

5. Tap Done to finish.

In the context menu, you can delete a rectangle, add a comment, change line thickness and color. To invoke this menu, tap the rectangle and select the corresponding option. You can also resize and move the selected rectangle.

Add Rectangles Programmatically

Use the following API members to add rectangles with specified settings to a PDF doc page:

AddSquareAnnotation

Adds a rectangle with thespecified boundaries to a page with the given serial number.

PdfAnnotationOptions.AllowAddSquare

Set this property to False to disable the AddSquareAnnotation method functionality.

PdfAnnotationOptions.SquareColor

Specifies the rectangle outline color.

SquareLineWidth

Specifies the rectangle outline thickness.

SquareSubject

Defines the subject for comments assigned to rectangles.

XAML

<dx:PdfViewer.AnnotationOptions>
    <dx:PdfAnnotationOptions ...
                             SquareColor="Blue"
                             SquareLineWidth="3"
                             SquareSubject="Subject"/>
</dx:PdfViewer.AnnotationOptions>
<dx:DXButton Clicked="DXButton_Clicked" .../>

C#

private void DXButton_Clicked(object sender, EventArgs e) {
    // The origin point (0,0) is the page's bottom-left corner; coordinates are in document units.
    pdfViewer.AddSquareAnnotation(0, new PdfRectangle(left: 240, bottom: 660, right: 355, top: 700));
}

Add Ellipses

Follow the steps below to add an ellipse with the PDF viewer UI:

1. Tap the Graphics icon () in the edit toolbar.

2. Tap the Ellipse icon:

   

3. (Optional) Change outline thickness and color:

   

4. You can draw directly on a document page. Tap where you want to place an ellipse bounding rectangle corner and drag diagonally to mark the opposite corner.

5. Tap Done to finish.

In the context menu, you can delete an ellipse, add a comment, change line thickness and color. To invoke this menu, tap the ellipse and select the corresponding option. You can also resize and move the selected ellipse.

Add Ellipses Programmatically

Use the following API members to add ellipses with specified settings to a PDF doc page:

AddCircleAnnotation

Adds an ellipse with the specified boundaries to a page with the given serial number.

PdfAnnotationOptions.AllowAddCircle

Set this property to False to disable the AddCircleAnnotation method functionality.

CircleColor

Specifies the ellipse outline color.

CircleLineWidth

Defines the ellipse outline thickness.

CircleSubject

Defines the subject for comments assigned to ellipses.

XAML

<dx:PdfViewer.AnnotationOptions>
    <dx:PdfAnnotationOptions ...
                             CircleColor="Red"
                             CircleLineWidth="3"
                             CircleSubject="Subject"/>
</dx:PdfViewer.AnnotationOptions>
<dx:DXButton Clicked="DXButton_Clicked" .../>

C#

private void DXButton_Clicked(object sender, EventArgs e) {
    // The origin point (0,0) is the page's bottom-left corner; coordinates are in document units.
    pdfViewer.AddCircleAnnotation(0, new PdfRectangle(left:240, bottom:660, right:355, top:700));
}

Save Changes to the Document

The PDF Viewer does not automatically save newly added annotations to the document. To invoke the system Save File dialog to allow users to save the current document to the file system, call the PdfViewer.ShowSaveFileDialogAsync method or the PdfViewerCommands.ShowSaveFileDialog command. Users can also save documents in the Share UI. To invoke it, call the PdfViewer.ShareDocumentAsync method or the PdfViewerCommands.ShareDocument command. Call the PdfViewer.SaveDocumentAsync method to save the current document to a stream.

Respond to User Actions

Handle the following PdfViewer events to respond to user actions:

AnnotationCreating | AnnotationCreated

Occur before/after a new annotation object is added.

AnnotationChanging | AnnotationChanged

Occur before/after an annotation object property value is changed.

AnnotationDeleting | AnnotationDeleted

Occur before/after an annotation object is deleted.

Select and Navigate Through Annotations

The PDF viewer raises the AnnotationSelectionChanged event once a user selects an annotation. To obtain the selected annotation object, use the SelectedAnnotation property.

Use the following methods/commands to implement a custom navigation UI:

• PdfViewer.SelectNextAnnotation | PdfViewerCommands.SelectNextAnnotation

• PdfViewer.SelectPreviousAnnotation | PdfViewerCommands.SelectPreviousAnnotation

Users can select an annotation in Annotations view to navigate to that annotation in the document.