PSPDFContainerAnnotationProvider

Objective-C


@interface PSPDFContainerAnnotationProvider : NSObject <PSPDFAnnotationProvider>

Swift

class PDFContainerAnnotationProvider : NSObject, AnnotationProvider

Default container for annotations. It’s highly recommended that you use this class as your base class if you implement a custom annotation provider in order to leverage built-in functionality that ensures annotation changes are correctly propagated throughout the framework.

You must use this base class to support refreshing annotations in response to an external change, like from -[PSPDFDocumentProvider setRotationOffset:forPageAtIndex:]. To put that in other words, an annotation provider must subclass this class for temporary page rotations to work correctly.

  • 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

  • Designated initializer.

    Declaration

    Objective-C

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

    Swift

    init(documentProvider: PSPDFDocumentProvider)

  • Associated documentProvider.

    Declaration

    Objective-C

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

    Swift

    weak var documentProvider: PSPDFDocumentProvider? { get }

  • Whether this class tracks removed annotations as soft deletions — defaults to true.

    When true, instances of this class track annotations that have been passed to removeAnnotations:options: in the dirtyAnnotations until clearNeedsSaveFlag is called. When implementing your own annotation provider, you can opt out of this behavior by overriding this class method to return false.

    Declaration

    Objective-C

    @property (class, nonatomic, readonly) BOOL shouldTrackDeletions;

    Swift

    class var shouldTrackDeletions: Bool { get }

  • Clears shouldSaveAnnotations, disposes of any soft deleted annotations, and clears the “dirty” flag of all the receiver’s annotations.

    Adding, removing, and updating annotations not only marks the annotation itself as “dirty”, but also triggers an internal flag that the provider requires saving. This method clears those flags and disposes of any “soft deleted” annotations. The receiver is left without dirtyAnnotations and shouldSaveAnnotations returns false until the next annotation change.

    Warning

    This method must be called inside a write block! Failing to do so will (at best) crash your program. At worst it will silently corrupt user data.

    Declaration

    Objective-C

    - (void)clearNeedsSaveFlag;

    Swift

    func clearNeedsSaveFlag()

  • Directly accesses the annotation cache used internally. Be extremely careful when accessing this, and use the locking methods.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSMutableDictionary<NSNumber *, NSArray<PSPDFAnnotation *> *> *_Nonnull annotationCache;

    Swift

    var annotationCache: NSMutableDictionary { get }

  • Called before new annotations are inserted. Subclass to perform custom actions.

    This method is called inside of a writing block. You can therefore safely inspect and even modify the annotationCache directly.

    Declaration

    Objective-C

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

    Swift

    func willInsertAnnotations(_ annotations: [PSPDFAnnotation])

  • Allows synchronization with the internal reader queue.

    This method is safe to call inside of a write block. That is a block passed into performBlockForWriting: or performBlockForWritingAndWait:. The reverse is not necessarily true. Specifically…

    Warning

    Calling performBlockForWritingAndWait: inside of the read block is unsafe, and will almost certainly cause deadlock! This includes making calls that have write semantics and are not documented to require to be called inside a write block.

    Declaration

    Objective-C

    - (void)performBlockForReading:(nonnull void (^)(void))block;

  • Allows synchronization with the internal writer queue.

    This method is safe to call at any time — including inside a read block. The exact execution characteristics may be surprising, though:

    1. When this method is called inside a write block, the block parameter is executed inline.
    2. When this method is called in any other context, the block parameter is executed asynchronously on a background queue.
    3. When executed, the block parameter will have writer status. It is therefore safe to call any instance method of this class inside the block.

    Declaration

    Objective-C

    - (void)performBlockForWriting:(nonnull void (^)(void))block;

  • Allows synchronization with the internal writer queue and blocks until the block is processed.

    When executed, the block parameter will have writer status. It is therefore safe to call any instance method of this class inside the block. This specifically includes calls to performBlockForWritingAndWait: and calls to performBlockForReading:. The reverse, however, is not true. Specifically…

    Warning

    Calling this method as part of a block passed to performBlockForReading: will almost certainly cause deadlock!

    Declaration

    Objective-C

    - (void)performBlockForWritingAndWait:(nonnull void (^)(void))block;

  • Modify the internal store. Optionally appends annotations instead of replacing them.

    Note

    The page set in the annotations need to match the page.

    Note

    Subclassing Note: If you override this method and modify additional internal state of your subclass, wrap the modifications as well as the call to super in a write block. Otherwise you risk breaking atomicity of the operation.

    Declaration

    Objective-C

    - (void)setAnnotations:(nonnull NSArray<PSPDFAnnotation *> *)annotations
        forPageAtIndex:(PSPDFPageIndex)pageIndex
                append:(BOOL)append;

    Swift

    func setAnnotations(_ annotations: [PSPDFAnnotation], forPageAt pageIndex: PageIndex, append: Bool)

  • Set annotations, evaluate the page value of each annotation.

    Note

    Subclassing Note: If you override this method and modify additional internal state of your subclass, wrap the modifications as well as the call to super in a write block. Otherwise you risk breaking atomicity of the operation.

    Declaration

    Objective-C

    - (void)setAnnotations:(nonnull NSArray<PSPDFAnnotation *> *)annotations
                append:(BOOL)append;

    Swift

    func setAnnotations(_ annotations: [PSPDFAnnotation], append: Bool)

  • Note

    Subclassing Note: If you override this method and modify additional internal state of your subclass, wrap the modifications as well as the call to super in a performLockForWritingAndWait:. Otherwise you risk breaking atomicity of the operation or deadlock.

    Declaration

    Objective-C

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

    Swift

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

  • As of PSPDFKit 7.4, PSPDFContainerAnnotationProvider tracks annotations passed into this method as deleted, unless you override +shouldTrackDeletions to return false. So when you are inheriting from this class, you must call clearNeedsSaveFlag when implementing saveAnnotationsWithOptions:error: to purge those deleted annotations.

    Note

    Subclassing Note: If you override this method and modify additional internal state of your subclass, wrap the modifications as well as the call to super in a performLockForWritingAndWait:. Otherwise you risk breaking atomicity of the operation or deadlock.

    Declaration

    Objective-C

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

    Swift

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

    Parameters

    annotations

    The annotations to delete.
    options

    Options for the deletion. For the full set of options, see PSPDFAnnotationOption constants in PSPDFAnnotationManager.h.

  • Remove all annotations (effectively clears the cache).

    Note

    Subclassing Note: If you override this method and modify additional internal state of your subclass, wrap the modifications as well as the call to super in a write block. Otherwise you risk breaking atomicity of the operation.

    Declaration

    Objective-C

    - (void)removeAllAnnotationsWithOptions:
    (nonnull NSDictionary<PSPDFAnnotationOption, id> *)options;

    Swift

    func removeAllAnnotations(options: [String : Any] = [:])

    Parameters

    options

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

  • Returns the cached annotations of all pages in one array.

    This will not force loading if the provider lazily loads annotations into the cache in annotationsForPageAtIndex:. Both PSPDFFileAnnotationProvider and PSPDFXFDFAnnotationProvider do this lazy loading.

    Note

    Subclassing Note: This is a reading operation. If you need to override this method to query mutable state, wrap these queries as well as the call to super in a read block. Otherwise you risk breaking atomicity of the operation.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSArray<PSPDFAnnotation *> *_Nonnull allAnnotations;

    Swift

    var allAnnotations: [PSPDFAnnotation] { get }

  • Returns cached annotations as a page->annotations per page dictionary.

    This will not force loading if the provider lazily loads annotations into the cache in annotationsForPageAtIndex:. Both PSPDFFileAnnotationProvider and PSPDFXFDFAnnotationProvider do this lazy loading.

    Note

    Subclassing Note: This is a reading operation. If you need to override this method to query mutable state, wrap these queries as well as the call to super in a read block. Otherwise you risk breaking atomicity of the operation.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSDictionary<NSNumber *, NSArray<PSPDFAnnotation *> *> *_Nonnull annotations;

    Swift

    var annotations: [NSNumber : [PSPDFAnnotation]] { get }

  • May be used to override the annotation cache directly. Faster than using setAnnotations:.

    Note

    Subclassing Note: If you override this method and modify additional internal state of your subclass, wrap the modifications as well as the call to super in a write block. Otherwise you risk breaking atomicity of the operation.

    Declaration

    Objective-C

    - (void)setAnnotationCacheDirect:
    (nonnull NSDictionary<NSNumber *, NSArray<PSPDFAnnotation *> *> *)
        annotationCache;

    Swift

    func setAnnotationCacheDirect(_ annotationCache: [NSNumber : [PSPDFAnnotation]])

  • Synchronize an operation with the internal reader queue.

    This method is safe to call inside of a write closure. That is a closure passed into performWrite(_:) or performWriteAndWait(_:). The reverse is not necessarily true. Specifically…

    Warning

    Calling performWriteAndWait(_:) inside of the read closure is unsafe, and will almost certainly cause deadlock! This includes making calls that have write semantics and are not documented to require to be called inside a write block.

    Declaration

    Swift

    public func performRead<Result>(_ operation: () -> Result) -> Result

    Parameters

    operation

    A closure to synchronize.

  • Synchronize an operation with the internal writer queue.

    This method is safe to call at any time — including inside a read closure. The exact execution characteristics may be surprising, though:

    1. When this method is called inside a write block, the block parameter is executed inline.

    2. When this method is called in any other context, the block parameter is executed asynchronously on a background queue.

    3. When executed, the block parameter will have writer status. It is therefore safe to call any instance method of this class inside the block.

    Declaration

    Swift

    public func performWrite(_ operation: @escaping () -> Void)

    Parameters

    operation

    A closure to synchronize.

  • Synchronize an operation with the internal writer queue and block execution until the closure is processed.

    When executed, the closure parameter will have writer status. It is therefore safe to call any instance method of this class inside the block. This specifically includes calls to performWriteAndWait(_:) and calls to performRead(_:). The reverse, however, is not true. Specifically…

    Warning

    Calling performWriteAndWait(_:) as part of a closure passed to performRead(_:) will almost certainly cause deadlock!

    Declaration

    Swift

    public func performWriteAndWait<Result>(_ operation: () -> Result) -> Result

    Parameters

    operation

    A closure to synchronize.