> For the complete documentation index, see [llms.txt](https://docs.apryse.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apryse.com/ios/guides/changelog/resource/6-7-to-6-8-tools-framework-migration.md).

# 6.7 to 6.8 Tools framework migration

Discover the latest improvements in Tools.framework with version 6.8. Learn about protocol changes, Swift support, and how to update your app for optimal performance. Contact support for any questions

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.

## 1. Tools.framework protocol changes

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:

| 6.7 Name                   | 6.7 Location    | 6.8 Name              | 6.8 Location    |
| -------------------------- | --------------- | --------------------- | --------------- |
| `PTToolCommon`             | `PDFViewCtrl.h` | `PTTool`              | `PDFViewCtrl.h` |
| `PTTool`                   | `PDFViewCtrl.h` | `PTToolSwitching`     | `ToolManager.h` |
| `PTPDFViewCtrlToolManager` | `PDFViewCtrl.h` | `PTToolManager`       | `ToolManager.h` |
| `ToolManagerDelegate`      | `ToolManager.h` | `ToolManagerDelegate` | `ToolManager.h` |

Please see the [tools protocols guide](/ios/ui-customization/tools-protocols.md) for a description of each of the protocols in 6.8.

## 2. Swift support in Tools.framework

The `Tools.framework` in 6.8 is now annotated with [nullability annotations](https://developer.apple.com/swift/blog/?id=25) 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](https://developer.apple.com/library/content/Swift/Conceptual/Swift_Programming_Language/TheBasics.html#//apple_ref/doc/uid/TP40014097-CH5-ID334). 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.

### Example

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

{% tabs %}
{% tab title="Shell" %}
{% code lineNumbers="true" %}

```sh
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.
    }
  }

}
```

{% endcode %}
{% endtab %}
{% endtabs %}

With 6.8 the code can be simplified:

{% tabs %}
{% tab title="Shell" %}
{% code lineNumbers="true" %}

```sh
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.
  }

}
```

{% endcode %}
{% endtab %}
{% endtabs %}

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

### Resources

[Nullability and Optionals](https://developer.apple.com/library/content/Swift/Conceptual/BuildingCocoaApps/InteractingWithObjective-CAPIs.html#//apple_ref/doc/uid/TP40014216-CH4-ID45)

## 3. Tools.framework properties and view attachment

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.:

{% tabs %}
{% tab title="Shell" %}
{% code lineNumbers="true" %}

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

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

{% endcode %}
{% endtab %}
{% endtabs %}

{% endtab %} {% endtabs %}

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.apryse.com/ios/guides/changelog/resource/6-7-to-6-8-tools-framework-migration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.