Custom Annotation Provider in Swift for iOS

1
//
2
//  Copyright © 2021-2025 PSPDFKit GmbH. All rights reserved.
3
//
4
//  The Nutrient sample applications are licensed with a modified BSD license.
5
//  Please see License for details. This notice may not be removed from this file.
6
//
7

8
import PSPDFKit
9
import PSPDFKitUI
10

11
class CustomAnnotationProviderExample: Example {
12

13
    override init() {
14
        super.init()
15
        title = "Custom Annotation Provider"
16
        contentDescription = "Shows how to use a custom annotation provider"
17
        category = .annotationProviders
18
    }
19

20
    override func invoke(with delegate: ExampleRunnerDelegate?) -> UIViewController? {
21
        let document = AssetLoader.document(for: .annualReport)
22

23
        document.didCreateDocumentProviderBlock = { documentProvider in
24
            documentProvider.annotationManager.annotationProviders = [
25
                // Assign a CustomAnnotationProvider instance as one of the
26
                // annotation providers for the document.
27
                CustomAnnotationProvider(documentProvider: documentProvider)
28
            ]
29
        }
30

31
        let controller = PDFViewController(document: document)
32
        return controller
33
    }
34
}
35

36
private class CustomAnnotationProvider: PDFContainerAnnotationProvider {
37
    /// Timer used to used to update annotation color and notify the delegates.
38
    private var timer: Timer?
39

40
    // MARK: - Lifecycle
41
    override init(documentProvider: PDFDocumentProvider) {
42
        super.init(documentProvider: documentProvider)
43

44
        // Add timer in a way so it works while we're dragging pages (NSRunLoopCommonModes).
45
        timer = Timer(timeInterval: 1.0, target: self, selector: #selector(timerFired(_:)), userInfo: nil, repeats: true)
46

47
        // The document provider generation can happen on any thread, make sure we register on the main runloop.
48
        if let timer {
49
            RunLoop.main.add(timer, forMode: .common)
50
        }
51
    }
52

53
    // MARK: - AnnotationProvider
54

55
    /// Backing store for the `AnnotationProvider` protocol's `providerDelegate` property.
56
    private var providerDelegateBackingStore: AnnotationProviderChangeNotifier?
57

58
    override var providerDelegate: AnnotationProviderChangeNotifier? {
59
        get { providerDelegateBackingStore }
60
        set {
61
            guard newValue?.isEqual(providerDelegate) == false else {
62
                return
63
            }
64

65
            providerDelegateBackingStore = newValue
66

67
            // Nil out timer to allow object to deallocate itself.
68
            if newValue == nil {
69
                timer?.invalidate()
70
                timer = nil
71
            }
72
        }
73
    }
74

75
    override func annotationsForPage(at pageIndex: PageIndex) -> [Annotation]? {
76
        // It's important that this method is:
77
        // - Fast
78
        // - Thread safe
79
        // - Caches annotations — Doesn't always create new objects.
80
        if let cachedAnnotations = performRead({ super.annotationsForPage(at: pageIndex) }) {
81
            return cachedAnnotations
82
        }
83

84
        // We have nothing cached yet, so populate the cache.
85
        return performWriteAndWait {
86
            // Since we left the critical region, another thread may have raced here before.
87
            // So if we omitted this second check, we would occasionally duplicate annotations!
88
            if let cachedAnnotations = super.annotationsForPage(at: pageIndex) {
89
                return cachedAnnotations
90
            }
91

92
            // Create a new note annotation and add it to the backing annotation dictionary storage.
93
            let documentProvider = providerDelegate?.parentDocumentProvider
94
            let noteAnnotation = NoteAnnotation()
95
            noteAnnotation.contents = "Annotation from the custom annotationProvider for page index \(pageIndex)."
96

97
            let pageInfo = documentProvider?.document?.pageInfoForPage(at: pageIndex)
98
            let pageHeight = pageInfo?.size.height ?? 500.0 // Using a fallback page height of 500.
99

100
            // Place it on top left (PDF coordinate space starts from bottom left).
101
            // See https://www.nutrient.io/guides/ios/faq/coordinate-spaces/ for more info.
102
            noteAnnotation.boundingBox = CGRect(x: 100.0, y: pageHeight - 100.0, width: 32.0, height: 32.0)
103

104
            // Set page as the last step, and register the annotation with the backing store.
105
            noteAnnotation.pageIndex = pageIndex
106
            noteAnnotation.isEditable = false
107
            let confirmedAdditions = super.add([noteAnnotation], options: [.suppressNotifications: true])
108

109
            // Adding annotations to the backing store typically sets the needs save flag. But if you get the
110
            // annotations added here from an external file, nothing really changed. So we should make sure to
111
            // clear this flag if we have no dirty annotations.
112
            if dirtyAnnotations?.isEmpty ?? true {
113
                clearNeedsSaveFlag()
114
            }
115

116
            return confirmedAdditions
117
        }
118
    }
119

120
    // MARK: - Helper
121

122
    // Change annotation color and notify the delegate that we have updates.
123
    @objc func timerFired(_ timer: Timer?) {
124
        let color = RandomColor()
125

126
        // Accessing the annotations backing store for a synchronized access to avoid
127
        // multithreading issues.
128
        let cachedAnnotations = performRead {
129
            annotationCache as! [Int: [Annotation]]
130
        }
131
        cachedAnnotations.forEach { _, annotationsOnPage in
132
            annotationsOnPage.forEach { $0.color = color }
133
            providerDelegate?.update(annotationsOnPage, animated: true)
134
        }
135
    }
136
}
137

138
// MARK: - Private
139

140
// Helper to generate a random color.
141
private func RandomColor() -> UIColor? {
142
    let hue = CGFloat.random(in: 0...1.0)
143
    let saturation = CGFloat.random(in: 0.5...1.0) //  0.5 to 1.0, away from white
144
    let brightness = CGFloat.random(in: 0.5...1.0) //  0.5 to 1.0, away from black
145
    return UIColor(hue: hue, saturation: saturation, brightness: brightness, alpha: 1.0)
146
}