Working with free text annotations

17 Mar 202215 minutes to read

PDF viewer allows you to include free text annotations in a PDF document and provides options to modify or remove the existing ones.

Adding free text annotations using toolbar

Enabling free text annotation mode

Set the AnnotationMode property of the PDF viewer to FreeText. After setting the annotation mode, tap any PDF page and a popup will appear. Zooming, panning and scrolling will be disabled. Type the text in the popup and click "OK" to add the typed text to the page. Zooming, panning, and scrolling will be enabled again if the free text annotation is added.

SfPdfViewer pdfViewer = new SfPdfViewer();
pdfViewer.AnnotationMode = AnnotationMode.FreeText;

Disabling free text annotation mode

Setting the annotation mode to None disables the free text mode.

SfPdfViewer pdfViewer = new SfPdfViewer();
pdfViewer.AnnotationMode = AnnotationMode.None;

Detecting the inclusion of free text annotations

The event FreeTextAnnotationAdded will be raised when a free text annotation is added to the PDF.

SfPdfViewer pdfViewer = new SfPdfViewer();
pdfViewer.FreeTextAnnotationAdded += PdfViewer_FreeTextAnnotationAdded;

Adding free text annotations programmatically

By AddAnnotation method , You can add the free text annotations programmatically. The created free text annotation object passed as a parameter. The FreeTextAnnotation instance acquires the text, page number and bounds as the parameters.

The following code sample illustrates the same.

string text = "Syncfusion";
           
//Creates the free text annotation
FreeTextAnnotation freeTextAnnotation = new FreeTextAnnotation(text, 1, new Rectangle(100, 100, 100, 50));           

//Add the free text annotation to the specified page 
pdfViewer.AddAnnotation(freeTextAnnotation);

Detecting tap on free text annotations

Tapping a free text annotation selects it or deselects if it is already selected. The event FreeTextAnnotationTapped is raised when a free text is tapped.

SfPdfViewer pdfViewer = new SfPdfViewer();
pdfViewer.FreeTextAnnotationTapped += PdfViewer_FreeTextAnnotationTapped;

Selecting free text annotations

You can select a free text annotation by tapping it. When a free text is selected, the FreeTextAnnotationSelected event will be raised.

SfPdfViewer pdfViewer = new SfPdfViewer();
pdfViewer.FreeTextAnnotationSelected += PdfViewer_FreeTextAnnotationSelected;

When the event is raised, the properties of the selected free text can be obtained from the args parameter of the event handler.

private void PdfViewer_FreeTextAnnotationSelected(object sender, FreeTextAnnotationSelectedEventArgs args)
{
	//Obtain the bounds of the annotation
	CGRect bounds = args.Bounds;

	//Obtain the text in the annotation
	string text = args.Text;

	//Obtain the size of the text in the annotation
	float textSize = args.TextSize;

	//Obtain the color of the text
	UIColor textColor = args.TextColor;

	//Obtain the page number in which the selected annotation is
	int pageNumber = args.PageNumber;
}

Selecting free text annotation programmatically

By SelectAnnotation method, You can select the free text annotation programmatically. The specified free text annotation object passed as a parameter.

The following code sample illustrates the same.

//Selects the specified free text annotation
pdfViewer.SelectAnnotation(freetextAnnotation);

NOTE

Once SelectAnnotation method is called and as long as the annotation stays selected, the SelectedAnnotation property will return the same instance as the parameter of this method.

Deselecting free text annotations

You can deselect a selected free text annotation by tapping on it or somewhere else on the PDF page. Deselection can be detected using the FreeTextAnnotationDeselected event.

SfPdfViewer pdfViewer = new SfPdfViewer();
pdfViewer.FreeTextAnnotationDeselected += PdfViewer_FreeTextAnnotationDeselected;

Deselecting free text annotation programmatically?

By DeselectAnnotation method, You can deselect the free text annotation. The specified free text annotation object passed as a parameter.

The following code sample illustrates the same.

//Deselects the specified free text annotation 
pdfViewer.DeselectAnnotation(freetextAnnotation);

NOTE

There is no effect in calling DeselectAnnotation method, if the given annotation is not selected. Once this method is called, the SelectedAnnotation property will return null until any other annotation gets selected.

Customizing the appearance of free text annotations

You can customize the default values of opacity, display text, text color, text size, maximum height, minimum height, maximum width, minimum width, minimum size, interaction (locked), and dialog of the free text annotations that are to be added. This will not affect the free text annotations that were already added.

Setting the default opacity

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

//Setting the opacity for the free text annotation 
pdfViewer.AnnotationSettings.FreeText.Opacity = 0.5f;

Setting the default text

