PSPDFKit 9.3 Migration Guide

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

PSPDFKit 9.3 for iOS fully supports iOS 11, 12, and 13. iOS 11 support will be removed later during the PSPDFKit 9 lifecycle. Xcode 11.4 or later is required to use this version of the SDK. Learn more in our version support guide.

Document Permissions

A PDF document defines a set of permissions that enable/disable certain actions a user can take with the document. These permissions cover things like printing, annotation modification, and content extraction.

Prior to this release, we could read and write user permissions on a PDF document, but most of them were ignored by the SDK. PSPDFKit 9.3 for iOS adds comprehensive support for all available document permissions so that the relevant UI actions are enabled/disabled based on which permissions are available.

The permissions are defined using the DocumentPermissions API (PSPDFDocumentPermissions in Objective-C). Here’s a brief list of the effects each permission has when disabled:

• .printing — The UIActivityTypePrint activity will be removed from the available sharing activities when using the DocumentSharingConfiguration.Destination.activity sharing destination, and the DocumentSharingConfiguration.Destination.print sharing destination will not be available.

• .extract — The user will not be able to copy selected text or images.

• .assemble — The user will not be able to enter the Document Editor view mode.

• .annotationsAndForms — The user will not be able to create new annotations; move, resize, or rotate existing annotations; or add comments to existing annotations.

• .fillForms — If disabled along with .annotationsAndForms, the user will not be able to fill in form fields, including signature fields, checkboxes, and radio buttons.

• .modification — The user will not be able to add or edit bookmarks, redact portions of a document, or edit information like a document’s title and author information.

Make sure to read the document permissions guide to learn more about this, including how to disable this behavior.

Objective-C Changes

If you’re using the PSPDFKit SDK with Swift, jump to the Swift-Only Changes section.

• Changed

  Presentation option constants for the PSPDFPresentationActions protocol have been deprecated in favor of renamed constants with the PSPDFPresentationOption prefix. This is for consistency and improved Swift interoperability.

• Changed

  Similarly, the existing constants used to access the contents of the dictionary objects of PSPDFGalleryItem have been deprecated in favor of a new type, PSPDFGalleryItemProperty.

• Changed

  The following cases from the PSPDFFlexibleToolbarPosition enum have been deprecated and replaced.

• Changed

  The existing PSPDFSettingKey constants have been deprecated in favor of the new ones, which are more semantically named.

• Changed

  The existing PSPDFAnnotationOption constants have been deprecated in favor of the new ones, which are semantically named for improved Swift interoperability.

• Changed

  The PSPDFRectAlignment API cases have been renamed to provide better interoperability in Swift.

• Changed

  The fields property of PSPDFAbstractFormAnnotation is now typed NSArray<id<PSPDFFormFieldIdentifier>> *, in order to more clearly document what this property contains. The newly introduced PSPDFFormFieldIdentifier protocol is a trait added to NSString and NSNumber.

• Changed

  -[PSPDFFreeTextAnnotation convertToIntentType:] has been deprecated. Use -[PSPDFFreeTextAnnotation convertIntentTypeTo:] instead.

• Changed

  -[PSPDFSoundAnnotation initWithRecorder] has been deprecated. Use -[PSPDFSoundAnnotation initWithRecorderOptions:] with a nil parameter for options instead.

Swift-Only Changes

If you’re using the PSPDFKit SDK with Objective-C, check out the Objective-C Changes section.

The entire SDK has been carefully tweaked to make the entirety of our API semantic in Swift. We dropped the PSPDF prefix and tried to group related APIs by nesting them where appropriate and possible. Due to the vastness of the changes, and in order to keep the migration guide concise, we’ve only mentioned the API changes that could break your build and which cannot be fixed using Xcode’s suggestion (the Fix button).

Most of the API changes can be reliably fixed using the Fix All Issues option (Control-Option-Command-F) in Xcode. This fixes all the issues in the currently opened file. Some of the files may require multiple iterations of using Xcode’s fix option, as some the errors will only be caught after the initially shown errors are fixed.

