The Annotation Object Model

This article explains how the PSPDFAnnotation and PSPDFFormElement classes can be used. For an overview of annotation support in PSPDFKit, see Introduction to Annotations.

To learn more about how you can check if annotations have been added/removed/changed, see Detecting If Annotations Have Changed

Changing Annotations

The annotation object model is based on PSPDFModel. Changes need to be made on the main thread. If a PSPDFViewController is currently displaying the PSPDFDocument that owns the annotation, you should emit a change notification to ensure the UI is correctly updated:

Copy
1
2
3
4
let freeTextAnnotation: PSPDFFreeTextAnnotation = ...
freeTextAnnotation.contents = "These are my new note contents."

NotificationCenter.default.post(name: NSNotification.Name.PSPDFAnnotationChanged, object: freeTextAnnotation, userInfo: [PSPDFAnnotationChangedNotificationKeyPathKey: ["contents"]])
Copy
1
2
3
4
5
PSPDFFreeTextAnnotation *freeTextAnnotation = ...;
freeTextAnnotation.contents = @"These are my new note contents.";

[NSNotificationCenter.defaultCenter postNotificationName:PSPDFAnnotationChangedNotification
object:freeTextAnnotation userInfo:@{PSPDFAnnotationChangedNotificationKeyPathKey : @[@"contents"]}];

This sends a PSPDFAnnotationChangedNotification. The PSPDFAnnotationChangedNotificationKeyPathKey should match the change you’ve made, as this enables PSPDFKit to perform additional performance optimizations (for example, various properties might not require a new render step).

Adding Annotations

Annotations can be added by calling addAnnotations:options: on your PSPDFDocument. This will emit a PSPDFAnnotationsAddedNotification.

Deleting Annotations

Deleting annotations should be performed by calling removeAnnotations:options: on your PSPDFDocument. This will emit either a PSPDFAnnotationsRemovedNotification or a PSPDFAnnotationChangedNotification, depending on whether or not the annotation has already been saved in the PDF. If it has been saved, we need to use soft delete to track and correctly update the file.

Thread Safety

Annotations should only be accessed on the main thread. They can be created on any thread, but as soon as they’re added to a PSPDFDocument, they need to be treated as accessible on the main thread only. The annotations will check access via testing if the documentProvider property is set and assert if non-main thread access is detected. This behavior is new as of PSPDFKit 4.1 in order to ensure that there won’t be situations where the main thread is writing to a model being evaluated on a background thread, which could lead to inconsistencies or even a crash (accessing an already released object, etc.).

Internally, PSPDFKit uses immutable copies to feed the render queue and to ensure thread safety. These methods are not exposed. If the automatic annotation fetching feature is used for document rendering, immutable copies are used to ensure thread safety.

💡 Tip: You can also access annotations when tapping on them by implementing PSPDFViewControllerDelegate methods like -pdfViewController:didTapOnAnnotation:annotationPoint:annotationView:pageView:viewPoint:.