PSPDFViewControllerDelegate

Objective-C

@protocol PSPDFViewControllerDelegate <NSObject>

Swift

protocol PDFViewControllerDelegate : NSObjectProtocol

Implement this delegate in your UIViewController to get notified of PSPDFViewController events.

Document Handling

  • Asks the delegate if the specified document should be saved with the provided options.

    Note

    This method will only be called if the view controller’s PSPDFConfiguration autosave option is set to YES, and its annotation save mode is set to a value other than PSPDFAnnotationSaveModeDisabled.

    Declaration

    Objective-C

    - (BOOL)pdfViewController:(nonnull PSPDFViewController *)pdfController
       shouldSaveDocument:(nonnull PSPDFDocument *)document
              withOptions:(NSDictionary<PSPDFDocumentSaveOption, id> *_Nonnull
                               *_Nonnull)options;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, shouldSave document: Document, withOptions options: AutoreleasingUnsafeMutablePointer<NSDictionary>) -> Bool

    Parameters

    pdfController

    The PSPDFViewController instance.
    document

    The document to save.
    options

    The current options that the document is going to be saved with. This is an inout parameter.

    Return Value

    BOOL indicating whether the passed document should be saved with the passed parameters.

  • Notifies the delegate that the specified document’s saving operation was completed.

    Note

    This method will only be called if the view controller’s PSPDFConfiguration autosave option is set to YES, and its annotation save mode is set to a value other than PSPDFAnnotationSaveModeDisabled.

    Declaration

    Objective-C

    - (void)pdfViewController:(nonnull PSPDFViewController *)pdfController
          didSaveDocument:(nonnull PSPDFDocument *)document
                    error:(nullable NSError *)error;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, didSave document: Document, error: Error?)

    Parameters

    pdfController

    The PSPDFViewController instance.
    document

    The document that was saved.
    error

    The error that occurred during document saving, if any. Can be nil.

  • Will be called when an action tries to change the document (For example, a PDF link annotation pointing to another document). Will also be called when the document is changed via using the document property. Return NO to block changing the document.

    Declaration

    Objective-C

    - (BOOL)pdfViewController:(nonnull PSPDFViewController *)pdfController
     shouldChangeDocument:(nullable PSPDFDocument *)document;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, shouldChange document: Document?) -> Bool

  • Will be called after the document has been changed.

    Note

    This will also be called for nil and broken documents. use document.isValid to check.

    Declaration

    Objective-C

    - (void)pdfViewController:(nonnull PSPDFViewController *)pdfController
        didChangeDocument:(nullable PSPDFDocument *)document;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, didChange document: Document?)