• Changed

  The String constants used in the PSPDFPresentationActions protocol have been removed in favor of the new Swift struct type, PresentationOption. All the places where the old constants are used as arguments will throw an error while compiling since the type of the method arguments has also been changed from String to the appropriate new struct type.

• Changed

  The constants used for accessing the dictionary values of a PSPDFGalleryItem have been replaced with the GalleryItem.Property struct.

If any of these types happen to clash with other declarations in Swift, this can be resolved by accessing the type using the module name. For example, use PSPDFKitUI.GalleryItem.Option.autoPlay instead of GalleryItem.Option.autoPlay.

• Changed

  The PSPDFAnnotationOption type has been renamed to AnnotationManager.ChangeBehaviorKey in Swift. Its existing values have been deprecated in favor of semantically named ones.

• Changed

  The PSPDFRectAlignment enumeration has been renamed to RectAlignment for Swift. Its cases have also been renamed.

• Changed

  PSPDFFlexibleToolbarPosition has been updated with a new Swift name, FlexibleToolbar.Position. Some position values have been deprecated and replaced with new ones to ensure better translation to Swift names.

• Changed

  PSPDFSettingKey has been renamed to SDK.Setting, and the existing constants have been deprecated in favor of new ones, which are more semantically named.

• Changed

  PSPDFMetadataName has been renamed to PDFMetadata.Key, and the existing constants have been deprecated in favor of new ones, which are more semantically named.

• Changed

  PSPDFValueTransformerName has been renamed to ValueTransformerName, and the existing constants have been replaced. See below for the list.

• Changed

  PSPDFDocumentUnderlyingFileChangedNotificationOptions has been renamed to Document.UnderlyingFileChangedNotificationOption, and the existing constants have been replaced. See below for the list.

Annotation API Refinements

• Changed

  AnnotationStyleType has been renamed to AnnotationStyle.Kind.

• Changed

  AnnotationStyleKey has been renamed to AnnotationStyle.Key.

• Changed

  AnnotationString has been renamed to Annotation.Tool.

• Changed

  AnnotationVariantString has been renamed to Annotation.Variant.

• Changed

  AnnotationStateVariantID has been renamed to Annotation.ToolVariantID.

• Removed

  The PSPDFStringFromAnnotationType() helper for creating Annotation.Tool from Annotation.Kind has been removed. Use the init?(kind:) initializer on Annotation.Tool instead.

• Removed

  The PSPDFAnnotationTypeFromString() helper for creating Annotation.Kind from Annotation.Tool has been removed. Use the init(tool:) initializer on Annotation.Kind instead.

• Removed

  The PSPDFAnnotationStateVariantIDMake() helper for generating Annotation.ToolVariantID has been removed. Use Annotation.ToolVariantID(tool:, variant:) instead.

• Removed

  The PSPDFAnnotationStateFromStateVariantIdentifier() helper for extracting Annotation.Tool has been removed. Use the tool property on Annotation.ToolVariantID instead.

• Removed

  The PSPDFAnnotationVariantFromStateVariantIdentifier() helper for extracting Annotation.Variant has been removed. Use the variant property on Annotation.ToolVariantID instead.

• Changed

  The type of the Annotation.additionalActions property has been changed to [Annotation.TriggerEvent: Action].

• Changed

  The type of the Annotation.dashArray property has been changed to [CGFloat].

• Changed

  The type of the Annotation.rects property has been changed to [CGRect].

• Changed

  The type of the Annotation.points property has been changed to [CGPoint].

• Changed

  The AbstractFormAnnotation.fields property has been renamed to fieldIdentifiers to more clearly document what this array contains. Its type has been changed from [Any]? to [FormFieldIdentifier]?, where the nested enum FormFieldIdentifier further documents the semantics. For coding convenience, the enum is both ExpressibleByIntegerLiteral and ExpressibleByStringLiteral.

