PSPDFKit 11.4 Migration Guide

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

PSPDFKit 11.4 for iOS drops support for iOS 13 in preparation for the expected announcement of iOS 16, which means you must ensure your app’s deployment target is at least iOS 14. All devices that support iOS 13 also support iOS 14 and iOS 15. This version fully supports iOS 14 and 15. Xcode 13 or later is required to use this version of PSPDFKit. Learn more in our version support guide.

Removed Deprecated APIs

This version of PSPDFKit removes APIs that have been deprecated for more than a year. This includes deprecations from PSPDFKit 9.1 to PSPDFKit 10.4 for iOS. Here’s a list of all the APIs that have been removed in this release:

Other Breaking Changes

This release changes the superclass of ThumbnailFilterSegmentedControl from SegmentedControl to UISegmentedControl, since SegmentedControl was deprecated and is now removed.

MutableRenderRequest.document has been changed to a read-only property. If you need to request renders for many different documents, create a new request for each document instead.

This release also changes the type of ImageDocument.supportedContentTypes and OfficeDocument.supportedContentTypes from an array of String to an array of UTType, which has been the preferred way to describe type information of data since iOS 14. If you require a string representation of a supported content type, you can use the identifier property of UTType.

The LogLevelMask option set changed to a LogLevel enum. Refer to the logging guide for more details.

This release also removes some APIs that were implementation details and unintentionally ended up in our public API. This includes the removal of the following symbols, and if applicable, migration strategies in case you used any:

Changes to DrawView’s Undo Recording

When presented within PSPDFKit, the DrawView(opens in a new tab) API handles persisting changes to a document and recording the undo/redo commands of the annotations it’s displaying. However, if you’re using the DrawView(opens in a new tab) API outside of PSPDFKit, you’ll have to persist the changes to the document and record the undo/redo commands for the annotations yourself. This can be done by conforming to the new DrawViewDelegate(opens in a new tab) protocol and setting that instance as the DrawView.delegate(opens in a new tab).

The modification and deletion of annotations can involve multiple user interactions, and each user interaction has to be recorded as a separate undo command. For example, a user erasing parts of multiple ink annotations in a single gesture is a single interaction, hence these modifications of multiple ink annotations should be recorded as a single undo command. However, if a user is erasing different parts of an ink annotation in two interactions, it should be recorded as a separate undo command. Likewise, adding multiple strokes to an ink annotation demands recording separate undo commands for each drawing stroke. To support all these interactions, you need to use a DetachedUndoRecorder(opens in a new tab), which facilitates recording undoable actions over time until they’re manually committed.

Your DrawViewDelegate(opens in a new tab) implementation will require an optional property of type DetachedUndoRecorder(opens in a new tab), which you can use to record the modification and deletion of annotations. The addition and deletion of annotations can be recorded directly to the document.

Below is an example snippet of code for illustrating the recording of undo commands for a DrawView presented outside of PSPDFKit:

/// Document to which the annotations displayed in the `DrawView` belong.
let document: Document = ... // The document to which the undo actions should be recorded to.

/// Detached undo recorder for recording the modification and erasing of annotations.
var pendingUndoRecorder: DetachedUndoRecorder?

func drawView(_ drawView: DrawView, didBeginDrawingIn inputMode: DrawView.InputMode) {
    if inputMode == .erase {
        // Begin recording erasing of annotations.
        pendingUndoRecorder = document.undoController.beginRecordingCommand(named: "Erase")
    }
}

func drawView(_ drawView: DrawView, didEndDrawingIn inputMode: DrawView.InputMode, finished didFinish: Bool) {
    if inputMode == .erase {
        if didFinish {
            // Commit the changes only if the stroke was carried out successfully.
            pendingUndoRecorder?.commit()
        }
        pendingUndoRecorder = nil
    }
}

func drawView(_ drawView: DrawView, wantsToAdd annotation: Annotation) {
    // Add the annotation to the document recording its undo command.
    document.undoController.recordCommand(named: "Add", adding: [annotation]) {
        document.add(annotations: [annotation])
    }
}

func drawView(_ drawView: DrawView, wantsToDelete annotation: Annotation) {
    // Remove the annotation from the document with an undo command.
    pendingUndoRecorder?.record(removing: [annotation], in: {
        document.remove(annotations: [annotation])
    })
}

func drawView(_ drawView: DrawView, wantsToModifyAnnotation annotation: Annotation, inScope scope: @escaping () -> Void) {
    if drawView.inputMode == .erase {
        // Use the detached pending recorder to record the undo command for erasing an annotation.
        pendingUndoRecorder?.record(changing: [annotation], in: scope)
    } else {
        // We're appending to an annotation, so this can be recorded manually.
        document.undoController.recordCommand(named: "Draw", changing: [annotation], in: scope)
    }
}