Ink annotation in .NET MAUI PDF Viewer (SfPdfViewer)

24 Jun 20247 minutes to read

The ink annotation feature of SfPdfViewer allows you to add, remove and modify free hand drawings (ink) in the PDF document. This is useful for making corrections or emphasizing important points in the document. This section will go through the various functions available in the SfPdfViewer for working with ink annotations.

Add ink annotations

This section will cover how to add ink annotations to a PDF document using a toolbar as well as programmatically.

Add ink annotation using toolbar

On the built-in toolbar, an ink annotation tool is available. Using that, you can add ink annotations by drawing on the PDF document. Additionally, the toolbar shows the option to modify the properties of existing or new ink annotations.

The following image represents how to add the ink annotations using the toolbar on the desktop.

Ink annotation desktop

The following image represents how to add the ink annotations using the toolbar on mobile.

Ink annotation mobile

Add ink annotation without using toolbar

You can draw and add ink annotations to a PDF document with UI interaction using touch or mouse. The following steps explains how to draw ink annotation on a PDF.

  1. Set the AnnotationMode property of the SfPdfViewer to Ink. It activates the ink drawing mode on the control.
  2. Place your finger (or mouse) on the screen, where you want to start drawing the ink stroke.
  3. Draw the stroke by dragging the finger (or cursor) across the screen.
  4. Finish the stroke by releasing the finger (or cursor).
  5. Repeat the steps 2-4, if you want to create multiple strokes on other areas during the ink drawing mode.
  6. Once you have done, set the AnnotationMode to None. It will disable the drawing mode and save the drawn strokes to the PDF page as a single ink annotation.
  7. You can later move, resize, or edit the annotation.

The following code explains how to enable the ink annotation mode.

// Enable or activate the ink drawing mode.
void EnableInkDrawingMode()
{
    // Set the annotation mode to ink using the [SfPdfViewer](https://help.syncfusion.com/cr/maui/Syncfusion.Maui.PdfViewer.SfPdfViewer.html) instance.
    PdfViewer.AnnotationMode = AnnotationMode.Ink;
}

Similarly, refer to following code to disable the ink annotation mode.

// Disable or deactivate the ink drawing mode.
void DisableInkDrawingMode()
{
    // Set the annotation mode to none using the [SfPdfViewer](https://help.syncfusion.com/cr/maui/Syncfusion.Maui.PdfViewer.SfPdfViewer.html) instance.
    PdfViewer.AnnotationMode = AnnotationMode.None;
}

Add ink annotations programmatically

You can create and add an ink annotation to a PDF document programmatically using the AddAnnotation method of the SfPdfViewer. The following example explains how to create an ink annotation and add it to the first page of a PDF document.

// Create an ink annotation
InkAnnotation CreateInkAnnotation()
{
    int pageNumber = 1;
    
    // Provide the points collection to draw a stroke. Here a single stroke is created.
    List<List<float>> pointsCollection = new List<List<float>>()
    {
        new List<float> { 40, 300, 60, 100, 40, 50, 40, 300 }
    };

    // Create an ink annotation.
    InkAnnotation annotation = new InkAnnotation(pointsCollection, pageNumber);

    // Set the appearance for the ink annotation.
    annotation.Color = Colors.Red; //Stroke color
    annotation.BorderWidth = 2; //Stroke thickness.
    annotation.Opacity = 0.75f; // 75% opacity

    // return the annotation.
    return annotation;
}

void AddInkAnnotation()
{
    Annotation inkAnnotation = CreateInkAnnotation();

    // Add the ink annotation to the PDF document using `AddAnnotation` method of the `SfPdfViewer` instance.
    PdfViewer.AddAnnotation(inkAnnotation);
}

Annotation settings

In the ink annotation mode, the ink annotation will be drawn with a default appearance and behavior. You can modify the annotation after it has been added to the pages. However, if you need to define the appearance and behavior before drawing on the document, you can change its default settings using the AnnotationSettings property of the SfPdfViewer.

Customize the default appearance

You can customize the default appearance of ink annotation using the InkAnnotationSettings. The following example explains how to obtain the default ink annotation settings and modify its appearance properties. Similarly, you can modify other available properties also.

void CustomizeDefaultInkSettings()
{
    // Obtain the default ink annotation settings from the [SfPdfViewer](https://help.syncfusion.com/cr/maui/Syncfusion.Maui.PdfViewer.SfPdfViewer.html) instance.
    InkAnnotationSettings inkSettings = PdfViewer.AnnotationSettings.Ink;

    // Modify the default appearance properties
    inkSettings.Color = Colors.Blue; // Stroke color
    inkSettings.BorderWidth = 2; // Stroke thickness
    inkSettings.Opacity = 0.75f; // 75% opacity
}

Consider each stroke as a separate ink annotation

When drawing ink annotations on a PDF document interactively, all the strokes that are created during a session are treated as a single ink annotation. The session here refers to the duration between enabling and disabling the ink drawing mode. However, if you wish to consider each stroke as an individual ink annotation, set the AggregateInkStrokes property of the default ink annotation settings to false. This allows you to access and modify individual strokes. The following example explains how to access the default ink annotation settings and set the property to false.

void DisableAggregateInkStrokes()
{
    // Obtain the default ink annotation settings from the [SfPdfViewer](https://help.syncfusion.com/cr/maui/Syncfusion.Maui.PdfViewer.SfPdfViewer.html) instance.
    InkAnnotationSettings inkSettings = PdfViewer.AnnotationSettings.Ink;

    // Disable aggregating the insk strokes
    inkSettings.AggregateInkStrokes = false;
}

How to draw ink annotation only using stylus

The ink annotation operation can be customized so that the ink strokes can be added only using a stylus by setting the AnnotationSettings.Ink.TouchScreenInputMode property to TouchScreenInputMode.Stylus. When TouchScreenInputMode is set to TouchScreenInputMode.Stylus, users can easily draw ink strokes using a stylus. However, zooming and scrolling functionality will still be available using their fingers.

By default, the TouchScreenInputMode property is set to TouchScreenInputMode.FingerAndStylus, where both finger and stylus inputs are recognized as ink operations.

PdfViewer.AnnotationSettings.Ink.TouchScreenInputMode = TouchScreenInputMode.Stylus;

NOTE

  • At present, this feature is available only in iOS and Android.

Edit the selected ink annotation

You can edit the properties of the selected ink annotation programmatically by accessing the selected annotation instance. The selected annotation instance may be obtained from the AnnotationSelected event. The following example shows how to edit some of the properties of the selected ink annotation. Similar you can modify the other properties.

/// <summary>
/// Edit the selected ink annotation.
/// </summary>
/// <param name="selectedAnnotation">The selected annotation instance that may be obtained from the annotation selected event</param>
void EditSelectedInkAnnotation(Annotation selectedAnnotation)
{
    // Type cast the selected annotation as ink annotation.
    if(selectedAnnotation is InkAnnotation inkAnnotation)
    {
        inkAnnotation.Color = Colors.Blue; // Change the color to blue.
        inkAnnotation.BorderWidth = 1; // Change the stroke thickness to 1.
        inkAnnotation.Opacity = 0.75f; // Change the opacity to 75%.
    }
}