You can set the text for the free text annotations by using the SfPdfViewer.AnnotationSettings.FreeText.Text property. Refer to the following code example.

//Setting the text for the free text annotation
pdfViewer.AnnotationSettings.FreeText.Text = "Syncfusion";

Setting the default text color

You can set the color for the text assigned to the free text annotations by using the SfPdfViewer.AnnotationSettings.FreeText.TextColor property. Refer to the following code example.

//Setting the text color for the free text annotation
pdfViewer.AnnotationSettings.FreeText.TextColor = UIColor.Black;

Setting the default text size

You can set the size for the text assigned to the free text annotations by using the SfPdfViewer.AnnotationSettings.FreeText.TextSize property. Refer to the following code example.

//Setting the text size for the free text annotation
pdfViewer.AnnotationSettings.FreeText.TextSize = 2;

Setting the default background-color

You can set the background color for the free text annotations using the SfPdfViewer.AnnotationSettings.FreeText.FillColor property. The default value is set to UIColor.Clear.

//Setting the background color of the free text annotation

pdfViewerControl.AnnotationSettings.FreeText.FillColor = UIColor.Blue;

Setting the default minimum size

By the SfPdfViewer.AnnotationSettings.FreeText.MinimumSize property, You can set the minimum size to which the free text annotations could be resized.

Refer the following code example:

//Sets the minimum size for the free text annotations
pdfViewerControl.AnnotationSettings.FreeText.MinimumSize = new CGSize(10, 10);

Setting the default minimum height

You can set the minimum height for the free text annotations by using the SfPdfViewer.AnnotationSettings.FreeText.MinimumHeight property. Refer to the following code example.

//Setting the minimum height for the free text annotation
pdfViewer.AnnotationSettings.FreeText.MinimumHeight = 20;

NOTE

The MinimumHeight property have been marked as obsolete. Use the MinimumSize property instead.

Setting the default minimum width

You can set the minimum width for the free text annotations by using the SfPdfViewer.AnnotationSettings.FreeText.MinimumWidth property. Refer to the following code example.

//Setting the minimum width for the free text annotation
pdfViewer.AnnotationSettings.FreeText.MinimumWidth = 20;

NOTE

The MinimumWidth property have been marked as obsolete. Use the MinimumSize property instead.

Setting the default maximum height

You can set the maximum height for the free text annotations by using the SfPdfViewer.AnnotationSettings.FreeText.MaximumHeight property. Refer to the following code example.

//Setting the maximum height for the free text annotation
pdfViewer.AnnotationSettings.FreeText.MaximumHeight = 60;

Setting the default maximum width

You can set the maximum width for the free text annotations by using the SfPdfViewer.AnnotationSettings.FreeText.MaximumWidth property. Refer to the following code example.

//Setting the maximum width for the free text annotation
pdfViewer.AnnotationSettings.FreeText.MaximumWidth = 60;

Changing the properties of a selected free text

You can change the properties of the selected annotation by casting the sender parameter of the FreeTextAnnotationSelected event handler to FreeTextAnnotation and modifying its properties. The following code shows how to change the properties.

SfPdfViewer pdfViewer = new SfPdfViewer();
pdfViewer.FreeTextAnnotationSelected += PdfViewer_FreeTextAnnotationSelected;
changeFreeTextPropertiesButton.TouchUpInside += ChangeFreeTextPropertiesButton_TouchUpInside;
FreeTextAnnotation selectedFreeTextAnnotation;

private void PdfViewer_FreeTextAnnotationSelected(object sender, FreeTextAnnotationSelectedEventArgs args)
{
	//Cast the sender object to free text annotation
	selectedFreeTextAnnotation = sender as FreeTextAnnotation;
}

private void ChangeFreeTextPropertiesButton_TouchUpInside(object sender, EventArgs e)
{
	//Change the color of the text
    selectedFreeTextAnnotation.Settings.TextColor = UIColor.Purple;

    //Change the size of the text
    selectedFreeTextAnnotation.Settings.TextSize = 6;
}

Moving or resizing free text annotations

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

Detecting the move or resize of a free text

The event FreeTextAnnotationMovedOrResized will be raised when you move or resize the selected annotation.

SfPdfViewer pdfViewer = new SfPdfViewer();
pdfViewer.FreeTextAnnotationMovedOrResized += PdfViewer_FreeTextAnnotationMovedOrResized;

The properties of the moved or resized free text can be obtained from the args parameter of the event handler.

private void PdfViewer_FreeTextAnnotationMovedOrResized(object sender, FreeTextAnnotationMovedOrResizedEventArgs args)
{
	//Retrieve the old bounds of the annotation
	CGRect oldBounds = args.OldBounds;

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

	//Retrieve the current page number
	int pageNumber = args.PageNumber;
}

