PSPDFKit 9.4 Migration Guide

This guide covers updating an iOS or Mac Catalyst project from PSPDFKit 9.3.3 for iOS to PSPDFKit 9.4 for iOS. We encourage you to update as soon as possible, in order to take advantage of future new features and fixes.

PSPDFKit 9.4 for iOS drops support for iOS 11 in preparation for the upcoming iOS 14 release. It fully supports iOS 12 and 13. Xcode 11.5 or later is required to use this version of the SDK. Learn more in our version support guide.

Opt In to Trackpad and Mouse Support

PSPDFKit now has enhancements for trackpad and mouse input on iPad, including responding to secondary clicks. Some of this functionality requires UIApplicationSupportsIndirectInputEvents(opens in a new tab) to be enabled in your app’s Info.plist. You can read more in our trackpad and mouse support guide.

Public Podspec and Carthage JSON URLs

The use of the CocoaPods key in the Podspec and Carthage JSON URLs is no longer required. While the old URLs are still supported, we recommend you integrate PSPDFKit using CocoaPods or Carthage using the new public links.

New Podspec URL

The new Podspec URL is:

use_frameworks!
target :YourTargetName do
pod 'PSPDFKit',
podspec: 'https://my.pspdfkit.com/pspdfkit-ios/9.4.0.podspec'
end

New Carthage JSON URL

The new Carthage JSON URL is:

binary "https://my.pspdfkit.com/pspdfkit-ios.json" ~>'9.4.0'

XCFramework Support for CocoaPods

With PSPDFKit 9.4 for iOS, the CocoaPods integration switches to using XCFrameworks by default, allowing you to integrate PSPDFKit via CocoaPods in Mac Catalyst projects.

Note that XCFrameworks support in CocoaPods requires CocoaPods version 1.9.3 or later.

If your project environment requires you to use the old fat .framework files instead, you can append -framework to the version number of your CocoaPods URL, like so:

use_frameworks!
target :YourTargetName do
pod 'PSPDFKit',
podspec:
'https://my.pspdfkit.com/pspdfkit-ios/9.4.0-framework.podspec'
end

API Functionality Changes

  • The behavior of the isEditable property of PSPDFAnnotation was changed slightly. An annotation will no longer be editable if the isReadOnly property is true. Double-check your expectations are still being met if you use the isEditable property.

  • The Processor class methods generatePDF(from ...) now have a non-optional return type and call their completion handler with an error if the required feature is missing in the license. However, note that in general, APIs should not be called when a required license feature is missing. The optional change is a minor breaking change in Swift.

  • As part of adopting system contextual menus, the longPressGestureRecognizer properties on BackForwardButton, ToolbarGroupButton, and ToolbarDualButton are now only used by PSPDFKit on iOS 12, where system contextual menus are not available. These properties have been deprecated and will be removed in a future version of PSPDFKit.

  • The BackForwardActionListDelegate methods backForwardList(_:requestedBackActionExecution:) and backForwardList(_:requestedForwardActionExecution:), and the BackForwardActionList methods requestBack, requestBack(to:), requestForward, and requestForward(to:) were deprecated in favor of variants with an animated parameter. The variants without the animated parameter will be removed in a future version of PSPDFKit.

API Naming and Modernization

Swift

This release includes API refinements for Swift. In addition to the changes listed below, there are additional unlisted renames that Xcode can fix automatically using the Fix Next Issue or Fix All Issues commands.

  • The type of the pointSequences property on DrawView has changed from [[NSValue]] to [[DrawingPoint]]. This should save you some boxing and unboxing.

  • The type aliases PDFLine and ViewLine have been deprecated because their names were inaccurate. Use [DrawingPoint] and [CGPoint] instead.

  • PDFSigner.Error has been renamed to PDFSignerError. This is a breaking change with no deprecation, done in order to avoid ambiguity with the Swift.Error type.

  • The type of the options dictionary keys on the URLAction initializer have changed from String to Action.Option.

The options dictionary keys for PDFLibrary have changed from String to a new enum, PDFLibrary.Option:

