Nutrient iOS SDK 14.2 migration guide

This guide covers updating an iOS, Mac Catalyst, or visionOS project from Nutrient iOS SDK 13.3 through 14.1.1 to Nutrient iOS SDK 14.2. We encourage you to update as soon as possible, in order to take advantage of future new features and fixes.

If you have any trouble with upgrading or doubts about the best migration strategy, get in touch with us through our support platform.

New name

With our new company name, PSPDFKit for iOS is now called Nutrient iOS SDK. No technical details have changed: Our modules are still called PSPDFKit and PSPDFKitUI and are available at the same Swift package URL. We want to make this a smooth transition, so no specific steps are required for the rename.

Removed support for iOS 15

This release removes support for iOS 15 and macOS 12, bringing this version in line with our standard support for the three most recent operating system versions after the release of iOS 18 and macOS 15. Xcode 16.1 or later is required to use this version of our SDK. Learn more in our version support guide.

Ensure your target’s deployment target settings are set to iOS 16.0 or greater and macOS 13.0 or greater.

Note that the App Store allows users on older OS versions to download the last compatible version of an app, even if it‘s not the latest version of that app. If running the latest version of your app on iOS 15 is a requirement for your product, keep using Nutrient iOS SDK 14.1.1, which has been tested on iOS 15.0 through 18.0. However, this release won’t be tested on any subsequent iOS versions, so we recommended moving forward when possible.

System text selection

System text selection — internally driven by UITextInteraction — is now used on document pages. This was a large internal change that has provided improved system integration and a native look and feel. As a result of this, some customization APIs have changed. All older APIs mentioned in this section have been deprecated to make the changes more visible.

Our previous fully custom implementation of text selection was a very good replica of the system behavior, so users shouldn’t notice any significant difference, except for a larger number of available menu items.

Configuration

PDFConfiguration.textSelectionMode no longer has an effect, because system text selection doesn’t support alternative modes, and the automatic behavior of switching based on the input (touch screen or pointer) provides the best user experience.

PDFConfiguration.textSelectionShouldSnapToWord no longer influences text selection. This property is now only used for text markup tools.

TextSelectionView.selectionHitTestExtension no longer has an effect. This API previously provided limited functionality and worked only in certain conditions.

Interaction components

The selectText and deselectText components of DocumentViewInteractions — which previously handled both text and images — are now only used for image selection and deselection. We don’t have replacement interaction components specifically for text selection and deselection. You can use allTextInteractions to customize text selection, text deselection, image selection, and image deselection all together. You could also consider whether the PDFViewControllerDelegate methods pdfViewController(_:shouldSelectText:with:at:on:) and pdfViewController(_:didSelectText:with:at:on:) meet your needs.

We’re interested in bringing back more fine-grained components for text selection, but to do that, it would help us a lot if you let us know how you’re using these APIs.

Text selection menus

In earlier versions, PDFPageView.select(glyphs:presentMenu:animated:) would ignore the presentMenu in some situations where programmatically presenting the menu wasn’t possible. With system text selection, this is never possible, so this parameter is now always ignored.

Nutrient no longer supplies the Define and Search Web text selection menu items, which had the identifiers UIAction.Identifier.PSPDFKit.define and UIAction.Identifier.PSPDFKit.searchWeb, respectively. We instead use the system-provided menu items from UIMenu.Identifier.lookup. If you removed or repositioned the old menu items, check for the system menu instead.

Similarly, we no longer supply a Speak menu item with the UIMenu.Identifier.PSPDFKit.accessibility identifier. If you removed or repositioned the old menu items, check for the system-provided equivalent UIMenu.Identifier.speech instead.

Text-to-speech

Customizing SpeechController no longer has an effect, because Nutrient now uses the system-provided Speak Selection accessibility feature, which provides better handling of multilingual text and language ambiguity. If you want to customize the speech rate, pitch, or language for selected text on page views, replace UIMenu.Identifier.speech with your own menu, as shown in CustomSpeakMenuItemExample.swift in our Catalog app.

Removed previously deprecated APIs

This release removes APIs that were deprecated from Nutrient iOS SDK 12.0 through 13.0.

Warning

If your project uses any of the APIs listed below, you’ll need to update to the replacement as soon as you update to Nutrient iOS SDK 14.2.