Scroll and Page Events

  • Called when a page view schedules a render task to update its content view.

    Once the render taks completed, pdfViewController:didFinishRenderTaskForPageView: will be called.

    See

    pdfViewController:didFinishRenderTaskForPageView:

    Declaration

    Objective-C

    - (void)pdfViewController:(nonnull PSPDFViewController *)pdfController
    willScheduleRenderTaskForPageView:(nonnull PSPDFPageView *)pageView;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, willScheduleRenderTaskFor pageView: PSPDFPageView)

    Parameters

    pdfController

    The pdf view controller the page view belongs to.
    pageView

    The page view that scheduled the render task.

  • Called when a render task finishes that was scheduled by a page view to update its content view.

    See

    pdfViewController:willScheduleRenderTaskForPageView:

    Declaration

    Objective-C

    - (void)pdfViewController:(nonnull PSPDFViewController *)pdfController
    didFinishRenderTaskForPageView:(nonnull PSPDFPageView *)pageView;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, didFinishRenderTaskFor pageView: PSPDFPageView)

    Parameters

    pdfController

    The pdf view controller the page view belongs to.
    pageView

    The page view that scheduled the render task.

  • Called when a page view sets an image on its content view. This image can either be a full sized image, a smaller image that is used while waiting for a full sized image, or nil. The image might be aquired from the cache or from a render task.

    Declaration

    Objective-C

    - (void)pdfViewController:(nonnull PSPDFViewController *)pdfController
    didUpdateContentImageForPageView:(nonnull PSPDFPageView *)pageView
                       isPlaceholder:(BOOL)placeholder;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, didUpdateContentImageFor pageView: PSPDFPageView, isPlaceholder placeholder: Bool)

    Parameters

    pdfController

    The pdf view controller the page view belongs to.
    pageView

    The page view that updated its content view’s image.
    placeholder

    YES if the image set in the content view is just a placeholder while waiting for a full resolution image from the render engine. The placeholder image might also be nil.

  • Called when a page view is about to enter the visible screen area.

    Note

    This call is bound to the page view’s spread view and will be triggered as soon as the spread view enters the visible screen area.

    Declaration

    Objective-C

    - (void)pdfViewController:(nonnull PSPDFViewController *)pdfController
    willBeginDisplayingPageView:(nonnull PSPDFPageView *)pageView
                 forPageAtIndex:(NSInteger)pageIndex;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, willBeginDisplaying pageView: PSPDFPageView, forPageAt pageIndex: Int)

    Parameters

    pdfController

    The pdf view controller the page view belongs to.
    pageView

    The page view that is about to enter the visible screen.
    pageIndex

    The page index of the page that this page view will display.

  • Called when a page view exits the visible screen area.

    Note

    This call is bound to the page view’s spread view and will be triggered when the spread view leaves the visible screen area.

    Declaration

    Objective-C

    - (void)pdfViewController:(nonnull PSPDFViewController *)pdfController
    didEndDisplayingPageView:(nonnull PSPDFPageView *)pageView
              forPageAtIndex:(NSInteger)pageIndex;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, didEndDisplaying pageView: PSPDFPageView, forPageAt pageIndex: Int)

    Parameters

    pdfController

    The pdf view controller the page view belongs to.
    pageView

    The page view that exits the visible screen.
    pageIndex

    The page index of the page that this page view has displayed.

  • Called when a page view is configured for the view hierarchy.

    Declaration

    Objective-C

    - (void)pdfViewController:(nonnull PSPDFViewController *)pdfController
     didConfigurePageView:(nonnull PSPDFPageView *)pageView
           forPageAtIndex:(NSInteger)pageIndex;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, didConfigurePageView pageView: PSPDFPageView, forPageAt pageIndex: Int)

    Parameters

    pdfController

    The pdf view controller the page view belongs to.
    pageView

    The page view that is configured for the view hierarchy.
    pageIndex

    The page index of the page that this page view will display.

  • Called when a page view is cleaned up from the view hierarchy.

    Declaration

    Objective-C

    - (void)pdfViewController:(nonnull PSPDFViewController *)pdfController
       didCleanupPageView:(nonnull PSPDFPageView *)pageView
           forPageAtIndex:(NSInteger)pageIndex;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, didCleanupPageView pageView: PSPDFPageView, forPageAt pageIndex: Int)

    Parameters

    pdfController

    The pdf view controller the page view belongs to.
    pageView

    The page view that is removed from the view hierarchy.
    pageIndex

    The page index of the page that this page view has displayed.

  • Return a PSPDFDocument for a relative path. If this returns nil, we try to find the PDF ourselves with using the current document’s basePath.

    Declaration

    Objective-C

    - (nullable PSPDFDocument *)pdfViewController:
                                (nonnull PSPDFViewController *)pdfController
                      documentForRelativePath:(nonnull NSString *)relativePath;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, documentForRelativePath relativePath: String) -> Document?

  • didTapOnPageView: will be called if a user taps on the page view.

    Taps that can’t be associated to a specific pageView will still call this method, but pageView is nil and the point will be relative to the view of the PSPDFViewController. This doesn’t mean that this method is called when a tap is outside the pageView.

    Return YES if you want to set this touch as processed; this will disable automatic touch processing like showing/hiding the userInterfaceView or scrolling to the next/previous page.

    Note

    This will not send events when the controller is in thumbnail view.

    PSPDFPageCoordinates has been replaced by just CGPoint viewPoint. You can easily calculate other needed coordinates: e.g. to get the pdfPoint: [pageView convertPoint:viewPoint toCoordinateSpace:pageView.pdfCoordinateSpace] screenPoint: [pageView convertPoint:tapPosition fromView:pageView] zoomScale: pageView.zoomView.zoomScale pageInfo: pageView.pageInfo

    Declaration

    Objective-C

    - (BOOL)pdfViewController:(nonnull PSPDFViewController *)pdfController
         didTapOnPageView:(nonnull PSPDFPageView *)pageView
                  atPoint:(CGPoint)viewPoint;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, didTapOn pageView: PSPDFPageView, at viewPoint: CGPoint) -> Bool

  • Similar to didTapOnPageView: invoked after 0.35 sec of tap-holding. LongPress and tap are mutually exclusive. Return YES if you custom-process that event.

    Default handling is (if available) text selection; showing the magnification-loupe. The gestureRecognizer helps you evaluating the state; as this delegate is called on every touch-move.

    Note that there may be unexpected results if you only capture some events (thus, return YES on some movements during the recognition state) as e.g. you might not give the system a chance to clean up the magnification loupe. Either consume all or no events for a recognition cycle.

    Declaration

    Objective-C

    - (BOOL)pdfViewController:(nonnull PSPDFViewController *)pdfController
    didLongPressOnPageView:(nonnull PSPDFPageView *)pageView
                   atPoint:(CGPoint)viewPoint
         gestureRecognizer:
             (nonnull UILongPressGestureRecognizer *)gestureRecognizer;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, didLongPressOn pageView: PSPDFPageView, at viewPoint: CGPoint, gestureRecognizer: UILongPressGestureRecognizer) -> Bool