Removed APIReplacement API
PSPDFLibraryMaximumSearchResultsTotalKey.maximumSearchResultsTotal
PSPDFLibraryMaximumSearchResultsPerDocumentKey.maximumSearchResultsPerDocument
PSPDFLibraryMaximumPreviewResultsTotalKey.previewResultsTotal
PSPDFLibraryMaximumPreviewResultsPerDocumentKey.maximumPreviewResultsPerDocument
PSPDFLibraryMatchExactWordsOnlyKey.matchExactWordsOnly
PSPDFLibraryMatchExactPhrasesOnlyKey.matchExactPhrasesOnly
PSPDFLibraryExcludeAnnotationsKey.excludeAnnotations
PSPDFLibraryExcludeDocumentTextKey.excludeDocumentText
PSPDFLibraryPreviewRangeKey.previewRange

The options dictionary keys for SpeechController have changed from String to a new enum, SpeechController.Option:

Removed APIReplacement API
PSPDFSpeechSynthesizerAutoDetectLanguage.autoDetectLanguage
PSPDFSpeechSynthesizerLanguageKey.language
PSPDFSpeechSynthesizerLanguageHintKey.languageHint

The options dictionary keys for Document (ObjectFinder) have changed from String to a new enum, Document.ObjectFinderOption:

Deprecated APIReplacement API
PSPDFObjectsGlyphsKey.extractGlyphs
PSPDFObjectsWordsKey.extractWords
PSPDFObjectsTextKey.extractText
PSPDFObjectsTextBlocksKey.extractTextBlocks
PSPDFObjectsImagesKey.extractImages
PSPDFObjectsAnnotationsKey.extractAnnotations
PSPDFObjectsIgnoreLargeTextBlocksKey.ignoreLargeTextBlocks
PSPDFObjectsAnnotationTypesKey.annotationTypes
PSPDFObjectsAnnotationPageBoundsKey.annotationPageBounds
PSPDFObjectsPageZoomLevelKey.pageZoomLevel
PSPDFObjectsAnnotationIncludedGroupedKey.annotationIncludedGrouped
PSPDFObjectsSmartSortKey.smartSort
PSPDFObjectMinDiameterKey.minDiameter
PSPDFObjectsTextFlowKey.textFlow
PSPDFObjectsFindFirstOnlyKey.findFirstOnly
PSPDFObjectsTestIntersectionKey.testIntersection
PSPDFObjectsTestIntersectionFractionKey.testIntersectionFraction

In addition to being used as keys for options, some of the PSPDFObjects dictionary keys were also used for returning objects. To reduce this ambiguity, we added a new enum, Document.ObjectFinderType:

Deprecated APIReplacement API
PSPDFObjectsGlyphsKey.glyphs
PSPDFObjectsWordsKey.words
PSPDFObjectsTextKey.text
PSPDFObjectsTextBlocksKey.textBlocks
PSPDFObjectsImagesKey.images
PSPDFObjectsAnnotationsKey.annotations

Objective-C

Some naming has been modernized in Objective-C. These changes are all deprecations rather than hard breaking changes. Deprecated APIs will be removed in a future release.

  • PSPDFInstantError has been renamed to PSPDFInstantErrorCode. The old name has been deprecated.

Names for the options dictionary keys for PSPDFLibrary have been modernized:

Deprecated APIReplacement API
PSPDFLibraryMaximumSearchResultsTotalKeyPSPDFLibraryOptionMaximumSearchResultsTotal
PSPDFLibraryMaximumSearchResultsPerDocumentKeyPSPDFLibraryOptionMaximumSearchResultsPerDocument
PSPDFLibraryMaximumPreviewResultsTotalKeyPSPDFLibraryOptionPreviewResultsTotal
PSPDFLibraryMaximumPreviewResultsPerDocumentKeyPSPDFLibraryOptionMaximumPreviewResultsPerDocument
PSPDFLibraryMatchExactWordsOnlyKeyPSPDFLibraryOptionMatchExactWordsOnly
PSPDFLibraryMatchExactPhrasesOnlyKeyPSPDFLibraryOptionMatchExactPhrasesOnly
PSPDFLibraryExcludeAnnotationsKeyPSPDFLibraryOptionExcludeAnnotations
PSPDFLibraryExcludeDocumentTextKeyPSPDFLibraryOptionExcludeDocumentText
PSPDFLibraryPreviewRangeKeyPSPDFLibraryOptionPreviewRange

