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 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 API Replacement 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 API Replacement 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 API Replacement 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 API Replacement 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 API Replacement API
PSPDFLibraryMaximumSearchResultsTotalKey PSPDFLibraryOptionMaximumSearchResultsTotal
PSPDFLibraryMaximumSearchResultsPerDocumentKey PSPDFLibraryOptionMaximumSearchResultsPerDocument
PSPDFLibraryMaximumPreviewResultsTotalKey PSPDFLibraryOptionPreviewResultsTotal
PSPDFLibraryMaximumPreviewResultsPerDocumentKey PSPDFLibraryOptionMaximumPreviewResultsPerDocument
PSPDFLibraryMatchExactWordsOnlyKey PSPDFLibraryOptionMatchExactWordsOnly
PSPDFLibraryMatchExactPhrasesOnlyKey PSPDFLibraryOptionMatchExactPhrasesOnly
PSPDFLibraryExcludeAnnotationsKey PSPDFLibraryOptionExcludeAnnotations
PSPDFLibraryExcludeDocumentTextKey PSPDFLibraryOptionExcludeDocumentText
PSPDFLibraryPreviewRangeKey PSPDFLibraryOptionPreviewRange

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

Deprecated API Replacement API
PSPDFSpeechSynthesizerAutoDetectLanguage PSPDFSpeechControllerOptionAutoDetectLanguage
PSPDFSpeechSynthesizerLanguageKey PSPDFSpeechControllerOptionLanguage
PSPDFSpeechSynthesizerLanguageHintKey PSPDFSpeechControllerOptionLanguageHint

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

Deprecated API Replacement API
PSPDFObjectsGlyphsKey PSPDFObjectFinderOptionExtractGlyphs
PSPDFObjectsWordsKey PSPDFObjectFinderOptionExtractWords
PSPDFObjectsTextKey PSPDFObjectFinderOptionExtractText
PSPDFObjectsTextBlocksKey PSPDFObjectFinderOptionExtractTextBlocks
PSPDFObjectsImagesKey PSPDFObjectFinderOptionExtractImages
PSPDFObjectsAnnotationsKey PSPDFObjectFinderOptionExtractAnnotations
PSPDFObjectsIgnoreLargeTextBlocksKey PSPDFObjectFinderOptionIgnoreLargeTextBlocks
PSPDFObjectsAnnotationTypesKey PSPDFObjectFinderOptionAnnotationTypes
PSPDFObjectsAnnotationPageBoundsKey PSPDFObjectFinderOptionAnnotationPageBounds
PSPDFObjectsPageZoomLevelKey PSPDFObjectFinderOptionPageZoomLevel
PSPDFObjectsAnnotationIncludedGroupedKey PSPDFObjectFinderOptionAnnotationIncludedGrouped
PSPDFObjectsSmartSortKey PSPDFObjectFinderOptionSmartSort
PSPDFObjectMinDiameterKey PSPDFObjectFinderOptionMinDiameter
PSPDFObjectsTextFlowKey PSPDFObjectFinderOptionTextFlow
PSPDFObjectsFindFirstOnlyKey PSPDFObjectFinderOptionFindFirstOnly
PSPDFObjectsTestIntersectionKey PSPDFObjectFinderOptionTestIntersection
PSPDFObjectsTestIntersectionFractionKey PSPDFObjectFinderOptionTestIntersectionFraction

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 API Replacement API
PSPDFObjectsGlyphsKey PSPDFObjectFinderTypeGlyphs
PSPDFObjectsWordsKey PSPDFObjectFinderTypeWords
PSPDFObjectsTextKey PSPDFObjectFinderTypeText
PSPDFObjectsTextBlocksKey PSPDFObjectFinderTypeTextBlocks
PSPDFObjectsImagesKey PSPDFObjectFinderTypeImages
PSPDFObjectsAnnotationsKey PSPDFObjectFinderTypeAnnotations

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.