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 toremoveAnnotations:options:
in thedirtyAnnotations
untilclearNeedsSaveFlag
is called. When implementing your own annotation provider, you can opt out of this behavior by overriding this class method to returnfalse
.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
andshouldSaveAnnotations
returnsfalse
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. -
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:
orperformBlockForWritingAndWait:
. The reverse is not necessarily true. Specifically…Warning
CallingperformBlockForWritingAndWait:
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. -
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:
- When this method is called inside a write block, the block parameter is executed inline.
- When this method is called in any other context, the block parameter is executed asynchronously on a background queue.
- When executed, the block parameter will have writer status. It is therefore safe to call any instance method of this class inside the 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 toperformBlockForReading:
. The reverse, however, is not true. Specifically…Warning
Calling this method as part of a block passed toperformBlockForReading:
will almost certainly cause deadlock! -
Modify the internal store. Optionally appends annotations instead of replacing them.
Note
Subclassing Note: If you override this method and modify additional internal state of your subclass, wrap the modifications as well as the call tosuper
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 tosuper
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 tosuper
in aperformLockForWritingAndWait:
. 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 returnfalse
. So when you are inheriting from this class, you must callclearNeedsSaveFlag
when implementingsaveAnnotationsWithOptions: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 aperformLockForWritingAndWait:
. 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 tosuper
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 inPSPDFAnnotationManager.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:
. BothPSPDFFileAnnotationProvider
andPSPDFXFDFAnnotationProvider
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 tosuper
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:
. BothPSPDFFileAnnotationProvider
andPSPDFXFDFAnnotationProvider
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 tosuper
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 tosuper
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(_:)
orperformWriteAndWait(_:)
. 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:
When this method is called inside a write block, the block parameter is executed inline.
When this method is called in any other context, the block parameter is executed asynchronously on a background queue.
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 toperformRead(_:)
. The reverse, however, is not true. Specifically…Warning
Calling
performWriteAndWait(_:)
as part of a closure passed toperformRead(_:)
will almost certainly cause deadlock!Declaration
Swift
public func performWriteAndWait<Result>(_ operation: () -> Result) -> Result
Parameters
operation
A closure to synchronize.