Names for the options dictionary keys for PSPDFSpeechController have been modernized:

Deprecated APIReplacement API
PSPDFSpeechSynthesizerAutoDetectLanguagePSPDFSpeechControllerOptionAutoDetectLanguage
PSPDFSpeechSynthesizerLanguageKeyPSPDFSpeechControllerOptionLanguage
PSPDFSpeechSynthesizerLanguageHintKeyPSPDFSpeechControllerOptionLanguageHint

Names for the options dictionary keys for PSPDFDocument (ObjectFinder) have been modernized:

Deprecated APIReplacement API
PSPDFObjectsGlyphsKeyPSPDFObjectFinderOptionExtractGlyphs
PSPDFObjectsWordsKeyPSPDFObjectFinderOptionExtractWords
PSPDFObjectsTextKeyPSPDFObjectFinderOptionExtractText
PSPDFObjectsTextBlocksKeyPSPDFObjectFinderOptionExtractTextBlocks
PSPDFObjectsImagesKeyPSPDFObjectFinderOptionExtractImages
PSPDFObjectsAnnotationsKeyPSPDFObjectFinderOptionExtractAnnotations
PSPDFObjectsIgnoreLargeTextBlocksKeyPSPDFObjectFinderOptionIgnoreLargeTextBlocks
PSPDFObjectsAnnotationTypesKeyPSPDFObjectFinderOptionAnnotationTypes
PSPDFObjectsAnnotationPageBoundsKeyPSPDFObjectFinderOptionAnnotationPageBounds
PSPDFObjectsPageZoomLevelKeyPSPDFObjectFinderOptionPageZoomLevel
PSPDFObjectsAnnotationIncludedGroupedKeyPSPDFObjectFinderOptionAnnotationIncludedGrouped
PSPDFObjectsSmartSortKeyPSPDFObjectFinderOptionSmartSort
PSPDFObjectMinDiameterKeyPSPDFObjectFinderOptionMinDiameter
PSPDFObjectsTextFlowKeyPSPDFObjectFinderOptionTextFlow
PSPDFObjectsFindFirstOnlyKeyPSPDFObjectFinderOptionFindFirstOnly
PSPDFObjectsTestIntersectionKeyPSPDFObjectFinderOptionTestIntersection
PSPDFObjectsTestIntersectionFractionKeyPSPDFObjectFinderOptionTestIntersectionFraction

In addition to being used as keys for options, some of the PSPDFObjects dictionary keys were also used for returning objects. To reduce this ambiguity, we added several new dictionary keys:

Deprecated APIReplacement API
PSPDFObjectsGlyphsKeyPSPDFObjectFinderTypeGlyphs
PSPDFObjectsWordsKeyPSPDFObjectFinderTypeWords
PSPDFObjectsTextKeyPSPDFObjectFinderTypeText
PSPDFObjectsTextBlocksKeyPSPDFObjectFinderTypeTextBlocks
PSPDFObjectsImagesKeyPSPDFObjectFinderTypeImages
PSPDFObjectsAnnotationsKeyPSPDFObjectFinderTypeAnnotations

Removal of Incorrect APIs

The following API has been removed because it did not work correctly:

  • The PDFPage class has been removed because it was not possible to create or obtain PDFPage objects via public APIs. This also means the LinkAnnotationEditingContainerViewController.init(page:, selectedRects:) initializer has been replaced with LinkAnnotationEditingContainerViewController.init(document:, pageIndex:, selectedRects:).

  • One of the two Swift free functions named BoundingBoxFromLines has been removed. The other one can still be used.