Working with measurements annotations

7 Oct 202024 minutes to read

Measurement annotations are used to measure the distance, area, perimeter, radius, volume of the objects present in a PDF document.The PDF viewer allows you to include the measurement annotations in a PDF document and provides options to modify or remove the existing measurement annotations. The supported measurement annotations are listed as follows.

Area
Distance
Perimeter
Radius
Volume.

Adding Measurement annotations

Enabling the Measurement annotation mode

Set the AnnotationMode of the PDF Viewer to any of the measurement annotations to enable it. Once the measurement annotation mode is set, the zooming, panning, and scrolling will be disabled. The measurement annotations can be drawn only on the currently visible pages. Refer to the following code.

C#
//Initialize the SfPdfViewer
SfPdfViewer pdfViewer = new SfPdfViewer(); 

//Setting the annotation mode to Area
pdfViewer.AnnotationMode = AnnotationMode.Area;

Disabling measurement annotation mode

Set the AnnotationMode of the PDF Viewer to None to disable the measurement annotation mode. When the measurement annotation mode is disabled, the zooming, panning, and scrolling will be enabled again.

C#
//Initialize the SfPdfViewer
SfPdfViewer pdfViewer = new SfPdfViewer(); 

//Setting the annotation mode to None
pdfViewer.AnnotationMode = AnnotationMode.None;

Detecting the inclusion of measurement annotations

The ShapeAnnotationAdded event will be raised when a measurement annotation is added to the PDF. The properties of the added measurement annotation can be retrieved from the ShapeAnnotationAddedEventArgs parameter of the event handler.

C#
//Initialize the SfPdfViewer
SfPdfViewer pdfViewer = new SfPdfViewer(); 

//Wire up the ShapeAnnotionAdded Event
pdfViewer.ShapeAnnotationAdded += PdfViewer_ShapeAnnotationAdded;

The following code shows how to retrieve the properties of the added measurement annotation.

C#
private void PdfViewer_ShapeAnnotationAdded(object sender, ShapeAnnotationAddedEventArgs args)
        {
            //Get the added measurement annotation type
            AnnotationMode annotationMode = args.AnnotationType;

            //Get the bounds of the added measurement annotation
            CGRect bounds = args.Bounds;

            //Get the page number in which the added measurement annotation is present
            int pageNumber = args.PageNumber;

            //Get the data points of the added measurement annotation
            List<CGPoint> dataPoints = args.DataPoints;

            //Get the opacity value of the added measurement annotation
            nfloat opacity = args.Opacity;            

            //Get the position of the added measurement annotation within the page
            CGPoint position = args.Position;

            //Get the stroke color of the added measurement annotation 
            UIColor strokeColor = args.StrokeColor;

            //Get the thickness of the added measurement annotation
            float thickness = args.Thickness;
        }

Detecting tap on measurement annotations

Tapping a measurement annotation selects it or deselects it if it is already selected. The ShapeAnnotationTapped event is raised when a measurement annotation is tapped. The properties of the tapped measurement annotation can be retrieved from the ShapeAnnotationTappedEventArgs parameter of the event handler.

C#
//Initialize the SfPdfViewer
SfPdfViewer pdfViewer = new SfPdfViewer(); 

//Wire up the ShapeAnnotionTapped event
pdfViewer.ShapeAnnotationTapped += PdfViewer_ShapeAnnotationTapped;

The following code shows how to retrieve the properties of the tapped measurement annotation.

C#
private void PdfViewer_ShapeAnnotationTapped(object sender, ShapeAnnotationTappedEventArgs args)
        {
            //Get the tapped measurement annotation type
            AnnotationMode annotationMode = args.AnnotationType;

            //Get the bounds of the tapped measurement annotation
            CGRect bounds = args.Bounds;

            //Get the page number in which the tapped measurement annotation is present
            int pageNumber = args.PageNumber;

            //Get the data points of the tapped measurement annotation
            List<CGPoint> dataPoints = args.DataPoints;

            //Get the opacity value of the tapped measurement annotation
            nfloat opacity = args.Opacity;

            //Get the position of the tapped measurement annotation within the page
            CGPoint position = args.Position;

            //Get the stroke color of the tapped measurement annotation 
            UIColor strokeColor = args.StrokeColor;

            //Get the thickness of the tapped measurement annotation
            float thickness = args.Thickness;
        }

