PSPDFAnnotationManager

Objective-C


@interface PSPDFAnnotationManager
    : NSObject <PSPDFAnnotationProviderChangeNotifier, PSPDFOverridable>

Swift

class AnnotationManager : NSObject, AnnotationProviderChangeNotifier, Overridable

Collects annotations from the various PSPDFAnnotationProvider implementations.

Usually you want to add your custom PSPDFAnnotationProvider instead of subclassing this class. If you subclass, use overrideClass:withClass: in Document.

This class will set the documentProvider on both annotation adding and retrieving. You don’t have to handle this in your annotationProvider subclass.

  • 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 annotation manager with the associated documentProvider.

    Declaration

    Objective-C

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

    Swift

    init(documentProvider: PSPDFDocumentProvider)

  • The simplest way to extend PSPDFAnnotationManager is to register a custom PSPDFAnnotationProvider. Remove the default PSPDFFileAnnotationProvider if you don’t need file-based annotations.

    By default, this array will contain the fileAnnotationProvider.

    Important: Only the first annotation provider implementing saveAnnotationsWithOptions:error: will be used for saving.

    Note

    The order of the array is important. The PSPDFFileAnnotationProvider also implements autodetected annotations.

    Warning

    Only change this before the document is presented.

    Declaration

    Objective-C

    @property (nonatomic, copy) NSArray<id<PSPDFAnnotationProvider>> *_Nonnull annotationProviders;

    Swift

    var annotationProviders: [AnnotationProvider] { get set }

  • Shortcut to the PSPDFFileAnnotationProvider if it exists in the annotationProviders array.

    Note

    In earlier versions of PSPDFKit, the fileAnnotationProvider always existed. We now allow deallocation if it is not used, and this property just checks the existing annotationProviders array and returns the first matching class. This implies that we might not find an object anymore and may return nil.

    Declaration

    Objective-C

    @property (nonatomic, readonly, nullable) PSPDFFileAnnotationProvider *fileAnnotationProvider;

    Swift

    var fileAnnotationProvider: PSPDFFileAnnotationProvider? { get }

  • Return annotation array for specified page.

    This method will be called OFTEN. Multiple times during a page display, and basically each time you’re scrolling or zooming. Ensure it is fast. This will query all annotationProviders and merge the result. For example, to get all annotations except links, use PSPDFAnnotationTypeAll &~ PSPDFAnnotationTypeLink as type.

    Note

    Fetching annotations may take a while. You can do this in a background thread.

    Declaration

    Objective-C

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

    Swift

    func annotationsForPage(at pageIndex: PageIndex, type: Annotation.Kind) -> [Annotation]?

  • Returns dictionary NSNumber->NSArray. Only adds entries for a page if there are annotations.

    Warning

    This might take some time if the annotation cache hasn’t been built yet.

    Declaration

    Objective-C

    - (nonnull NSDictionary<NSNumber *, NSArray<__kindof PSPDFAnnotation *> *> *)
    allAnnotationsOfType:(PSPDFAnnotationType)annotationType;

    Swift

    func allAnnotations(of annotationType: Annotation.Kind) -> [NSNumber : [Annotation]]

  • YES if annotations are loaded for a specific page. This is used to determine if annotationsForPageAtIndex:type: should be called directly or in a background thread.

    Declaration

    Objective-C

    - (BOOL)hasLoadedAnnotationsForPageAtIndex:(PSPDFPageIndex)pageIndex;

    Swift

    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. If no class is found, the view will be ignored.

    Declaration

    Objective-C

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

    Swift

    func annotationViewClass(for annotation: Annotation) -> AnyClass?

  • Add annotations to the currently set annotation providers. pageIndex is defined through the set page in each annotation object.

    Note

    PSPDFAnnotationManager will query all registered annotationProviders until one returns YES on addAnnotations.

    Will return NO if no annotation provider can handle the annotations. (By default, the PSPDFFileAnnotationProvider will handle all annotations.)

    If you’re just interested in being notified, you can register a custom annotationProvider and set in the array before the file annotationProvider. Implement addAnnotations: and return NO. You’ll be notified of all add operations.

    Declaration

    Objective-C

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

    Swift

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

    Parameters

    annotations

    An array of PSPDFAnnotation objects to be added.
    options

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

  • Inserts annotation to the currently set annotation providers at a specific z-index.

    Will return NO if no annotation provider can handle the annotation. (By default, the PSPDFFileAnnotationProvider will handle all annotations.)

    Declaration

    Objective-C

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

    Swift

    func insert(_ annotation: Annotation, atZIndex destinationIndex: UInt, options: [AnnotationManager.ChangeBehaviorKey : Any]? = nil) throws

    Parameters

    annotation

    A PSPDFAnnotation object to be added.
    destinationIndex

    z-index the annotation should be inserted at.
    options

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

  • Update annotations for a given page in a safe scope.

    Note

    Currently only used for annotation z-index moving.

    Declaration

    Objective-C

    - (BOOL)updateAnnotationsOnPageAtIndex:(PSPDFPageIndex)pageIndex
                                 error:(NSError *_Nullable *_Nullable)error
                       withUpdateBlock:
                           (nonnull BOOL (^)(id<PSPDFAnnotationUpdate> _Nonnull,
                                             NSError *_Nullable *_Nullable))
                               updateBlock;

    Parameters

    pageIndex

    The index of the page you are updating annotations on.
    updateBlock

    Block that should perform all the annotation updates. updateError parameter should be used to report errors that occurred in the updateBlock.

  • Whether an annotation can be moved to a different z-index.

    Declaration

    Objective-C

    - (BOOL)canMoveAnnotation:(nonnull PSPDFAnnotation *)annotation
                    error:(NSError *_Nullable *_Nullable)error;

    Swift

    func canMove(_ annotation: Annotation) throws

  • If the annotation can be moved by a specified z-index move.

    Declaration

    Objective-C

    - (BOOL)canExecuteZIndexMove:(PSPDFAnnotationZIndexMove)zIndexMove
               forAnnotation:(nonnull PSPDFAnnotation *)annotation;

    Swift

    func canExecute(_ zIndexMove: Annotation.ZIndexMove, for annotation: Annotation) -> Bool

  • Remove annotations from the pages they are registered in.

    If the annotations have replies, those will be removed too. If you don’t want this copy the annotations you want to keep and add them back.

    Note

    Will return NO if no annotationProvider can handle the annotations. (By default, the PSPDFFileAnnotationProvider will handle all annotations.)

    Declaration

    Objective-C

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

    Swift

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

    Parameters

    annotations

    An array of PSPDFAnnotation objects to be removed.
    options

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

  • Will be called by PSPDF internally every time an annotation is changed. Call will be relayed to all annotationProviders.

    This method will be called on ALL annotations, not just the ones that you provided.

    Note

    If you have custom code that changes annotations and you rely on the didChangeAnnotation: event, you need to call it manually.

    options is used internally to determine of the file annotation provider should request an annotation update. (the userInfo notification dict will be forwarded.)

    Declaration

    Objective-C

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

    Swift

    func didChange(_ annotation: Annotation, keyPaths: [String], options: [String : Any]? = nil)

  • Save annotations. (returning NO + eventually an error if it fails) Saving will be forwarded to all annotation providers. Usually you want to override the method in PSPDFFileAnnotationProvider instead.

    Declaration

    Objective-C

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

    Swift

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

  • Return YES if the manager requires saving.

    Note

    You should first ensure the state property in the annotationStateManager to nil to commit any draft annotations.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL shouldSaveAnnotations;

    Swift

    var shouldSaveAnnotations: Bool { get }

  • Provided to the PSPDFAnnotationProviders via PSPDFAnnotationProviderChangeNotifier. Will update any visible annotation.

    Declaration

    Objective-C

    - (void)updateAnnotations:(nonnull NSArray<PSPDFAnnotation *> *)annotations
                 animated:(BOOL)animated;

    Swift

    func update(_ annotations: [Annotation], animated: Bool)

  • Will parse the annotations in the array and add the ones that are included in the group (have the same grouping ID) annotations need to be handled in the annotation manager.

    Declaration

    Objective-C

    - (nonnull NSArray<PSPDFAnnotation *> *)
    annotationsIncludingGroupsFromAnnotations:
        (nonnull NSArray<PSPDFAnnotation *> *)annotations;

    Swift

    func annotationsIncludingGroups(from annotations: [Annotation]) -> [Annotation]

  • Change the protocol that’s used to parse PSPDFKit-additions (links, audio, video). Defaults to pspdfkit://.

    Note

    This will affect all parsers that generate PSPDFAction objects.

    Warning

    Set this early on or manually clear the cache to update the parsers.

    Declaration

    Objective-C

    @property (nonatomic, copy) NSArray<NSString *> *_Nonnull protocolStrings;

    Swift

    var protocolStrings: [String] { get set }

  • The fileType translation table is used when we encounter pspdfkit:// links (or whatever is set to document.protocolStrings) Maps e.g. “mpg” to PSPDFLinkAnnotationVideo. (NSString -> NSNumber)

    Note

    If you need file translation categorization that is not related to annotations, use PSPDFFileHelperGetFileCategory() instead.

    Declaration

    Objective-C

    + (nonnull NSDictionary<NSString *, NSNumber *> *)fileTypeTranslationTable;

    Swift

    class func fileTypeTranslationTable() -> [String : NSNumber]

  • Document provider for annotation parser.

    Declaration

    Objective-C

    @property (nonatomic, weak, readonly) PSPDFDocumentProvider *_Nullable documentProvider;

    Swift

    weak var documentProvider: PSPDFDocumentProvider? { get }