Text Selection

Menu Handling

  • Called before the menu for text selection is displayed. All coordinates are in view coordinate space.

    Using PSPDFMenuItem will help with adding custom menu’s w/o hacking the responder chain. Default returns menuItems if not implemented. Return nil or an empty array to not show the menu.

    Use PSPDFMenuItem’s identifier property to check and modify the menu items. This string will not be translated. (vs the title property)

    rect is in the coordinate space of the pageView. annotationRect or textRect is in the PDF coordinate space of the current page.

    Declaration

    Objective-C

    - (nonnull NSArray<PSPDFMenuItem *> *)
        pdfViewController:(nonnull PSPDFViewController *)pdfController
      shouldShowMenuItems:(nonnull NSArray<PSPDFMenuItem *> *)menuItems
    atSuggestedTargetRect:(CGRect)rect
          forSelectedText:(nonnull NSString *)selectedText
                   inRect:(CGRect)textRect
               onPageView:(nonnull PSPDFPageView *)pageView;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, shouldShow menuItems: [PSPDFMenuItem], atSuggestedTargetRect rect: CGRect, forSelectedText selectedText: String, in textRect: CGRect, on pageView: PSPDFPageView) -> [PSPDFMenuItem]

  • Called before the menu for a selected image is displayed.

    Declaration

    Objective-C

    - (nonnull NSArray<PSPDFMenuItem *> *)
        pdfViewController:(nonnull PSPDFViewController *)pdfController
      shouldShowMenuItems:(nonnull NSArray<PSPDFMenuItem *> *)menuItems
    atSuggestedTargetRect:(CGRect)rect
         forSelectedImage:(nonnull PSPDFImageInfo *)selectedImage
                   inRect:(CGRect)textRect
               onPageView:(nonnull PSPDFPageView *)pageView;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, shouldShow menuItems: [PSPDFMenuItem], atSuggestedTargetRect rect: CGRect, forSelectedImage selectedImage: PSPDFImageInfo, in textRect: CGRect, on pageView: PSPDFPageView) -> [PSPDFMenuItem]

  • Called before we’re showing the menu for an annotation. If annotation is nil, we show the menu to create new annotations (in that case annotationRect will also be nil) This delegate is also called as you dig into sub-menus like the color options.

    Note

    You should filter out unwanted menu items as a blacklist - if you try to whitelist menu items, you might break functionality, unless you explore every annotation type and every sub-menu and very carefully allow all entries. The idenfifier property of the PSPDFMenuItem object is not loacalized and perfect for comparison.

    Declaration

    Objective-C

    - (nonnull NSArray<PSPDFMenuItem *> *)
        pdfViewController:(nonnull PSPDFViewController *)pdfController
      shouldShowMenuItems:(nonnull NSArray<PSPDFMenuItem *> *)menuItems
    atSuggestedTargetRect:(CGRect)rect
           forAnnotations:(nullable NSArray<PSPDFAnnotation *> *)annotations
                   inRect:(CGRect)annotationRect
               onPageView:(nonnull PSPDFPageView *)pageView;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, shouldShow menuItems: [PSPDFMenuItem], atSuggestedTargetRect rect: CGRect, for annotations: [Annotation]?, in annotationRect: CGRect, on pageView: PSPDFPageView) -> [PSPDFMenuItem]