Selecting Measurement annotations

You can select a measurement annotation by tapping it. When a measurement annotation is selected, the ShapeAnnotationSelected event will be raised. The properties of the selected measurement annotation can be retrieved from the ShapeAnnotationSelectedEventArgs parameter of the event handler.

C#
//Initialize the SfPdfViewer
SfPdfViewer pdfViewer = new SfPdfViewer();

//Wire up the ShapeAnnotionSelected event
pdfViewer.ShapeAnnotationSelected += PdfViewer_ShapeAnnotationSelected;

The following code shows how to retrieve the properties of the selected measurement annotation.

C#
private void PdfViewer_ShapeAnnotationSelected(object sender, ShapeAnnotationSelectedEventArgs args)
        {
            //Get the selected measurement annotation type
            AnnotationMode annotationMode = args.AnnotationType;

            //Get the bounds of the selected measurement annotation
            CGRect bounds = args.Bounds;

            //Get the page number in which the selected measurement annotation is present
            int pageNumber = args.PageNumber;

            //Gets the list of other annotations that overlap the selected annotation
            System.Collections.Generic.List<IAnnotation> overlappedAnnotation = args.OverlappedAnnotations;
        }

Deselecting measurement annotations

You can deselect a selected measurement annotation by tapping on it or somewhere else on the PDF page. Deselection can be detected using the ShapeAnnotationDeselected event. The properties of the deselected measurement annotation can be retrieved from the ShapeAnnotationDeselectedEventArgs parameter of the event handler.

C#
//Initialize the SfPdfViewer
SfPdfViewer pdfViewer = new SfPdfViewer(); 

//Wire up the ShapeAnnotionDeselected Event
pdfViewer.ShapeAnnotationDeselected = PdfViewer_ShapeAnnotationDeselected;

The following code shows how to retrieve the properties of the deselected measurement annotation.

C#
private void PdfViewer_ShapeAnnotationDeselected(object sender, ShapeAnnotationDeselectedEventArgs args)
        {
            //Get the deselected measurement annotation type
            AnnotationMode annotationType = args.AnnotationType;

            //Retrieves the bounds of the deselected measurement annotation. 
            CGRect bounds = args.Bounds;

            //Retrieves the page number where the deselected measurement annotation resides. 
            int page = args.PageNumber;
        }

Moving or resizing the selected measurement annotation

To move or resize the measurement annotation it should be selected. After the appearance of the selector, tapping and dragging anywhere inside the selector will move the measurement annotation. Tapping on the bubbles around the selector and dragging would resize the measurement annotation.

Detecting the move or resize of a measurement Annotation

The AnnotationMovedOrResized event will be raised when you move or resize the selected annotation. The properties of the moved or re-sized measurement annotation can be retrieved from the AnnotationMovedOrResizedEventArgs parameter of the event handler.

C#
//Initialize the SfPdfViewer
SfPdfViewer pdfViewer = new SfPdfViewer(); 

//Wire up the AnnotationMovedOrResized event
pdfViewer.AnnotationMovedOrResized = PdfViewer_AnnotationMovedOrResized;

The following code shows how to retrieve the properties of the moved or re-sized measurement annotation.

C#
private void PdfViewer_AnnotationMovedOrResized(object sender, AnnotationMovedOrResizedEventArgs args)
        {
            //Determine whether the moved or resized annotation is a measurement annotation or some other annotation. 
            if (sender as AreaAnnotation != null)
            {
                //The annotation is an area annotation 
            }
            else
            {
                //The annotation is not an area annotation
            }

            //Retrieve the old bounds of the measurement annotation
            CGRect oldBounds = args.OldBounds;

            //Retrieve the new bounds of the measurement annotation 
            CGRect newBounds = args.NewBounds;

            //Get the page number in which the measurement annotation is moved or re-sized
            int pageNumber = args.PageNumber;

            //Get the opacity value of the measurement annotation
            nfloat opacity = args.Opacity;

            //Get the color of the measurement annotation
            UIColor color = args.Color;

            //Get the thickness of the measurement annotation
            float thickness = args.Thickness;
        }

Deleting the measurement annotations

The PDF Viewer allows you to remove a selected annotation or all the annotations in the PDF document.

