Introduction to Annotations


Annotation support of PSPDFKit

PSPDFKit supports all common annotation types:

These are the standard annotations (as defined in the PDF Reference) that can be read and written by many apps like Adobe Acrobat or even Apple's Preview.app. Most of these annotation types can also be written back, with the exception of RichMedia/Video/File and Widget.

Working with annotations in code

You can work with all supported annotations not only in our UI but in code as well. We have API for getting, setting, modifying, removing and a lot more operations regarding annotations.

To get all annotations on a certain document page, you can call annotationsForPageAtIndex:type

Copy
1
2
// Get all annotations on the first page
let annotations = document.annotationsForPage(at: 0, type: .all)
Copy
1
2
// Get all annotations on the first page
NSArray<__kindof PSPDFAnnotation *> *annotations = [document annotationsForPageAtIndex:0 type:PSPDFAnnotationTypeAll]

Creating annotation

You can instantiate annotations with their corresponding classes, which all are subclasses of the base PSPDFAnnotation class.

Copy
1
2
3
4
5
6
// Create a free text annotation
let freeTextAnnotation = PSPDFFreeTextAnnotation()
freeTextAnnotation.contents = "This is a Free Text Annotation."
freeTextAnnotation.fontSize = 20
freeTextAnnotation.boundingBox = CGRect(x: 200, y: 200, width: 200, height: 200)
freeTextAnnotation.pageIndex = 0
Copy
1
2
3
4
5
6
// Create a free text annotation
PSPDFFreeTextAnnotation *freeTextAnnotation = [[PSPDFFreeTextAnnotation alloc] init];
freeTextAnnotation.contents = @"This is a Free Text Annotation.";
freeTextAnnotation.fontSize = 20.f;
freeTextAnnotation.boundingBox = CGRectMake(200.f, 200.f, 200.f, 200.f);
freeTextAnnotation.pageIndex = 0;

For a more detailed guide also see: Programmatically creating annotations

Adding and removing annotations

To add annotations on a document page, you can use addAnnotations:options: on PSPDFDocument. You can also remove annotations on the document with removeAnnotations:options:.

Copy
1
2
3
4
5
// Add annotation to document
document.add([freeTextAnnotation])

// Remove annotation from document
document.remove([freeTextAnnotation])
Copy
1
2
3
4
5
// Add annotation to document
[document addAnnotations:@[freeTextAnnotation] options:nil];

// Remove annotation from document
[document removeAnnotations:@[freeTextAnnotation] options:nil];

You can also remove all annotations from a document by using allAnnotationsOfType: and removeAnnotations:options:. Note: You usually don't want to remove links and form elements, which are also annotations. These annotation types can be excluded, as seen in the code snippet below.

Copy
1
2
3
4
5
6
7
var annotationTypes = PSPDFAnnotationType.all
annotationTypes.remove([.link, .widget])
let allAnnotationsDictionary = document.allAnnotations(of: annotationTypes)
let allAnnotations = allAnnotationsDictionary.flatMap { key, value in
    return value
}
document.remove(allAnnotations)
Copy
1
2
3
4
5
6
7
NSDictionary *allAnnotationsDictionary = [document allAnnotationsOfType:PSPDFAnnotationTypeAll & ~(PSPDFAnnotationTypeLink|PSPDFAnnotationTypeWidget)];

NSMutableArray *allAnnotations = [NSMutableArray array];
[allAnnotationsDictionary enumerateKeysAndObjectsUsingBlock: ^(NSNumber *key, NSArray *value, BOOL *stop) {
    [allAnnotations addObjectsFromArray:value];
}];
[document removeAnnotations:allAnnotations options:nil];

Saving annotations with PSPDFKit

Annotations can only be written back into the PDF if the file is writeable. The default location (App Bundle) is readonly. Copy the PDF into your Documents folder (see the example "Test PDF annotation writing" in PSPDFCatalog).

Optionally and as a fallback, annotations can also be written as external files. This is the default behavior if the PDF is readonly. This can be customized by changing annotationSaveMode. Valid options are: PSPDFAnnotationSaveModeDisabled, PSPDFAnnotationSaveModeExternalFile, PSPDFAnnotationSaveModeEmbedded, and PSPDFAnnotationSaveModeEmbeddedWithExternalFileAsFallback (default).

For more information also see: Saving Annotations

Handling annotations with PSPDFKit

Annotations are handled by the PSPDFAnnotationManager class, an instance of which is managed by a PSPDFDocumentProvider. A PSPDFDocument has one or more PSPDFDocumentProviders depending on the amount of PDF files it contains (usually just one). The preferred way to customize annotation handling is to implement a custom PSPDFAnnotationProvider subclass. We provide a PSPDFContainerAnnotationProvider subclass that is a good base to build upon. If you want to change PSPDFAnnotationManager across the application, the best way to do this is to use overrideClass:withClass: on PSPDFDocument.

Make sure to add the annotationButtonItem to the toolbar to be able to show the annotation toolbar. With PSPDFConfiguration's editableAnnotationTypes property you can customize what annotations can be edited. Set this to an empty array to disable annotation editing.

Checking if a document contains annotations

When calling allAnnotationsOfType:, PSPDFKit will return all annotations of the specified type(s). To check for annotations, you will likely want to use PSPDFAnnotationTypeAll & ~(PSPDFAnnotationTypeLink|PSPDFAnnotationTypeWidget). This returns all annotations excluding links and widgets (buttons and all form elements; remember that form elements are also annotations, even though people don't usually consider them as such). allAnnotationsOfType: returns a dictionary where the key is the page number and the value is an array containing all annotations on that page, so you need to check if any of those arrays have any annotations.

PSPDFCatalog contains many examples of working with annotations, be sure to check them out.

Was this page helpful? We're happy to answer any questions.