PSPDFAnnotationManager


@interface PSPDFAnnotationManager
    : NSObject <PSPDFAnnotationProviderChangeNotifier>

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

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

  • Undocumented

    Declaration

    Objective-C

    
    @interface PSPDFAnnotationManager
        : NSObject <PSPDFAnnotationProviderChangeNotifier>
  • Undocumented

    Declaration

    Objective-C

    
    @interface PSPDFAnnotationManager
        : NSObject <PSPDFAnnotationProviderChangeNotifier>
  • 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. You can even remove the default PSPDFFileAnnotationProvider if you don’t want file-based annotations.

    On default, this array will contain the fileAnnotationProvider. - note: The order of the array is important. - warning: Only change this before the document is presented.

    Declaration

    Objective-C

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

    Swift

    var annotationProviders: [PSPDFAnnotationProvider] { get set }
  • Direct access to the file annotation provider, who default is the only registered annotationProvider. Will never be nil, but can be removed from the annotationProviders list.

    Declaration

    Objective-C

    @property (readonly, nonatomic)
        PSPDFFileAnnotationProvider *_Nonnull 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:(NSUInteger)pageIndex
                         type:(PSPDFAnnotationType)type;

    Swift

    func annotationsForPage(at pageIndex: UInt, type: PSPDFAnnotationType) -> [PSPDFAnnotation]?
  • 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: PSPDFAnnotationType) -> [NSNumber : [PSPDFAnnotation]]
  • 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:(NSUInteger)pageIndex;

    Swift

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

    Declaration

    Objective-C

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

    Swift

    func annotationViewClass(for annotation: PSPDFAnnotation) -> AnyClass?
  • Add annotations to the currently set annotation providers. page 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 annotationProvider 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<NSString *, id> *)options;

    Swift

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

    Parameters

    annotations

    An array of PSPDFAnnotation objects to be added.

    options

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

  • Remove annotations from the pages they are registered in. - parameter: annotations An array of PSPDFAnnotation objects to be removed. - parameter: options Deletion options (see the PSPDFAnnotationOption... constants in PSPDFAnnotationManager.h). - 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<NSString *, id> *)options;

    Swift

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

    Parameters

    annotations

    An array of PSPDFAnnotation objects to be removed.

    options

    Deletion options (see the 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: PSPDFAnnotation, 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 (readonly, nonatomic) 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: [PSPDFAnnotation], 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: [PSPDFAnnotation]) -> [PSPDFAnnotation]
  • 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 (readwrite, copy, nonatomic)
        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 (readonly, nonatomic)
        PSPDFDocumentProvider *_Nullable documentProvider;

    Swift

    weak var documentProvider: PSPDFDocumentProvider? { get }
  • 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 (readonly, nonatomic, nullable)
        NSDictionary<NSNumber *, NSArray<__kindof PSPDFAnnotation *> *>
            *dirtyAnnotations;

    Swift

    var dirtyAnnotations: [NSNumber : [PSPDFAnnotation]]? { 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: PSPDFAnnotation) -> AnyClass?