SubclassingHooks

  • Searches the annotation cache for annotations that have the dirty flag set. Dictionary key are the pages, object an array of annotations.

    Declaration

    Objective-C

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

    Swift

    var dirtyAnnotations: [NSNumber : [Annotation]]? { get }

  • Filtered fileTypeTranslationTable that only returns video or audio elements.

    Declaration

    Objective-C

    + (nonnull NSArray<NSString *> *)mediaFileTypes;

    Swift

    class func mediaFileTypes() -> [String]

  • Returns the view class that can host the specific annotation subtype.

    Note

    Usually you want to write an annotation provider and implement annotationViewClassForAnnotation: instead of subclassing.

    Declaration

    Objective-C

    - (nullable Class)defaultAnnotationViewClassForAnnotation:
    (nonnull PSPDFAnnotation *)annotation;

    Swift

    func defaultAnnotationViewClass(for annotation: Annotation) -> AnyClass?

  • Update annotations for a given page in a safe scope.

    Note

    Currently only used for annotation z-index moving.

    Declaration

    Swift

    public func updateAnnotationsOnPage(at pageIndex: PageIndex, updates: (AnnotationUpdate) throws -> Void) throws

    Parameters

    pageIndex

    The index of the page you are updating annotations on.
    updates

    The block containing performing the annotation updates using the AnnotationUpdate passed to it.