Customize the Tools framework

In this document

There are two ways to customize how the tools work, by using APIs, or by modifying the source code directly.

When possible, we recommend making customizations via the API as it will make updating to the latest version of the tools framework simpler (no code merging needed).

Customize via the API

The tools expose an API which makes adding or overriding PDF interaction behaviour easy. This is done by implementing the ToolManagerDelegate protocol.

There are three methods that allow you to be notified of, and if desired modify or prevent, default behaviour from occuring. For all three methods, if false is returned, then the default behaviour will not occur.

  1. -toolManager:shouldSelectAnnotation:onPageNumber:

    This method is called just before an annotation is selected. The annotation object itself is available for the decision making process, and for further action if needed.

  2. -toolManager:shouldShowMenu:forAnnotation:onPageNumber:

    This method is called just before the selection popup menu is shown. The UIMenuController object is passed so that menu items can be added or removed as required.

  3. -toolManager:shouldHandleLinkAnnotation:orLinkInfo:onPageNumber:

    This method is called just before a link is followed. The link is provided so that alternate action can be taken if required.


The sample code uses -toolManager:shouldShowMenu:forAnnotation:onPageNumber: to restrict use of the UIMenuController to copying and defining text found in the PDF. This is done by stopping the UIMenuController from popping up in any case other than selecting text, and by removing options to highlight/underline etc. from the selected text UIMenuController popup.

We are always interested in expanding the customization options via the API, and will be adding more options in the future. If you would like to suggest changes, please don't hesitate to get in touch.

Customize by modifying the source code

Because Tools.framework is open source, any and all changes are possible by editing the source code directly. The project is found in /Lib/Tools/src.

If you customize the tools source code, you will likely want to use a universal framework (one that contains architectures for both simulators and devices), which is not done automatically by Xcode. The Tools project includes a custom script step that automatically creates a universal framework, located in a folder next to the default build location, with the name {Debug,Release}-universal.

(Building a universal framework also be done manually byfirst building for device, then simulator, and using the terminal command xcrun -sdk iphoneos lipo -create to merge the binaries (Tools.framework/Tools) into a universal binary.)