• Added

  A new type, PDFLine, which is a type alias for an array of DrawingPoint ([DrawingPoint]), has been added.

• Added

  A new type, ViewLine, which is a type alias for an array of CGPoint ([CGPoint]), has been added.

• Removed

  InkAnnotation(lines: [[NSValue]]) has been removed. Use InkAnnotation(lines: [PDFLine]) instead.

• Changed

  The type of the InkAnnotation.lines property has been updated from [[NSValue]] to [PDFLine]).

• Changed

  The type of the points parameter in initializers of AbstractLineAnnotation (formerly PSPDFAbstractLineAnnotation) and PolygonAnnotation has been updated to an array of CGPoint instead of an array of NSValue. Updated APIs: AbstractLineAnnotation(points: [CGPoint]), PolygonAnnotation(points: [CGPoint], intentType: PolygonAnnotation.Intent = .none)

• Removed

  FreeTextAnnotation.convert(toIntentType:) has been deprecated. Use FreeTextAnnotation.convertIntent(to:) instead.

• Changed

  The rects parameter to TextMarkupAnnotation’s class method — textOverlayAnnotation(withRects:,boundingBox:,pageIndex:) — has been changed from [NSValue] to [CGRect]. The signature of this method is now class func textOverlayAnnotation(withRects rects: [CGRect], boundingBox: CGRect, pageIndex: Int) -> Self?.

• Changed

  The PSPDFAnnotationAuthorState and PSPDFAnnotationAuthorStateModel APIs have been consolidated into the Annotation.State API, which is an enum with associated values. Below is the list of the possible values for the Annotation.State type.

The change above affects the NoteAnnotation API. Since the two types have been reorganized into a single type (Annotation.State), NoteAnnotation uses a single property (authorState) to show the author-specific state. This means that the other property, authorStateModel, has been removed.

• Changed

  SoundAnnotation(recorderOptions:) has been updated to take a parameter of type Set<SoundAnnotation.RecorderOption> instead of a dictionary. SoundAnnotation.RecorderOption is an enum with associated values that can be used to configure a recorder.

• Removed

  The SoundAnnotation.initWithRecorder() API has been removed. Use SoundAnnotation(recorderOptions:) by passing an empty set as the recorderOptions: parameter instead.

Document API Refinements

• Removed

  The save(options: [PSPDFDocumentSaveOption : Any]) throws API on Document (formerly PSPDFDocument) has been removed. Use the save(options: Set<SaveOption>) throws API instead.

• Removed

  The save(options: [PSPDFDocumentSaveOption : Any]?, completionHandler: ((Error?, [PSPDFAnnotation]) -> Void)?) API of Document has also been removed. Use save(options: Set<SaveOption> = [], completion: @escaping (Result<[Annotation], Error>) -> Void) instead.

Note Annotation Icon

• Changed

  The icon used for representing the note annotation tool in the annotation toolbar has been replaced. You can read more about how to customize the icon in our customizing the annotation toolbar guide.

Old	New

Flexible Toolbar Position

• Changed

  The default value for FlexibleToolbarPosition’s supportedToolbarPositions property has changed from .all to .default. If you were programmatically setting your toolbar’s supportedToolbarPositions to .all, use .default instead to support the default toolbar positions. For more details on how to customize the toolbar positions, take a look at both our customizing the annotation toolbar guide and ToolbarPositionTopExample.swift from the Catalog app.

Class Overriding

The class overriding mechanism is now more type-safe and better documented. All classes that can be overridden now conform to the Overridable protocol. Classes that don’t conform to it are no longer accepted by overrideClass(_:with:) and can no longer participate in the mechanism.

If you were overriding an illicit class, you might now see compile warnings or errors. If you were implementing the Overridable protocol in your own classes, remove the conformance. It will no longer work with the class overriding mechanism.