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.

    This delegate method is not called if the Document being shared has its annotationSaveMode set to disabled.

    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?)

  • 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 an 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

  • Called when a user taps on an annotation but before PSPDFKit continues handling the touch. This allows the delegate to implement custom behavior that happens just before the annotation becomes selected or form element becomes focused.

    Note

    This method isn’t called if a user interacts with annotation views like the PSPDFGalleryView. See these subclasses for more 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;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, didTapOn annotation: Annotation, annotationPoint: CGPoint, annotationView: (UIView & AnnotationPresenting)?, pageView: PSPDFPageView, viewPoint: CGPoint) -> Bool

    Return Value

    A boolean value that, if true, cancels PSPDFKit’s further touch handling (like selecting an annotation, presenting menus, opening links).

  • Called when annotations are about to become selected.

    This method is called after the didTapOnAnnotation method but before the didSelectAnnotations and didDeselectAnnotations methods. This method isn’t called when selecting annotations programmatically.

    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]

    Return Value

    An array containing a subset or none of the given annotations.

  • Called after annotations have been selected as a result of direct user interaction on a page view.

    This method is called after the shouldSelectAnnotations method but before the didDeselectAnnotations method.

    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. It’s also not called when selecting the annotations programmatically. For exact diff tracking, consider implementing the PSPDFPageView/didSelectAnnotations: and PSPDFPageView/didDeselectAnnotations: subclassing hooks instead.

    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.

    This method is called after the didSelectAnnotations method.

    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. It’s also not called when selecting the annotations programmatically. For exact diff tracking, consider implementing the PSPDFPageView/didSelectAnnotations: and PSPDFPageView/didDeselectAnnotations: subclassing hooks instead.

    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)

  • Customization point to modify or replace the view for showing an annotation.

    The default view PSPDFKit would use is passed into this method as annotationView. This view can be modified and then returned, or you can return an entirely different view. For custom annotations types, the passed in annotationView will be nil. You probably don’t want to return nil from this method because that will result in the annotation disappearing when PSPDFKit tries to put it in the annotation view. If you don’t need any customizations for a particular annotation, return annotationView without modifying it.

    To get the targeted rect use annotation.boundingBox(forPageRect: 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;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, annotationView: (UIView & AnnotationPresenting)?, for annotation: Annotation, on pageView: PSPDFPageView) -> (UIView & AnnotationPresenting)?

    Parameters

    pdfController

    The PDF view controller displaying the document.
    annotationView

    The proposed view for displaying the annotation.
    annotation

    The annotation to be displayed.
    pageView

    The view for the page the annotation is on.

    Return Value

    The view for displaying the annotation.

  • 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;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, willShowAnnotationView annotationView: UIView & AnnotationPresenting, on pageView: PSPDFPageView)

  • 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;

    Swift

    optional func pdfViewController(_ pdfController: PDFViewController, didShowAnnotationView annotationView: UIView & AnnotationPresenting, on pageView: PSPDFPageView)

  • Called before we show an internal view 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)

  • Allow the delegate to customize the menu for creating an annotation.

    The view controller will call this method just before the menu for creating an annotation is presented. This method will not be called before any of the sub-menus are presented.

    If you just want to exclude certain annotation types from appearing in the menu, consider customizing createAnnotationMenuGroups configuration property instead.

    Backwards Compatibility Considerations

    Historically, there have been multiple ways to customize the menu for creating an annotation:

    • pdfViewController:menuForCreatingAnnotationAtPoint:onPageView:appearance:suggestedMenu: — this delegate method that allows you to customize the menu directly,

    • pdfViewController:shouldShowMenuItems:atSuggestedTargetRect:forAnnotations:inRect:onPageView: (deprecated) — the legacy equivalent of this method that allowed you to customize the legacy menu items directly,

    • PSPDFPageView/menuItemsForNewAnnotationAtPoint: (deprecated) – the legacy subclassing hook for PSPDFPageView subclasses that also allowed you to customize the legacy menu items directly.

    Since the modern menu system based on UIMenuElement and UIMenu is incompatible with the legacy menu system based on UIMenuItem and UIMenuController, one of the two will be used, depending on the following circumstances.

    • If this method is implemented, it’s treated as an explicit opt into the modern menu system, even if one or more legacy methods are still implemented.

    • If this method is unimplemented but one or more legacy method listed above is, the legacy menu system will be used to preserve backwards compatibility during the deprecation period. Note that the legacy menu system is no longer supported and may exhibit problems on all iOS versions.

    • If none of the methods listed above is implemented, the modern menu system will be used by default.

    To learn more about migrating from the legacy menu system to the modern menu system, check out our PSPDFKit 12 for iOS Migration Guide.

    Declaration

    Objective-C

    - (nonnull UIMenu *)pdfViewController:(nonnull PSPDFViewController *)sender
     menuForCreatingAnnotationAtPoint:(CGPoint)point
                           onPageView:(nonnull PSPDFPageView *)pageView
                           appearance:(PSPDFEditMenuAppearance)appearance
                        suggestedMenu:(nonnull UIMenu *)suggestedMenu;

    Swift

    optional func pdfViewController(_ sender: PDFViewController, menuForCreatingAnnotationAt point: CGPoint, onPageView pageView: PSPDFPageView, appearance: EditMenuAppearance, suggestedMenu: UIMenu) -> UIMenu

    Return Value

    A menu for creating an annotation. Returning a menu with no children will cancel the menu presentation.

  • Allow the delegate to customize the menu for selected annotations.

    The view controller will call this method just before the menu for selected annotations is presented. This method will not be called before any of the sub-menus are presented.

    If you want to customize the choices for different style properties, consider customizing annotationMenuConfiguration configuration property instead.

    Important

    Customizing the menu for selected annotations requires Annotation Editing feature to be enabled for your license (or the Electronic Signatures feature when customizing the menu for signature annotations). Even though the menu might be presented for certain types of annotations without either of these features enabled, customizing it isn’t possible in this situation.

    Backwards Compatibility Considerations

    Historically, there have been multiple ways to customize the menu for selected annotations:

    • pdfViewController:menuForAnnotations:onPageView:appearance:suggestedMenu: — this delegate method that allows you to customize the menu directly,

    • pdfViewController:shouldShowMenuItems:atSuggestedTargetRect:forAnnotations:inRect:onPageView: (deprecated) — the legacy equivalent of this method that allowed you to customize the legacy menu items directly,

    • PSPDFPageView/menuItemsForAnnotations: (deprecated) — the legacy subclassing hook for PSPDFPageView subclasses that also allowed you to customize the legacy menu items directly,

    • PSPDFPageView/colorMenuItemsForAnnotation: (deprecated) — the legacy subclassing hook for PSPDFPageView subclasses that allowed you to customize the legacy menu items for choosing color,

    • PSPDFPageView/fillColorMenuItemsForAnnotation: (deprecated) — the legacy subclassing hook for PSPDFPageView subclasses that allowed you to customize the legacy menu items for choosing fill color,

    • PSPDFPageView/opacityMenuItemForAnnotation:withColor: (deprecated) — the legacy subclassing hook for PSPDFPageView subclasses that allowed you to customize the legacy menu item for choosing opacity,

    • PSPDFPageView/defaultColorOptionsForAnnotationType: (deprecated) — the legacy subclassing hook for PSPDFPageView subclasses that allowed you to customize the color choices,

    • availableFontSizes (deprecated) — the legacy subclassing hook for PSPDFPageView subclasses that allowed you to customize the font size choices,

    • availableLineWidths (deprecated) — the legacy subclassing hook for PSPDFPageView subclasses that allowed you to customize the line width choices,

    • shouldMoveStyleMenuEntriesIntoSubmenu (deprecated) — the legacy subclassing hook for PSPDFPageView subclasses that allowed you to customize the appearance of the Style menu.

    Since the modern menu system based on UIMenuElement and UIMenu is incompatible with the legacy menu system based on UIMenuItem and UIMenuController, one of the two will be used, depending on the following circumstances.

    • If this method is implemented, it’s treated as an explicit opt into the modern menu system, even if one or more legacy methods are still implemented.

    • If this method is unimplemented but one or more legacy method listed above is, the legacy menu system will be used to preserve backwards compatibility during the deprecation period. Note that the legacy menu system is no longer supported and may exhibit problems on all iOS versions.

    • If none of the methods listed above is implemented, the modern menu system will be used by default.

    To learn more about migrating from the legacy menu system to the modern menu system, check out our PSPDFKit 12 for iOS Migration Guide.

    Declaration

    Objective-C

    - (nonnull UIMenu *)pdfViewController:(nonnull PSPDFViewController *)sender
                   menuForAnnotations:
                       (nonnull NSArray<PSPDFAnnotation *> *)annotations
                           onPageView:(nonnull PSPDFPageView *)pageView
                           appearance:(PSPDFEditMenuAppearance)appearance
                        suggestedMenu:(nonnull UIMenu *)suggestedMenu;

    Swift

    optional func pdfViewController(_ sender: PDFViewController, menuForAnnotations annotations: [Annotation], onPageView pageView: PSPDFPageView, appearance: EditMenuAppearance, suggestedMenu: UIMenu) -> UIMenu

    Return Value

    A menu for selected annotations. Returning a menu with no children will cancel the menu presentation.

  • Allow the delegate to customize the menu for selected text.

    The view controller will call this method just before the menu for selected text is presented. This method will not be called before any of the sub-menus are presented.

    If you want to customize the choices for annotation tools available in the menu, consider customizing contentMenuConfiguration configuration property instead.

    Important

    Customizing the menu for selected text requires Text Selection feature to be enabled for your license.

    Backwards Compatibility Considerations

    Historically, there have been multiple ways to customize the menu for selected text:

    • pdfViewController:menuForText:onPageView:appearance:suggestedMenu: — this delegate method that allows you to customize the menu directly,

    • pdfViewController:shouldShowMenuItems:atSuggestedTargetRect:forSelectedText:inRect:onPageView: (deprecated) — the legacy equivalent of this method that allowed you to customize the legacy menu items directly,

    • PSPDFPageView/textSelectionMenuItemForCreatingAnnotationWithType: (deprecated) — the legacy subclassing hook for PSPDFPageView subclasses that also allowed you to customize legacy menu items for annotating selected text,

    • PSPDFPageView/textSelectionView:updateMenuAnimated: (deprecated) — the page view’s implementation of the deprecated PSPDFTextSelectionViewDelegate method that presented a legacy menu for currently selected text or image,

    • allowedMenuActions (deprecated) — the legacy configuration property that controlled which actions were available in the legacy menu for selected text or image.

    Since the modern menu system based on UIMenuElement and UIMenu is incompatible with the legacy menu system based on UIMenuItem and UIMenuController, one of the two will be used, depending on the following circumstances.

    • If this method is implemented, it’s treated as an explicit opt into the modern menu system, even if one or more legacy methods are still implemented.

    • If this method is unimplemented but one or more legacy method listed above is, the legacy menu system will be used to preserve backwards compatibility during the deprecation period. Note that the legacy menu system is no longer supported and may exhibit problems on all iOS versions.

    • If none of the methods listed above is implemented, the modern menu system will be used by default.

    To learn more about migrating from the legacy menu system to the modern menu system, check out our PSPDFKit 12.3 for iOS Migration Guide.

    Declaration

    Objective-C

    - (nonnull UIMenu *)pdfViewController:(nonnull PSPDFViewController *)sender
                          menuForText:(nonnull PSPDFGlyphSequence *)glyphs
                           onPageView:(nonnull PSPDFPageView *)pageView
                           appearance:(PSPDFEditMenuAppearance)appearance
                        suggestedMenu:(nonnull UIMenu *)suggestedMenu;

    Swift

    optional func pdfViewController(_ sender: PDFViewController, menuForText glyphs: PSPDFGlyphSequence, onPageView pageView: PSPDFPageView, appearance: EditMenuAppearance, suggestedMenu: UIMenu) -> UIMenu

    Return Value

    A menu for selected text. Returning a menu with no children will cancel the menu presentation.

  • Allow the delegate to customize the menu for selected image.

    The view controller will call this method just before the menu for selected image is presented. This method will not be called before any of the sub-menus are presented.

    Important

    Customizing the menu for selected image requires Text Selection feature to be enabled for your license.

    Backwards Compatibility Considerations

    Historically, there have been multiple ways to customize the menu for selected image:

    • pdfViewController:menuForImage:onPageView:appearance:suggestedMenu: — this delegate method that allows you to customize the menu directly,

    • pdfViewController:shouldShowMenuItems:atSuggestedTargetRect:forSelectedImage:inRect:onPageView: (deprecated) — the legacy equivalent of this method that allowed you to customize the legacy menu items directly,

    • PSPDFPageView/textSelectionView:updateMenuAnimated: (deprecated) — the page view’s implementation of the deprecated PSPDFTextSelectionViewDelegate method that presented a legacy menu for currently selected text or image,

    • allowedMenuActions (deprecated) — the legacy configuration property that controlled which actions were available in the legacy menu for selected text or image.

    Since the modern menu system based on UIMenuElement and UIMenu is incompatible with the legacy menu system based on UIMenuItem and UIMenuController, one of the two will be used, depending on the following circumstances.

    • If this method is implemented, it’s treated as an explicit opt into the modern menu system, even if one or more legacy methods are still implemented.

    • If this method is unimplemented but one or more legacy method listed above is, the legacy menu system will be used to preserve backwards compatibility during the deprecation period. Note that the legacy menu system is no longer supported and may exhibit problems on all iOS versions.

    • If none of the methods listed above is implemented, the modern menu system will be used by default.

    To learn more about migrating from the legacy menu system to the modern menu system, check out our PSPDFKit 12.3 for iOS Migration Guide.

    Declaration

    Objective-C

    - (nonnull UIMenu *)pdfViewController:(nonnull PSPDFViewController *)sender
                         menuForImage:(nonnull PSPDFImageInfo *)image
                           onPageView:(nonnull PSPDFPageView *)pageView
                           appearance:(PSPDFEditMenuAppearance)appearance
                        suggestedMenu:(nonnull UIMenu *)suggestedMenu;

    Swift

    optional func pdfViewController(_ sender: PDFViewController, menuForImage image: PSPDFImageInfo, onPageView pageView: PSPDFPageView, appearance: EditMenuAppearance, suggestedMenu: UIMenu) -> UIMenu

    Return Value

    A menu for selected image. Returning a menu with no children will cancel the menu presentation.

  • Deprecated

    Deprecated in PSPDFKit 12 for iOS. Use ‘pdfViewController(:menuForAnnotations:onPageView:appearance:suggestedMenu:)’ or ‘pdfViewController(:menuForCreatingAnnotationAt:onPageView:appearance:suggestedMenu:)’ instead.

    Allow the delegate to customize the legacy menu for creating an annotation or selecting annotations.

    The view controller will call this method just before the legacy menu for creating an annotation or selecting annotations is about to be presented. This method will also be called as you dig into the sub-menus like color options.

    Warning

    This delegate method is deprecated in favor of the more modern pdfViewController:menuForCreatingAnnotationAtPoint:onPageView:appearance:suggestedMenu: and pdfViewController:menuForAnnotations:onPageView:appearance:suggestedMenu: equivalents. See the documentation of these method to learn more about backwards compatibility considerations.

    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]

    Return Value

    An array of menu items for the legacy menu for creating an annotation or selecting annotations. Returning an empty array will cancel the menu presentation.

  • Deprecated

    Deprecated in PSPDFKit 12.3 for iOS. Use ‘pdfViewController(_:menuForText:onPageView:appearance:suggestedMenu:)’ instead.

    Allow the delegate to customize the menu for selected text.

    The view controller will call this method just before the legacy menu for selected text is about to be presented. This method will not be called before any of the sub-menus are presented.

    Warning

    This delegate method is deprecated in favor of the more modern pdfViewController:menuForText:onPageView:appearance:suggestedMenu: equivalent. See the documentation of this method to learn more about backwards compatibility considerations.

    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]

    Return Value

    An array of menu items for the legacy menu for selected text. Returning an empty array will cancel the menu presentation.

  • Deprecated

    Deprecated in PSPDFKit 12.3 for iOS. Use ‘pdfViewController(_:menuForImage:onPageView:appearance:suggestedMenu:)’ instead.

    Allow the delegate to customize the legacy menu for selected image.

    The view controller will call this method just before the legacy menu for selected image is about to be presented. This method will not be called before any of the sub-menus are presented.

    Warning

    This delegate method is deprecated in favor of the more modern pdfViewController:menuForImage:onPageView:appearance:suggestedMenu: equivalent. See the documentation of this method to learn more about backwards compatibility considerations.

    Declaration

    Objective-C

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

    Swift

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

    Return Value

    An array of menu items for the legacy menu for selected image. Returning an empty array will cancel the menu presentation.