PSPDFAnnotationProviderRefreshing

Objective-C

@protocol PSPDFAnnotationProviderRefreshing <PSPDFAnnotationProvider>

Swift

protocol PSPDFAnnotationProviderRefreshing : AnnotationProvider

Protocol to be implemented by any annotation provider that allows refreshing of its annotations in response to an external change, like from -[PSPDFDocumentProvider setRotationOffset:forPageAtIndex:]. To put that in other words, an annotation provider must implement this protocol for temporary page rotations to work correctly.

However, this protocol is deprecated because it is very hard to implement correctly. PSPDFContainerAnnotationProvider conforms to this protocol, which means that PSPDFKit can handle refreshing annotations internally. In a future release, this protocol will be removed, and PSPDFContainerAnnotationProvider will continue to implement refreshing internally.

  • Tells the receiver to flush any annotation changes to its store.

    Locking Considerations

    This method is called inside a write block (see -performBlockForWritingAndWait:) before a change that requires a refresh (like rotating a page) is performed. Try to avoid additional locking when implementing this method to minimize the risk of introducing lock inversions.

    Declaration

    Objective-C

    - (void)prepareForRefresh;

    Swift

    func prepareForRefresh()
  • Called when the annotation provider should refresh its annotations for pages at the specified index. This method is usually called when a property of the page needs to be changed, like in -[PSPDFDocumentProvider setRotation:forPageAtIndex:].

    Locking Considerations

    This method is called inside a write block (see -performBlockForWritingAndWait:) after a change that requires a refresh (like rotating a page) is performed. Try to avoid additional locking when implementing this method to minimize the risk of introducing lock inversions.

    The sequence of events for a refresh is as follows:

    1. -performBlockForWritingAndWait: is called.
    2. The writeBlock() is entered. The next steps are all within the write block.
    3. -prepareForRefresh is called on all providers conforming to this protocol.
    4. The page property requiring a refresh is changed (e.g. The page rotation).
    5. -refreshAnnotationsForPagesAtIndexes: is called on all providers.
    6. The writeBlock completes and returns.

    Declaration

    Objective-C

    - (void)refreshAnnotationsForPagesAtIndexes:(nonnull NSIndexSet *)pageIndexes;

    Swift

    func refreshAnnotationsForPages(at pageIndexes: IndexSet)

    Parameters

    pageIndexes

    An NSIndexSet containing indexes of the pages that should be refreshed.

  • Called before -prepareForRefresh and -refreshAnnotationsForPagesAtIndexes:. This method is called to encapsulate a “prepare, change, and refresh” transaction You should acquire any required locks, and then call the writeBlock(). Once writeBlock returns, release the lock and return from the method.

    If your annotation provider inherits from PSPDFContainerAnnotationProvider, please use its -performBlockForReading:, -performBlockForWriting: and -performBlockForWritingAndWait: methods to implement all your locking requirements, and do not override any of them. If you cannot inherit from PSPDFContainerAnnotationProvider, the easiest way to achieve correct behavior, is to use a single (recursive) lock for all synchronization purposes, and implement this method by acquiring that lock, calling the block, and then releasing the lock again.

    As this lock has to be coordinated with other annotation providers, try to avoid additional locking within your implementations of -prepareForRefresh and -refreshAnnotationsForPagesAtIndexes: to minimize the risk of introducing lock inversions.

    Note

    It is important that this be synchronous.

    Declaration

    Objective-C

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

    Swift

    func performBlock(forWritingAndWait writeBlock: @escaping () -> Void)

    Parameters

    writeBlock

    The block that should be called when the locks are acquired.