Legacy menu APIs

Legacy menu customization APIs that used Apple’s deprecated UIMenuController and UIMenuItem APIs have been removed. For details about migrating to the newer menu APIs, refer to the version 12 migration guide and the version 12.3 migration guide.

  • PDFView.allowedMenuActions
    To configure which annotation tools are available in the menu for selected text, use the contentMenuConfiguration configuration property. To customize the menu for selected text directly, use menuForText. To customize the menu for selected images, use menuForImage.

  • PDFView.onShouldShowMenuItemsForSelectedAnnotations
    Use menuForAnnotations.

  • PDFView.onShouldShowMenuItemsForSelectedImage
    Use menuForImage.

  • PDFView.onShouldShowMenuItemsForSelectedText
    Use menuForText.

  • PDFConfiguration.allowedMenuActions
    To configure which annotation tools are available in the menu for selected text, use the contentMenuConfiguration configuration property. To customize the menu for selected text directly, use the pdfViewController(_:menuForText:onPageView:appearance:suggestedMenu:) delegate method. To customize the menu for selected images, use the pdfViewController(_:menuForImage:onPageView:appearance:suggestedMenu:) delegate method.

  • PDFViewControllerDelegate.pdfViewController(_:shouldShow:atSuggestedTargetRect:for:in:on:)
    Use pdfViewController(_:menuForAnnotations:onPageView:appearance:suggestedMenu:) or pdfViewController(_:menuForCreatingAnnotationAt:onPageView:appearance:suggestedMenu:).

  • PDFViewControllerDelegate.pdfViewController(_:shouldShow:atSuggestedTargetRect:forSelectedImage:in:on:)
    Use pdfViewController(_:menuForImage:onPageView:appearance:suggestedMenu:).

  • PDFViewControllerDelegate.pdfViewController(_:shouldShow:atSuggestedTargetRect:forSelectedText:in:on:)
    Use pdfViewController(_:menuForText:onPageView:appearance:suggestedMenu:).

  • MenuItem
    Use the newer menu APIs.

  • TextSelectionView.discardSelection(animated:)
    Use PDFPageView.discardSelection(animated:).

  • FlexibleToolbar.menuItem(for:), **FlexibleToolbar.showMenu(forCollapsedButtons:from:animated:), and FlexibleToolbar.showMenu(with:target:animated:)
    Use UIButton.menu to add context menus to buttons.

  • PDFPageView.select(_:animated:)
    To select annotations, use select(annotations:presentMenu:animated:). To focus form elements, use focus(formElement:toggleValue:animated:).

  • PDFPageView.showMenuIfSelected(animated:), PDFPageView.showMenuIfSelected(with:animated:), PDFPageView.showMenu(for:animated:), TextSelectionView.updateMenu(animated:), UserInterfaceControls.showMenuIfSelected(with:animated:), and ContextMenuOption
    Programmatically presenting menus is only possible in limited situations. For annotation selection, use select(annotations:presentMenu:animated:) or PDFViewController.interactions.tryToShowAnnotationMenu(at:in:). For image selection, use select(image:presentMenu:animated:). For text selection, programmatically presenting menus isn’t possible.

  • PDFPageView.showAnnotationMenu(at:animated:)
    Use PDFViewController.interactions.tryToShowAnnotationMenu(at:in:).

  • PDFPageView.showMenu(for:targetRect:option:animated:)
    Use select(annotations:presentMenu:animated:).

  • PDFPageView.textSelectionView(_:updateMenuAnimated:)
    Use PDFViewControllerDelegate.pdfViewController(_:menuForText:onPageView:appearance:suggestedMenu:) or PDFViewControllerDelegate.pdfViewController(_:menuForImage:onPageView:appearance:suggestedMenu:).

  • PDFPageView.selectColor(for:isFillColor:)
    Use presentColorPicker(for:property:options:animated:completion:).

  • PDFPageView.useAnnotationInspector(for:)
    Use canPresentInspector(for:).

  • PDFPageView.showInspector(for:options:animated:)
    Use presentInspector(for:options:animated:completion:).

  • PDFPageView.showNoteController(for:animated:)
    Use presentComments(for:options:animated:completion:).

  • PDFPageView.showColorPicker(for:animated:)
    Use presentColorPicker(for:property:options:animated:completion:).

  • PDFPageView.showFontPicker(for:animated:)
    Use presentFontPicker(for:options:animated:completion:).

  • PDFPageView.showLinkPreviewActionSheet(for:from:animated:)
    Use presentLinkActionSheet(for:options:animated:completion:).

  • PDFPageView.menuItemsForNewAnnotation(at:)
    Use PDFConfiguration.createAnnotationMenuGroups or PDFViewControllerDelegate.pdfViewController(_:menuForCreatingAnnotationAt:onPageView:appearance:suggestedMenu:).

  • PDFPageView.menuItems(for:)
    Use PDFViewControllerDelegate.pdfViewController(_:menuForAnnotations:onPageView:appearance:suggestedMenu:).

  • PDFPageView.colorMenuItems(for:)
    Use PDFConfiguration.annotationMenuConfiguration.colorChoices or PDFViewControllerDelegate.pdfViewController(_:menuForAnnotations:onPageView:appearance:suggestedMenu:).

  • PDFPageView.fillColorMenuItems(for:)
    Use PDFConfiguration.annotationMenuConfiguration.colorChoices or PDFViewControllerDelegate.pdfViewController(_:menuForAnnotations:onPageView:appearance:suggestedMenu:).

  • PDFPageView.opacityMenuItem(for:with:)
    Use PDFConfiguration.annotationMenuConfiguration.alphaChoices or PDFViewControllerDelegate.pdfViewController(_:menuForAnnotations:onPageView:appearance:suggestedMenu:).

  • PDFPageView.textSelectionMenuItemForCreatingAnnotation(withType:)
    Use PDFConfiguration.contentMenuConfiguration.annotationToolChoices or PDFViewControllerDelegate.pdfViewController(_:menuForText:onPageView:appearance:suggestedMenu:).

  • PDFPageView.defaultColorOptions(for:)
    Use PDFConfiguration.annotationMenuConfiguration.colorChoices.

  • PDFPageView.availableFontSizes
    Use PDFConfiguration.annotationMenuConfiguration.fontSizeChoices.

  • PDFPageView.availableLineWidths
    Use PDFConfiguration.annotationMenuConfiguration.lineWidthChoices.

  • PDFPageView.shouldMoveStyleMenuEntriesIntoSubmenu
    Use PDFViewControllerDelegate.pdfViewController(_:menuForAnnotations:onPageView:appearance:suggestedMenu:).

  • PDFPageView.passthroughViewsForPopoverController
    Use PresentationOption.popoverPassthroughViews when presenting view controllers.

  • TextMenu and TextSelectionMenuAction
    Use UIAction.Identifier or UIMenu.Identifier with the newer menu APIs.

