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:

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

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

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:

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:

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

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

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:

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.