PSPDFFileAnnotationProvider

Objective-C


@interface PSPDFFileAnnotationProvider
    : PSPDFContainerAnnotationProvider <PSPDFOverridable>

Swift

class PDFFileAnnotationProvider : PDFContainerAnnotationProvider, Overridable

An implementation of the PSPDFAnnotationProvider protocol that uses the PDF document as source/target to load/save annotations. You almost always want to use the PSPDFFileAnnotationProvider in your PSPDFAnnotationManager. You can also use this class inside a custom annotation provider, to parse PDF annotations once and then manage them in your custom database.

Note

Subclassing PSPDFFileAnnotationProvider will lead to slower PSPDFProcessor performance and is strongly discouraged. This will be blocked in future versions.

  • Unavailable

    Not the designated initializer

    Undocumented

    Declaration

    Objective-C

    PSPDF_EMPTY_INIT_UNAVAILABLE

  • Unavailable

    Not the designated initializer

    Undocumented

    Declaration

    Objective-C

    PSPDF_EMPTY_INIT_UNAVAILABLE

  • Initializes the file annotation provider with the document provider and uses the default path.

    The default annotation path is created based on the following rules: self.documentProvider.document.cacheDirectory + “annotations_%d.pspdfkit”. The number is omitted in the usual case with only one documentProvider. For documents with multiple providers, we write “annotations.pspdfkit”, “annotations_2.pspdfkit”, and so on.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithDocumentProvider:
    (nonnull PSPDFDocumentProvider *)documentProvider;

    Swift

    convenience init(documentProvider: PDFDocumentProvider)

  • Initializes the file annotation provider with the document provider and a custom file url (path).

    Declaration

    Objective-C

    - (nonnull instancetype)
    initWithDocumentProvider:(nonnull PSPDFDocumentProvider *)documentProvider
                     fileURL:(nullable NSURL *)annotationFileURL;

    Swift

    init(documentProvider: PDFDocumentProvider, fileURL annotationFileURL: URL?)

  • Set to enable auto-detection of various link types. Defaults to PSPDFTextCheckingTypeNone.

    Warning

    Detecting links might be an expensive operation.

    Declaration

    Objective-C

    @property (nonatomic) PSPDFTextCheckingType autodetectTextLinkTypes;

    Swift

    var autodetectTextLinkTypes: TextCheckingType { get set }

  • Performance optimized access.

    This method uses a cache (and is of course thread safe). After the first expensive call, this method is basically free.

    Note

    Soft deleted annotations are not returned from this method. They are, however, returned by dirtyAnnotations until the document has been saved successfully.

    See

    removeAnnotations:options:

    Declaration

    Objective-C

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

    Swift

    func annotationsForPage(at pageIndex: PageIndex) -> [Annotation]?

  • Adds the given annotations to the appropriate pages. Will accept any annotations.

    Returns the annotations that have actually been added. These objects will be returned from allAnnotations until they are removed from the receiver — either by passing them to removeAnnotations:options: or deleting them in the UI.

    Declaration

    Objective-C

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

    Swift

    func add(_ annotations: [Annotation], options: [AnnotationManager.ChangeBehaviorKey : Any]? = nil) -> [Annotation]?

    Parameters

    annotations

    An array of PSPDFAnnotation objects to be added.
    options

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

  • Removes the given annotations from the backing store and posts a PSPDFAnnotationsRemovedNotification for the deleted objects on the main queue.

    Note

    The annotations are soft-deleted. Meaning while they are removed from allAnnotations, they are returned from dirtyAnnotations until the next successful call to saveAnnotationsWithOptions:error:.

    Declaration

    Objective-C

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

    Swift

    func remove(_ annotations: [Annotation], options: [AnnotationManager.ChangeBehaviorKey : Any]? = nil) -> [Annotation]?

    Parameters

    annotations

    The annotations that have actually been removed.
    options

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

    Return Value

    Returns the annotations that have been removed from allAnnotations.

  • Removes all annotations and re-evaluates the document on next access.

    Declaration

    Objective-C

    - (void)clearCache;

    Swift

    func clearCache()

Advanced

  • Defaults to PSPDFAnnotationTypeAll&~PSPDFAnnotationTypeLink.

    Change this to PSPDFAnnotationTypeAll to also allow saving link annotations. (Links are not saved by default because some documents have a crazy high amount of link annotations which would make saving slow.)

    Warning

    Never exclude PSPDFAnnotationTypeWidget - forms are specially handled.

    Declaration

    Objective-C

    @property (nonatomic) PSPDFAnnotationType saveableTypes;

    Swift

    var saveableTypes: Annotation.Kind { get set }

  • What annotation types should be parsed from the PDF. Defaults to PSPDFAnnotationTypeAll.

    Declaration

    Objective-C

    @property (nonatomic) PSPDFAnnotationType parsableTypes;

    Swift

    var parsableTypes: Annotation.Kind { get set }

  • Path where annotations are being saved if saving to external file is enabled.

    Note

    This was settable in earlier versions of PSPDFKit. To change the annotation path, create a new file annotation provider object and set it on the annotation manager.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSString *_Nonnull annotationsPath;

    Swift

    var annotationsPath: String { get }

Subclassing Hooks

  • Parses the page annotation dictionary and returns the newly created annotations.

    Note

    Important: This method is meant to be overridden to customize annotations right after parsing. You should not call it yourself! Instead, this is called as a part of annotationsForPageAtIndex: from within a performBlockForWritingAndWait: block. It is therefore safe to call any method inside your override — including those that have or require write semantics. Calling this method from within a performBlockForReading: block is unsafe and will likely deadlock!

    Declaration

    Objective-C

    - (nullable NSArray<PSPDFAnnotation *> *)parseAnnotationsForPageAtIndex:
    (PSPDFPageIndex)pageIndex;

    Swift

    func parseAnnotationsForPage(at pageIndex: PageIndex) -> [Annotation]?

  • Saving code.

    Declaration

    Objective-C

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

    Swift

    func saveAnnotations(options: [String : Any]? = nil) throws

  • Loads annotations from an external file, returning nil and an error if that fails.

    Declaration

    Objective-C

    - (nullable NSDictionary<NSNumber *, NSArray<PSPDFAnnotation *> *> *)
    loadAnnotationsWithError:(NSError *_Nullable *_Nullable)error;

    Swift

    func loadAnnotations() throws -> [NSNumber : [Annotation]]