Deleting free text annotations

The PDF viewer can remove a selected annotation or all the annotations in the PDF document.

Removing a selected free text annotation.

The following code snippet illustrates removing a selected free text from the PDF document.

FreeTextAnnotation selectedFreeTextAnnotation;

private void PdfViewer_FreeTextAnnotationSelected(object sender, FreeTextAnnotationSelectedEventArgs args)
{
	//Cast the sender object to free text annotation.
	selectedFreeTextAnnotation = sender as FreeTextAnnotation;
}

private void deleteFreeTextAnnotationButton_Clicked(object sender, EventArgs e)
{
	//Delete the selected free text annotation
	pdfViewer.RemoveAnnotation(selectedFreeTextAnnotation);
}

Removing all annotations

The ClearAllAnnotations method can be used to delete all annotations irrespective of their types from the PDF.

pdfViewer.ClearAllAnnotations();

Detecting the removal of a free text

The event FreeTextAnnotationRemoved will be raised when a free text annotation is removed from the PDF.

SfPdfViewer pdfViewer = new SfPdfViewer();
pdfViewer.FreeTextAnnotationRemoved += PdfViewer_FreeTextAnnotationRemoved;

The properties of the removed free text can be obtained from the args parameter of the event handler.

private void PdfViewerControl_FreeTextAnnotationRemoved(object sender, FreeTextAnnotationRemovedEventArgs args)
{
	//Get the bounds 
	CGRect bounds = args.Bounds;
	//Get the page number on which the deselected free text is 
	int pageNumber = args.PageNumber;
	//Get the text of the free text annotation 
	string text = args.Text;
	//Get the text color 
	UIColor textColor = args.TextColor;
	//Get the text size 
	float textSize = args.TextSize;

}

How to enable or disable the free text dialog

The free text dialog (for adding the free text annotation) can be enabled or disabled by setting the IsFreeTextDialogEnabled API to true or false respectively. The default value is set to true.

//Disable the free text dialog
pdfViewer.AnnotationSettings.FreeText.IsFreeTextDialogEnabled = false;

How to lock or unlock the free text annotations?

To lock or unlock all the free text annotation, set the IsLocked API to true or false respectively, and the following sample explains the same. But other annotation types can be moved, resized, removed or their attributes can be changed.

//Disable the free text annotation interaction such as move, resize, remove, and attributes changes.
pdfViewerControl.AnnotationSettings.FreeText.IsLocked = true;

Interactions with free text annotation types such as move, resize, remove or attribute changes will be allowed only if the SfPdfViewer.AnnotationSettings.IsLocked API is set to false. The following code prevents the unlocking of the free text annotations, although the IsLocked property of the free text annotation is set to false.

//Disable the free text annotation interaction, though its 'IsLocked' property is set to ‘false’ .
pdfViewerControl.AnnotationSettings.IsLocked = true;
pdfViewerControl.AnnotationSettings.FreeText.IsLocked = false;

How to enable or disable the free text annotation selection?

To enable or disable the free text annotation selection, set the Constraints API to AnnotationConstraints.Selectable or ~AnnotationConstraints.Selectable respectively, and the following sample explains the same. But other annotation types can be selected, moved, resized, removed or their attributes can be changed.

//Disable the selection of free text annotations.
pdfViewerControl.AnnotationSettings.FreeText.Constraints = ~AnnotationConstraints.Selectable;

Free text annotation selection will be allowed only if the SfPdfViewer.AnnotationSettings.Constraints API is set to AnnotationConstraints.Selectable. The following code prevents the free text annotations selection, even though the Constraints property of the free text annotation is set to AnnotationConstraints.Selectable.

//Disable the free text annotation selection, though its 'Constraints' property is set to ‘AnnotationConstraints.Selectable’ 
pdfViewerControl.AnnotationSettings.Constraints= ~AnnotationConstraints.Selectable;
pdfViewerControl.AnnotationSettings.FreeText.Constraints = AnnotationConstraints.Selectable;

How to get and set the name of the free text annotations?

The PDF Viewer allows the users to get and set the name of free text annotations through the Name API.

The following code sample explains modifying the name of the free text annotation in the FreeTextAnnotationAdded event.

private void PdfViewerControl_ FreeTextAnnotationAdded (object sender, FreeTextAnnotationAddedEventArgs args)
{
//Sets the name for the annotation.
(sender as FreeTextAnnotation).Name = "FreeText1";           
}

NOTE

For illustration purposes, we have only provided the sample for modifying the name of the free text annotation in the FreeTextAnnotationAdded event. But this can be done in all other events as well.