Removing a selected annotation

The following code sample shows how to remove the selected area measurement annotation from the PDF document.

C#
AreaAnnotation areaAnnotation; 
private void PdfViewer_ShapeAnnotationSelected(object sender, ShapeAnnotationSelectedEventArgs args)
        {
            //Cast the sender object as area annotation. 
            areaAnnotation = sender as AreaAnnotation;
        }

private void deleteShapeAnnotationButton_Clicked(object sender, EventArgs e)
        {
            //Delete the area annotation 
            pdfViewer.RemoveAnnotation(areaAnnotation);
        }

Detecting the removal of a measurement Annotation

The ShapeAnnotationRemoved event will be raised when a measurement annotation is removed from the PDF.

C#
//Initialize the SfPdfViewer
SfPdfViewer pdfViewer = new SfPdfViewer(); 

//Wire up the ShapeAnnotionRemoved Event
pdfViewer.ShapeAnnotationRemoved = PdfViewer_ShapeAnnotationRemoved;

The properties of the removed measurement annotation can be retrieved from the ShapeAnnotationRemovedEventArgs parameter of the event handler.

C#
private void PdfViewerControl_ShapeAnnotationRemoved(object sender, ShapeAnnotationRemovedEventArgs args)
        {
            //Get the removed measurement annotation type
            AnnotationMode annotationMode = args.AnnotationType;

            //Get the bounds of the removed measurement annotation
            CGRect bounds = args.Bounds;

            //Get the data points of the removed measurement annotation
            List<CGPoint> dataPoints = args.DataPoints;

            //Get the page number in which the removed measurement annotation was present
            int pageNumber = args.PageNumber;
        }

Customizing the appearance of Measurement annotations

You can customize the default values of stroke color , opacity, maximum height, minimum height, maximum width, minimum width, display text, text background color, text color, text opacity, text size, interaction (locked), thickness, and fill color of the measurement annotations that are to be added.

NOTE

This will not affect the measurement annotations that were already added.

The following is the list of properties applicable to customize the appearance of the measurement annotations,

Properties	Area	Volume	Distance	Radius	Perimeter
Stroke Color	Yes	Yes	Yes	Yes	Yes
opacity	Yes	Yes	Yes	Yes	Yes
Fill color	Yes	Yes	Yes	Yes	Yes
Thickness	Yes	Yes	Yes	Yes	Yes
Text	Yes	Yes	Yes	Yes	Yes
Text color	Yes	Yes	Yes	Yes	Yes
Text background-color	Yes	Yes	Yes	Yes	Yes
Text opacity	Yes	Yes	Yes	Yes	Yes
Text size	Yes	Yes	Yes	Yes	Yes
Minimum height	Yes	Yes	Yes	Yes	Yes
Minimum width	Yes	Yes	Yes	Yes	Yes
Maximum height	Yes	Yes	Yes	Yes	Yes
Maximum width	Yes	Yes	Yes	Yes	Yes
Maximum width	Yes	Yes	Yes	Yes	Yes
Is Locked	Yes	Yes	Yes	Yes	Yes
End style	No	No	Yes	No	No
Begin style	No	No	Yes	No	No
Leader extension	No	No	Yes	No	No
LineCap position	No	No	Yes	No	No
Leader length	No	No	Yes	No	No
Depth	No	Yes	No	No	No
IsAutoCloseEnabled	No	No	No	No	Yes

NOTE

The following properties are common to all the Measurement annotations. In all code samples, the Area measurement annotation is used for illustration purposes.

Setting the default stroke color

You can set the default stroke color for the measurement annotations by using the StrokeColor property. Refer to the following code example.

C#
//Initialize the SfPdfViewer
SfPdfViewer pdfViewer = new SfPdfViewer(); 

//Setting the stroke color for area measurement annotation
pdfViewer.MeasurementSettings.Area.StrokeColor = UIColor.Red;

Setting the default opacity

You can set the default opacity for the measurement annotations by using the Opacity property. The opacity value ranges from 0 to 1. Refer to the following code example.

C#
//Initialize the SfPdfViewer
SfPdfViewer pdfViewer = new SfPdfViewer(); 

//Setting the opacity for area measurement 
annotationpdfViewer.MeasurementSettings.Area.Opacity = 0.5f;