Annotations

  • Called before a annotation view is created and added to a page. Defaults to YES if not implemented.

    Warning

    This will only be called for annotations that render as an overlay (that return YES for isOverlay) If NO is returned, viewForAnnotation will not be called.

    Declaration

    Objective-C

    - (BOOL)pdfViewController:(nonnull PSPDFViewController *)pdfController
    shouldDisplayAnnotation:(nonnull PSPDFAnnotation *)annotation
                 onPageView:(nonnull PSPDFPageView *)pageView;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, shouldDisplay annotation: Annotation, on pageView: PSPDFPageView) -> Bool

  • Delegate for tapping annotations. Will be called before the more general didTapOnPageView: if an annotationView is hit.

    Return YES to override the default action and custom-handle this. Default actions might be scroll to target page, open Safari, show a menu, …

    Some annotations might not have an annotationView attached. (because they are rendered with the page content, for example highlight annotations)

    Note

    This will not fire if you interact with annotation views like the PSPDFGalleryView. See these subclasses for details (e.g. PSPDFMediaPlayerControllerPlaybackDidStartNotification)

    Declaration

    Objective-C

    - (BOOL)pdfViewController:(nonnull PSPDFViewController *)pdfController
       didTapOnAnnotation:(nonnull PSPDFAnnotation *)annotation
          annotationPoint:(CGPoint)annotationPoint
           annotationView:
               (nullable UIView<PSPDFAnnotationPresenting> *)annotationView
                 pageView:(nonnull PSPDFPageView *)pageView
                viewPoint:(CGPoint)viewPoint;

    Parameters

    annotationPoint

    the point relative to the PSPDFAnnotation, in PDF coordinate space.
    viewPoint

    the point relative to the PSPDFPageView.

  • Called before an annotation will be selected. (but after didTapOnAnnotation:)

    Declaration

    Objective-C

    - (nonnull NSArray<PSPDFAnnotation *> *)
          pdfViewController:(nonnull PSPDFViewController *)pdfController
    shouldSelectAnnotations:(nonnull NSArray<PSPDFAnnotation *> *)annotations
                 onPageView:(nonnull PSPDFPageView *)pageView;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, shouldSelect annotations: [Annotation], on pageView: PSPDFPageView) -> [Annotation]

  • Called after an annotation has been selected by a touch directly on the page view.

    Note that this method isn’t called for indirect selections, for example when a newly created annotation is selected, a set of annotations are selected using the selection tool, or an annotation is selected via the list of annotations.

    For exact diff tracking, consider using the didSelectAnnotations: and didDeselectAnnotations: subclass hooks of PSPDFPageView.

    Declaration

    Objective-C

    - (void)pdfViewController:(nonnull PSPDFViewController *)pdfController
     didSelectAnnotations:(nonnull NSArray<PSPDFAnnotation *> *)annotations
               onPageView:(nonnull PSPDFPageView *)pageView;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, didSelect annotations: [Annotation], on pageView: PSPDFPageView)

  • Called after an annotation has been deselected by a touch directly on the page view.

    Note that this method isn’t called for indirect selections, for example when a newly created annotation is selected, a set of annotations are selected using the selection tool, or an annotation is selected via the list of annotations.

    For exact diff tracking, consider using the didSelectAnnotations: and didDeselectAnnotations: subclass hooks of PSPDFPageView.

    Declaration

    Objective-C

    - (void)pdfViewController:(nonnull PSPDFViewController *)pdfController
    didDeselectAnnotations:(nonnull NSArray<PSPDFAnnotation *> *)annotations
                onPageView:(nonnull PSPDFPageView *)pageView;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, didDeselect annotations: [Annotation], on pageView: PSPDFPageView)

  • Returns a pre-generated annotationView that can be modified before being added to the view. If no generator for a custom annotation is found, annotationView will be nil (as a replacement to viewForAnnotation) To get the targeted rect use [annotation boundingBoxForPageRect:pageView.bounds];

    Declaration

    Objective-C

    - (nullable UIView<PSPDFAnnotationPresenting> *)
    pdfViewController:(nonnull PSPDFViewController *)pdfController
       annotationView:
           (nullable UIView<PSPDFAnnotationPresenting> *)annotationView
        forAnnotation:(nonnull PSPDFAnnotation *)annotation
           onPageView:(nonnull PSPDFPageView *)pageView;

  • Invoked prior to the presentation of the annotation view: use this to configure actions etc

    Warning

    This will only be called for annotations that render as an overlay (that return YES for isOverlay) PSPDFLinkAnnotations are handled differently (they don’t have a selected state) - delegate will not be called for those.

    Declaration

    Objective-C

    - (void)pdfViewController:(nonnull PSPDFViewController *)pdfController
    willShowAnnotationView:
        (nonnull UIView<PSPDFAnnotationPresenting> *)annotationView
                onPageView:(nonnull PSPDFPageView *)pageView;

  • Invoked after animation used to present the annotation view

    Warning

    This will only be called for annotations that render as an overlay (that return YES for isOverlay) PSPDFLinkAnnotations are handled differently (they don’t have a selected state) - delegate will not be called for those.

    Declaration

    Objective-C

    - (void)pdfViewController:(nonnull PSPDFViewController *)pdfController
    didShowAnnotationView:
        (nonnull UIView<PSPDFAnnotationPresenting> *)annotationView
               onPageView:(nonnull PSPDFPageView *)pageView;

