PSPDFAnnotationProvider

@protocol PSPDFAnnotationProvider <NSObject>

With the annotation provider, you can mix in PDF annotations from any source (custom database, web, etc) Implement your custom provider class and register it in the PSPDFAnnotationManager.

(Make sure to register the provider in the PSPDFDocument’s didCreateDocumentProvider: method, since a PSPDFDocument can have multiple PSPDFDocumentProviders and thus multiple PSPDFAnnotationProviders - and they can also be discarded on low memory situations.)

Ensure everything is thread safe here - methods will be called from any threads and sometimes even concurrently at the same time. (If you’re doing parsing, block and then in the queue re-check so you’re not parsing multiple times for the same page)

Note

You should always use PSPDFContainerAnnotationProvider as the base class for your custom annotation provider.
  • Return any annotations that should be displayed on that page.

    Note

    This method needs to be accessible FROM ANY THREAD. You can block here and do your processing but try to cache the result, this method is called often. (e.g. on every zoom change/rerendering) You’re only getting the zero-based page index here. If needed, add a reference to PSPDFDocumentProvider during init or query the change notifier delegate.

    Declaration

    Objective-C

    - (nullable NSArray<__kindof PSPDFAnnotation *> *)annotationsForPageAtIndex:
        (NSUInteger)pageIndex;

    Swift

    func annotationsForPage(at pageIndex: UInt) -> [PSPDFAnnotation]?
  • Return YES if annotationsForPageAtIndex: is done preparing the cache, else NO. PSPDFKit will preload/access annotationsForPageAtIndex: in a background thread and then re-access it on the main thread. Defaults to YES if not implemented. - warning: You NEED to return YES on this after annotationsForPageAtIndex: has been accessed.

    Declaration

    Objective-C

    - (BOOL)hasLoadedAnnotationsForPageAtIndex:(NSUInteger)pageIndex;

    Swift

    optional func hasLoadedAnnotationsForPage(at pageIndex: UInt) -> Bool
  • Any annotation that returns YES on isOverlay needs a view class to be displayed. Will be called on all annotationProviders until someone doesn’t return nil. - note: If no class is found, the view will be ignored.

    Declaration

    Objective-C

    - (nonnull Class)annotationViewClassForAnnotation:
        (nonnull PSPDFAnnotation *)annotation;

    Swift

    optional func annotationViewClass(for annotation: PSPDFAnnotation) -> AnyClass
  • Handle adding annotations. A provider can decide that it doesn’t want to add this annotation, in that case either don’t implement addAnnotations: at all or return nil. Return all annotations that are handled by this annotation provider. PSPDFAnnotationManager will call all annotation providers in the list until all annotations have been processed. - parameter: annotations An array of PSPDFAnnotation objects to be added. - parameter: options Insertion options (see the PSPDFAnnotationOption... constants in PSPDFAnnotationManager.h). - note: The annotation provider is responsible for emitting then PSPDFAnnotationsAddedNotification.

    Declaration

    Objective-C

    - (nullable NSArray<__kindof PSPDFAnnotation *> *)
    addAnnotations:(nonnull NSArray<__kindof PSPDFAnnotation *> *)annotations
           options:(nullable NSDictionary<NSString *, id> *)options;

    Swift

    optional func add(_ annotations: [PSPDFAnnotation], options: [String : Any]? = nil) -> [PSPDFAnnotation]?

    Parameters

    annotations

    An array of PSPDFAnnotation objects to be added.

    options

    Insertion options (see the PSPDFAnnotationOption... constants in PSPDFAnnotationManager.h).

  • Handle removing annotations. A provider can decide that it doesn’t want to add this annotation, in that case either don’t implement removeAnnotations: at all or return NO. PSPDFAnnotationManager will query all registered annotationProviders until one returns YES on this method. - parameter: annotations An array of PSPDFAnnotation objects to be removed. - parameter: options Deletion options (see the PSPDFAnnotationOption... constants in PSPDFAnnotationManager.h). - note: The annotation provider is responsible for emitting then PSPDFAnnotationsRemovedNotification.

    Declaration

    Objective-C

    - (nullable NSArray<__kindof PSPDFAnnotation *> *)
    removeAnnotations:(nonnull NSArray<__kindof PSPDFAnnotation *> *)annotations
              options:(nullable NSDictionary<NSString *, id> *)options;

    Swift

    optional func remove(_ annotations: [PSPDFAnnotation], options: [String : Any]? = nil) -> [PSPDFAnnotation]?

    Parameters

    annotations

    An array of PSPDFAnnotation objects to be removed.

    options

    Deletion options (see the PSPDFAnnotationOption... constants in PSPDFAnnotationManager.h).

  • PSPDFKit requests a save. Can be ignored if you’re instantly persisting. Event is e.g. fired before the app goes into background, or when PSPDFViewController is dismissed. Return NO + error if saving failed.

    Declaration

    Objective-C

    - (BOOL)saveAnnotationsWithOptions:
                (nullable NSDictionary<NSString *, id> *)options
                                 error:(NSError *_Nullable *_Nullable)error;

    Swift

    optional func saveAnnotations(options: [String : Any]? = nil) throws
  • Return YES if the provider requires saving.

    Declaration

    Objective-C

    @optional
    @property (readonly, nonatomic) BOOL shouldSaveAnnotations;

    Swift

    optional var shouldSaveAnnotations: Bool { get }
  • Return all dirty = unsaved annotations.

    Declaration

    Objective-C

    @optional
    @property (readonly, nonatomic, nullable)
        NSDictionary<NSNumber *, NSArray<__kindof PSPDFAnnotation *> *>
            *dirtyAnnotations;

    Swift

    optional var dirtyAnnotations: [NSNumber : [PSPDFAnnotation]]? { get }
  • Callback if an annotation has been changed by PSPDFKit. This method will be called on ALL annotations, not just the ones that you provided.

    Declaration

    Objective-C

    - (void)didChangeAnnotation:(nonnull PSPDFAnnotation *)annotation
                       keyPaths:(nonnull NSArray<NSString *> *)keyPaths
                        options:(nullable NSDictionary<NSString *, id> *)options;

    Swift

    optional func didChange(_ annotation: PSPDFAnnotation, keyPaths: [String], options: [String : Any]? = nil)
  • Provides a back-channel to PSPDFKit if you need to change annotations on the fly. (e.g. new changes from your server are coming in)

    Declaration

    Objective-C

    @optional
    @property (readwrite, atomic)
        id<PSPDFAnnotationProviderChangeNotifier> _Nullable providerDelegate;

    Swift

    weak optional var providerDelegate: PSPDFAnnotationProviderChangeNotifier? { get set }
  • Set this delegate to be notified of annotation saving related events. Automatically synthesized on PSPDFContainerAnnotationProvider.

    Declaration

    Objective-C

    @optional
    @property (readwrite, nonatomic)
        id<PSPDFAnnotationProviderDelegate> _Nullable delegate;

    Swift

    weak optional var delegate: PSPDFAnnotationProviderDelegate? { get set }