Setting the default fill color

You can set the default fill color for the measurement annotations by using the FillColor property. Refer to the following code example.

C#
//Initialize the SfPdfViewer
SfPdfViewer pdfViewer = new SfPdfViewer(); 

//Setting the fill color for area measurement annotation
pdfViewer.MeasurementSettings.Area.FillColor = UIColor.Blue;

Setting the default thickness

You can set the thickness for the measurement annotations by using the Thickness property. Refer to the following code example.

C#
//Initialize the SfPdfViewer
SfPdfViewer pdfViewer = new SfPdfViewer(); 

//Setting thickness for the area measurement annotation
pdfViewer.MeasurementSettings.Area.Thickness = 5;

Setting the default text

You can set the text for the measurement annotations by using the Text property. Refer to the following code example.

C#
//Initialize the SfPdfViewer
SfPdfViewer pdfViewer = new SfPdfViewer(); 

//Setting the text for area measurement annotation
pdfViewer.MeasurementSettings.Area.Text = ?Area?;

Setting the default text background color

You can set the background color for the text assigned to the measurement annotations by using the TextBackgroundColor property. Refer to the following code example.

C#
//Initialize the SfPdfViewer
SfPdfViewer pdfViewer = new SfPdfViewer(); 

//Setting the text background color for area measurement annotation
pdfViewer.MeasurementSettings.Area.TextBackgroundColor = UIColor.Black

Setting the default text color

You can set the color for the text assigned to the measurement annotations by using the TextColor property. Refer to the following code example.

C#
//Initialize the SfPdfViewer
SfPdfViewer pdfViewer = new SfPdfViewer(); 

//Setting the text color for area measurement annotation
pdfViewer.MeasurementSettings.Area.TextColor = UIColor.Black;

Setting the default text opacity

You can set the opacity for the text assigned to the measurement annotations by using the TextOpacity property. Refer to the following code example.

C#
//Initialize the SfPdfViewer
SfPdfViewer pdfViewer = new SfPdfViewer(); 

//Setting the text opacity for area measurement annotation
pdfViewer.MeasurementSettings.Area.TextOpacity = 0.5f;

Setting the default text size

You can set the size for the text assigned to the measurement annotations by using the TextSize property. Refer to the following code example.

C#
//Initialize the SfPdfViewer
SfPdfViewer pdfViewer = new SfPdfViewer(); 

//Setting the text size for area measurement annotation
pdfViewer.MeasurementSettings.Area.TextSize = 2;

Setting the default minimum height

You can set the minimum height for the measurement annotations by using the MinimumHeight property. Refer to the following code example.

C#
//Initialize the SfPdfViewer
SfPdfViewer pdfViewer = new SfPdfViewer(); 

//Setting the minimum height for area measurement annotation
pdfViewer.MeasurementSettings.Area.MinimumHeight = 20;

Setting the default minimum width

You can set the minimum width for the measurement annotations by using the MinimumWidth property. Refer to the following code example.

C#
//Initialize the SfPdfViewer
SfPdfViewer pdfViewer = new SfPdfViewer(); 

//Setting the minimum width for area measurement annotation
pdfViewer.MeasurementSettings.Area.MinimumWidth = 20;

Setting the default maximum height

You can set the maximum height for the measurement annotations by using the MaximumHeight property. Refer to the following code example.

C#
//Initialize the SfPdfViewer
SfPdfViewer pdfViewer = new SfPdfViewer(); 

//Setting the maximum height for area measurement annotation
pdfViewer.MeasurementSettings.Area.MaximumHeight = 60;

Setting the default maximum width

You can set the maximum width for the measurement annotations by using the MaximumWidth property. Refer to the following code example.

C#
//Initialize the SfPdfViewer
SfPdfViewer pdfViewer = new SfPdfViewer(); 

//Setting the maximum width for area measurement annotation
pdfViewer.MeasurementSettings.Area.MaximumWidth = 60;

Customizing the default appearance which is specific to the Distance Annotation

You can customize the default values of the begin style, end style, leader extension, leader length, and line cap position of the distance Annotation to be added.

NOTE

This will not affect the already added distance annotations.

You can set the begin style for the distance measurement annotations using the BeginStyle property. The BeginStyle is an enum property with values Round, Closed, Diamond, None, Open, and Square.