View Controller Management

  • Called before we show a internal controller (color picker, note editor, …) modally or in a popover. Allows last minute modifications.

    Return NO to process the displaying manually.

    Declaration

    Objective-C

    - (BOOL)pdfViewController:(nonnull PSPDFViewController *)pdfController
     shouldShowController:(nonnull UIViewController *)controller
                  options:(nullable NSDictionary<NSString *, id> *)options
                 animated:(BOOL)animated;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, shouldShow controller: UIViewController, options: [String : Any]? = nil, animated: Bool) -> Bool

  • Called after the controller has been fully displayed.

    Declaration

    Objective-C

    - (void)pdfViewController:(nonnull PSPDFViewController *)pdfController
        didShowController:(nonnull UIViewController *)controller
                  options:(nullable NSDictionary<NSString *, id> *)options
                 animated:(BOOL)animated;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, didShow controller: UIViewController, options: [String : Any]? = nil, animated: Bool)

General View State

  • Will be called when viewMode changes.

    Declaration

    Objective-C

    - (void)pdfViewController:(nonnull PSPDFViewController *)pdfController
        didChangeViewMode:(PSPDFViewMode)viewMode;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, didChange viewMode: ViewMode)

  • Called before the view controller will be dismissed (either by modal dismissal, or popping from the navigation stack). Called before PSPDFKit tries to save any dirty annotation.

    Note

    If you use child view containment then the dismissal might not be properly detected.

    Declaration

    Objective-C

    - (void)pdfViewControllerWillDismiss:
    (nonnull PSPDFViewController *)pdfController;

    Swift

    optional func pdfViewControllerWillDismiss(_ pdfController: PDFViewController)

  • Called after the view controller has been dismissed (either by modal dismissal, or popping from the navigation stack).

    Note

    If you use child view containment then the dismissal might not be properly detected.

    Declaration

    Objective-C

    - (void)pdfViewControllerDidDismiss:
    (nonnull PSPDFViewController *)pdfController;

    Swift

    optional func pdfViewControllerDidDismiss(_ pdfController: PDFViewController)

Display State

  • Called after the view controller changed its controller state or its controller state error.

    Declaration

    Objective-C

    - (void)pdfViewController:(nonnull PSPDFViewController *)pdfController
    didChangeControllerState:(PSPDFControllerState)controllerState
                       error:(nullable NSError *)error;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, didChange controllerState: ControllerState, error: Error?)

    Parameters

    pdfController

    The controller that changed its state.
    controllerState

    The new state that the controller was changed to.
    error

    The underlying error if the controllerState provided is either .error or .locked.

user interface

  • Return NO to stop the user interface change event.

    Declaration

    Objective-C

    - (BOOL)pdfViewController:(nonnull PSPDFViewController *)pdfController
    shouldShowUserInterface:(BOOL)animated;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, shouldShowUserInterface animated: Bool) -> Bool

  • User interface was displayed (called after the animation finishes)

    Declaration

    Objective-C

    - (void)pdfViewController:(nonnull PSPDFViewController *)pdfController
     didShowUserInterface:(BOOL)animated;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, didShowUserInterface animated: Bool)

  • Return NO to stop the user interface change event.

    Declaration

    Objective-C

    - (BOOL)pdfViewController:(nonnull PSPDFViewController *)pdfController
    shouldHideUserInterface:(BOOL)animated;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, shouldHideUserInterface animated: Bool) -> Bool

  • User interface was hidden (called after the animation finishes)

    Declaration

    Objective-C

    - (void)pdfViewController:(nonnull PSPDFViewController *)pdfController
     didHideUserInterface:(BOOL)animated;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, didHideUserInterface animated: Bool)

Actions

  • Called every time before an action will be executed. Actions can come from many sources: Links, Forms, or any other annotation type (via additionalActions) Actions can be invoked on trigger events like PSPDFAnnotationTriggerEventMouseDown. Using the back/forward list will also trigger actions.

    Return NO to prevent the PDF action from being executed.

    Note

    This is also called for every subaction the action has.

    Declaration

    Objective-C

    - (BOOL)pdfViewController:(nonnull PSPDFViewController *)pdfController
      shouldExecuteAction:(nonnull PSPDFAction *)action;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, shouldExecute action: Action) -> Bool

  • Called every time after an action has been executed.

    Note

    This is also called for every subaction the action has.

    Declaration

    Objective-C

    - (void)pdfViewController:(nonnull PSPDFViewController *)pdfController
         didExecuteAction:(nonnull PSPDFAction *)action;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, didExecute action: Action)