6.7 to 6.8 Tools framework migration

6.8 introduces a number of improvements in the Tools.framework. The nature of these improvements are such that both PDFNet.framework and Tools.framework must be updated simultaneously. Additionally, some minor code changes in your app may be required.

Sections 1 and 2 apply if your app implements any of the delegate methods listed in the first table, with section 2 applying only if you are using Swift.

Section 3 applies if you have customized the tools source code. As always, we recommend using a diff tool (such as FileMerge) to merge your customizations into the new version.

If you have any questions or comments, please do not hesitate to contact support.

In order to reduce coupling and better communicate the relationships between objects, the tools protocols have been renamed and reorganized, as explained below. If you are using a customized version of the tools framework, it will need to be updated to reflect these changes, explained below.

Previously, the protocols used by Tools.framework were declared in PDFNet.framework's PTPDFViewCtrl.h. In 6.8, PDFNet.framework only declares a single tool-related protocol, PTTool, which has been simplified to include only events emitted PTPDFViewCtrl, with all other methods moved into PTToolSwitching. The other protocols that were previously declared in PTPDFViewCtrl.h have been moved into Tools.framework.

Additionally, all protocol methods have been updated to include the sending object as the first parameter when this was not already the case.

Table of protocol reorganization:

Please see the tools protocols guide for a description of each of the protocols in 6.8.

The Tools.framework in 6.8 is now annotated with nullability annotations for use from Swift. Parameter and return types explicitly indicate whether the value is permitted to be nil.

Previously, parameter and return types from Tools were imported by Swift as implicitly unwrapped optionals. Implicitly unwrapped optionals are safe to use when the value is non-null but can trigger a runtime error if accessed with a value of nil.

For the majority of methods in the 6.8 version of Tools.framework the parameters and return types are non-null. Updating your project to use the new method signatures involves replacing implicitly unwrapped optionals with optionals or non-optional types. No change is required for Objective-C code.

For 6.7 and before, an implementation of the AnnotationToolbarDelegate protocol in a view controller may have been:

extension ViewController : AnnotationToolbarDelegate {

  // Implicitly unwrapped optional method parameter.
  func annotationToolbarDidCancel(_ annotationToolbar: AnnotationToolbar!) {
    if annotationToolbar != nil {
      // annotationToolbar contains a value.
    }

    let tool: PanTool! = PanTool(pdfViewCtrl: self.pdfViewCtrl)
    if tool != nil {
      // tool contains a value.
    }
  }

}

With 6.8 the code can be simplified:

extension ViewController : AnnotationToolbarDelegate {

  // Non-optional method parameter.
  func annotationToolbarDidCancel(_ annotationToolbar: AnnotationToolbar) {
    // annotationToolbar contains a value.

    let tool = PanTool(pdfViewCtrl: self.pdfViewCtrl)
    // tool contains a value.
  }

}

Updating to the 6.8 version of Tools.framework yields shorter and safer Swift code.

Nullability and Optionals

In 6.7 and earlier, the tools made use of many ivars. In 6.8 these ivars have, where appropriate, been turned into properties. For example 6.7's m_pdfViewCtrl is now self.pdfViewCtrl in 6.8.

In 6.7 and earlier, tools attached views to the PTPDFViewCtrl ivar ContainerView, e.g.:

[m_pdfViewCtrl->ContainerView addSubview:selectionRectContainerView];```

In 6.8, `PTPDViewCtrl` has a new overlay view property, `toolOverlayView`, which should now be used instead, e.g.:

[self.pdfViewCtrl.toolOverlayView addSubview:self.selectionRectContainerView];```