Add Annotations in the DevExpress PDF Viewer for .NET MAUI

• Mar 28, 2024
• 5 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 adds a new annotation, the PDF Viewer control re-sorts the Annotations collection to insert this annotation 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 Comments view. The IsCommentsViewOpened property indicates whether Comments view is currently expanded. You can call the PdfViewerCommands.ToggleComments command to open Comments view.

Add Sticky Notes

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

<dxp:PdfViewer.AnnotationOptions>
    <dxp:PdfAnnotationOptions ...
                              StickyNoteColor="Beige"
                              StickyNoteSubject="Note"/>
</dxp: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

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 also disables the AddFreeTextAnnotation method functionality.

PdfAnnotationOptions.FreeTextColor

Specifies the text color.

PdfAnnotationOptions.FreeTextFontSize

Specifies the text font size.

PdfAnnotationOptions.FreeTextSubject

Specifies the subject for comments assigned to free text annotations.

XAML

<dxp:PdfViewer.AnnotationOptions>
    <dxp:PdfAnnotationOptions ...
                              FreeTextColor="Blue"
                              FreeTextFontSize="10"
                              FreeTextSubject="Subject"/>
</dxp: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

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 the ink line thickness.

PdfAnnotationOptions.InkSubject

Specifies the subject for comments assigned to drawing annotations.

XAML

<dxp:PdfViewer.AnnotationOptions>
    <dxp:PdfAnnotationOptions ...
                              InkColor="Green"
                              InkLineWidth="2"
                              InkSubject="Ink drawing"/>
</dxp: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

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

AddSquareAnnotation

Adds a rectangle with the specified 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

<dxp:PdfViewer.AnnotationOptions>
    <dxp:PdfAnnotationOptions ...
                              SquareColor="Blue"
                              SquareLineWidth="3"
                              SquareSubject="Subject"/>
</dxp: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

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

<dxp:PdfViewer.AnnotationOptions>
    <dxp:PdfAnnotationOptions ...
                              CircleColor="Red"
                              CircleLineWidth="3"
                              CircleSubject="Subject"/>
</dxp: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. Users can save documents in the Share UI. To invoke it, call the PdfViewer.ShareDocumentAsync() method or the PdfViewerCommands.ShareDocument command.

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.

AnnotationDeleted | AnnotationDeleting

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 Comments view to navigate to that annotation in the document.