PSPDFAnnotationProvider

Objective-C

@protocol PSPDFAnnotationProvider <NSObject>

Swift

protocol AnnotationProvider : NSObjectProtocol

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 Document 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/re-rendering) 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:
    (PSPDFPageIndex)pageIndex;

    Swift

    func annotationsForPage(at pageIndex: PageIndex) -> [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:(PSPDFPageIndex)pageIndex;

    Swift

    optional func hasLoadedAnnotationsForPage(at pageIndex: PageIndex) -> 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

    - (nullable 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.

    Note

    The annotation provider is responsible for emitting the PSPDFAnnotationsAddedNotification.

    Declaration

    Objective-C

    - (nullable NSArray<__kindof PSPDFAnnotation *> *)
    addAnnotations:(nonnull NSArray<__kindof PSPDFAnnotation *> *)annotations
           options:(nullable NSDictionary<PSPDFAnnotationOption, 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 PSPDFAnnotationOption constants in PSPDFAnnotationManager.h).

  • Handle inserting an annotation. A provider can decide that it doesn’t want to add this annotation, in that case either don’t implement insertAnnotation: at all or return NO. Return YES if inserting the annotation was successful, NO otherwise. PSPDFAnnotationManager will call all annotation providers in the list until the annotation has been successfully added.

    Note

    The annotation provider is responsible for emitting the PSPDFAnnotationsAddedNotification.

    Declaration

    Objective-C

    - (BOOL)insertAnnotation:(nonnull PSPDFAnnotation *)annotation
                atZIndex:(NSUInteger)destinationIndex
                 options:
                     (nullable NSDictionary<PSPDFAnnotationOption, id> *)options
                   error:(NSError *_Nullable *_Nullable)error;

    Swift

    optional func insert(_ annotation: PSPDFAnnotation, atZIndex destinationIndex: UInt, options: [String : Any]? = nil) throws

    Parameters

    annotation

    An PSPDFAnnotation object to be inserted.
    destinationIndex

    The z-index the annotation should be inserted at.
    options

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

  • Defines if this annotation provider supports z-index moving of annotations. If this is not implemented, NO is assumed.

    Declaration

    Objective-C

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

    Swift

    optional var allowAnnotationZIndexMoves: Bool { get }

  • 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.

    Note

    The annotation provider is responsible for emitting the PSPDFAnnotationsRemovedNotification.

    Declaration

    Objective-C

    - (nullable NSArray<__kindof PSPDFAnnotation *> *)
    removeAnnotations:(nonnull NSArray<__kindof PSPDFAnnotation *> *)annotations
              options:
                  (nullable NSDictionary<PSPDFAnnotationOption, 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 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 PDFViewController 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 (nonatomic, readonly) BOOL shouldSaveAnnotations;

    Swift

    optional var shouldSaveAnnotations: Bool { get }

  • Return all “dirty” = unsaved annotations.

    Declaration

    Objective-C

    @optional
@property (nonatomic, readonly, 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 (atomic, weak, readwrite)
    id<PSPDFAnnotationProviderChangeNotifier> _Nullable providerDelegate;

    Swift

    weak optional var providerDelegate: AnnotationProviderChangeNotifier? { get set }

  • Set this delegate to be notified of annotation saving related events. Automatically synthesized on PSPDFContainerAnnotationProvider.

    Declaration

    Objective-C

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

    Swift

    weak optional var delegate: AnnotationProviderDelegate? { get set }