PSPDFViewControllerDelegate
Objective-C
@protocol PSPDFViewControllerDelegate <NSObject>
Swift
protocol PDFViewControllerDelegate : NSObjectProtocol
Implement this delegate in your UIViewController
to get notified of PDFViewController
events.
-
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. usedocument.isValid
to check.Declaration
Objective-C
- (void)pdfViewController:(nonnull PSPDFViewController *)pdfController didChangeDocument:(nullable PSPDFDocument *)document;
Swift
optional func pdfViewController(_ pdfController: PDFViewController, didChange document: Document?)
-
Called when a page view schedules a render task to update its content view.
Once the render tasks completes,
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 acquired 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 before a page view enters the visible screen area.
You can use this method to customize the page view before it is displayed. Say, for example, you’ve built a custom user interface for searching, you can use this method to add the search highlights to the page before it comes on screen.
This call is bound to the page view’s spread view and will be triggered before the spread view enters the visible screen area. As such, you should generally avoid to begin view animations on the page in this callback: CoreAnimation may skip the animation of off-screen elements. If you want to animate changes to the page’s view hierarchy, have a look at
PSPDFDocumentViewControllerSpreadIndexDidChangeNotification
instead.This call will not be invoked for page views belonging to spreads that have an active first responder. This matches the behavior of similar
UICollectionViewDelegate
callbacks.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.
This call is bound to the page view’s spread view and will be triggered when the spread view leaves the visible screen area.
This call will not be invoked for page views belonging to spreads that have an active first responder. This matches the behavior of similar
UICollectionViewDelegate
callbacks.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?
-
Called when text is about to be selected. Return NO to disable text selection.
Declaration
Objective-C
- (BOOL)pdfViewController:(nonnull PSPDFViewController *)pdfController shouldSelectText:(nonnull NSString *)text withGlyphs:(nonnull NSArray<PSPDFGlyph *> *)glyphs atRect:(CGRect)rect onPageView:(nonnull PSPDFPageView *)pageView;
Swift
optional func pdfViewController(_ pdfController: PDFViewController, shouldSelectText text: String, with glyphs: [PSPDFGlyph], at rect: CGRect, on pageView: PSPDFPageView) -> Bool
-
Called after text has been selected. Will also be called when text has been deselected. Deselection sometimes cannot be stopped, so the
shouldSelectText:
will be skipped.Declaration
Objective-C
- (void)pdfViewController:(nonnull PSPDFViewController *)pdfController didSelectText:(nonnull NSString *)text withGlyphs:(nonnull NSArray<PSPDFGlyph *> *)glyphs atRect:(CGRect)rect onPageView:(nonnull PSPDFPageView *)pageView;
Swift
optional func pdfViewController(_ pdfController: PDFViewController, didSelectText text: String, with glyphs: [PSPDFGlyph], at rect: CGRect, on pageView: PSPDFPageView)
-
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
’sidentifier
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 thepageView
.annotationRect
ortextRect
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. Theidentifier
property of thePSPDFMenuItem
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]
-
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.
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
PDFPageView
. -
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:
anddidDeselectAnnotations:
subclass hooks ofPDFPageView
.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:
anddidDeselectAnnotations:
subclass hooks ofPDFPageView
.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 forisOverlay
)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 forisOverlay
)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;
-
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)
-
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)
-
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.
-
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)
-
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 sub-action 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 sub-action the action has.Declaration
Objective-C
- (void)pdfViewController:(nonnull PSPDFViewController *)pdfController didExecuteAction:(nonnull PSPDFAction *)action;
Swift
optional func pdfViewController(_ pdfController: PDFViewController, didExecute action: Action)
-
Deprecated
Deprecated in PSPDFKit 9.5 for iOS. Add your own gesture recognizer instead.
Warning
This delegate method has been removed in PSPDFKit 9.5 and is no longer called. You must add your own tap gesture recognizer and use the interaction components to set up relationships with the internal gesture recognizrs. For more information, check out the migration guide: https://pspdfkit.com/guides/ios/current/migration-guides/pspdfkit-95-migration-guideDeclaration
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
-
Deprecated
Deprecated in PSPDFKit 9.5 for iOS. Add your own gesture recognizer instead.
Warning
This delegate method has been removed in PSPDFKit 9.5 and is no longer called. You must add your own long press gesture recognizer and use the interaction components to set up relationships with the internal gesture recognizers. For more information, check out the migration guide: https://pspdfkit.com/guides/ios/current/migration-guides/pspdfkit-95-migration-guideDeclaration
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