PSPDFKit 5 Migration Guide

PSPDFKit 5 for iOS is the largest framework update so far.

New Renderer Core

While developing PSPDFKit for Android, which we released in early 2015, we started working on a new “core” shared C++ library that is now used in PSPDFKit for iOS. This was a long process that started in early 2014. Android didn’t have a capable PDF renderer: Google added a few calls in the KitKat 4.4 update, but they’re far too limited and only meant for printing. And we’re striving for compatibility with Ice Cream Sandwich 4.0, so we had to include our own renderer.

Once we built and released it, we noticed that, in many cases, our renderer performed better than Apple’s Core Graphics PDF renderer that was used on iOS. And at the same time, having full control over the whole stack would allow us to ship features that were previously unthinkable (like eager loading of linearized PDF, layers, and more — stay tuned for what we have in the pipeline).

Using a shared core also means even better test coverage. Of course, our main goal is always to design a beautiful, simple-to-use API, so the core is entirely internal and you’ll still get your native Objective-C APIs.

iOS and Xcode Requirements

With PSPDFKit 5 for iOS, we finally dropped support for iOS 7. At the time this post was written, less than 9 percent of all devices run either iOS 7 or an earlier version, and we follow our usual pattern of supporting n-1 major iOS versions. This currently spans across iOS 8.0, 8.1, 8.2, 8.3, 8.4, 9.0, and 9.1. This build also requires the just-released Xcode 7.1. Xcode 7.1 runs on 10.10 or 10.11, and we recommend El Capitan 10.11.1 or higher.

If you need support for iOS 7, we just updated the PSPDFKit 4 branch with more iOS 9-related fixes, and you’re free to continue using this version until you can drop the old OS requirements. Note that PSPDFKit 4 works best with Xcode 6.4, not Xcode 7.

Dynamic Framework

Along with dropping iOS 7, we simplified our setup and now exclusively ship with a dynamic SDK. This means you probably need to update your integration, and we made a handy guide to show you how.

CocoaPods now finally (!) has support for binary dynamic frameworks with the just-released 0.39.0 version, so after a gem update and adding a use_frameworks! directive, that will work great as well.

API Modernization

All APIs are now annotated for nullability and generics, so they work nicely with Swift 2.0.

We’ve modernized our APIs slightly to reflect new features and changed requirements:

  • The pageRange property didn’t make it into 5.0, but if there’s a lot of demand, we might bring it back.

  • PSPDFProcessor looks similar, but it now has more consistent calls with completion blocks and can be called on any thread.

  • Separating and merging documents is now done without Apple’s renderer and works faster and more reliably, thereby fixing erratic issues with larger files or missing content that we reported to Apple over the years, but which have almost never been fixed. We now own the full parsing and rendering stack and can deliver fixes ourselves.

  • We’ve converted many accessor methods to read-only properties, following Apple’s guidelines, and because property syntax often gives you better compile time checks.

  • We took the chance and renamed PSPDFScrobbleBar to PSPDFScrubberBar to make it more obvious for new people coming to the framework.

  • Instead of Boolean settings, we added PSPDFAdaptiveConditional, which better works in adaptive environments without requiring you to manually update the configuration object on such changes. This is currently only used for documentLabelEnabled.

  • The PDFBox property on PSPDFDocument was exposed in earlier versions. However, it’s extremely unlikely that you really need it, and the logic for choosing the correct box is actually a bit more complex than that. We now fully comply to what the PDF spec and Adobe Acrobat do by default and no longer expose this detail.

  • We’ve optimized the way text blocks are detected, which should result in an even more reliable zoom-to-fit experience. While doing this, a lot of our core was rewritten and we no longer expose PSPDFFontInfo.

  • The new parser now detects more cases of images, and PSPDFImageInfo works more reliably in extracting image data from the PDF when required.

Data Providers

PSPDFAESCryptoDataProvider now has a passphraseProvider, since we can run into situations where we require the passphrase again, and calling a block allows you to securely store it in the keychain instead of us having to keep it in memory. We also — finally — allow writing annotations back into encrypted files. Note that this isn’t the same as writing into PDF password-protected files, something which is on the roadmap and will come early next year.

Since we no longer use Apple’s renderer, there’s no need to pack things into a CGDataProvider, and we ship our own PSPDFDataProvider with a more convenient API and optional support to request a PSPDFDataSink for writing files.

Full-Text Indexing Library

Our indexed FTS library can now deal with CJK characters (Chinese, Japanese, and Korean languages). Find out more in our PSPDFKit 5 for iOS blog.

UIKit Modernization and Adaptivity

Dropping iOS 7 allowed us to fully switch over from the deprecated UIPopoverController to the new UIPresentationController APIs, which made the entire popover and adaptivity logic much more streamlined. We also updated our UI to be fully adaptive. (See the blog post announcement for images.) This means we ditched properties like isInPopover, since this can be found from the current presentation style without us adding extra APIs.

This means that any API that gave or took a UIPopoverController has been changed, and popovers can now be dismissed the same way as modal views. This includes our half modal view controller, which is now handled by a custom presentation controller as well.

We haven’t stopped there: The annotation and text toolbars are now adaptive as well, and we updated the configuration options to allow setting “sets” of configurations. PSPDFKit will select the set that fits best in the space available. See the documentation around the new PSPDFAnnotationToolbarConfiguration object for details.

UIKit API modernization also implies that we no longer use deprecated methods from iOS 7. Your view controller overrides should no longer override willRotateToInterfaceOrientation:duration:, willAnimateRotationToInterfaceOrientation:duration:, or didRotateFromInterfaceOrientation:, since these might cause conflicts with the more modern and flexible viewWillTransitionToSize:withTransitionCoordinator:.

Tabs

There have been many changes to the tabbed UI, which now properly animates and feels and looks much, much better. Use properties on PSPDFTabbedViewController to customize the behavior, and use its tabbedBar (an instance of PSPDFTabbedBar) to customize the appearance. There are new related APIs, such as PSPDFMultiDocumentListController, which shows all open documents when the tabbed bar is overflowing.

What’s Next

We’re still working on updating our bindings for Xamarin, Appcelerator Titanium, and Cordova, and we’ll ship compatible updates of these in the coming weeks. Our stylus drivers will receive updates as well, and we can’t wait to get our hands on iPad Pro and add support for the Apple Pencil. With our new renderer core, features such as PDF layers and displaying linearized PDFs on the fly are finally reachable, so stay tuned to see what 2016 will bring…