Other removed APIs

  • AnnotationSetStore.annotationSets
    Use fetchAnnotationSets() and setAnnotationSets(_:).

  • SavedAnnotationsViewController.shared
    Renamed to sharedAnnotationStore.

  • UIAction.Identifier.pspdfkit
    Use UIAction.Identifier.PSPDFKit.

  • UIMenu.Identifier.pspdfkit
    Use UIMenu.Identifier.PSPDFKit.

  • Notification.Name.PSPDFAnnotationCreateActionDidInsert and PSPDFAnnotationCreateActionInsertedAnnotationsKey
    Observe Notification.Name.PSPDFAnnotationsAdded.

  • Document.measurementScale and PDFDocumentProvider.measurementScale
    Use Document.activeMeasurementValueConfiguration.scale.

  • Document.measurementPrecision and PDFDocumentProvider.measurementPrecision
    Use Document.activeMeasurementValueConfiguration.precision.

  • PDFDocumentProvider.hashDocumentProviderRange(_:hashAlgorithm:)
    Use hashOfData(inRanges:algorithm:).

  • PDFSignatureInfo.byteRange
    Use byteRanges.

  • PKCS7.create(_:privateKey:certificate:hashAlgorithm:encryptionAlgorithm:)
    Use PKCS7.init(digest:type:privateKey:certificate:hashAlgorithm:encryptionAlgorithm:) with CMS as the type.

  • UnitTo.point
    Use a different unit for real-world distances.

  • PDFCache.StoragePolicy
    This type was unused.