Tools protocols

This document explains the tools hierarchy in Apryse versions 6.8 and greater.

##Protocols

Events that occur on the PTPDFViewCtrl, such as touches began, moved, ended; tapped, long press; scrolled, etc. These are used to implement user interactive behaviour on the PDF.

Adds properties and methods to PTPDFViewCtrlToolDelegate for initializing a tool, switching to a new tool, and accessing the tool’s state. The events declared by PTPDFViewCtrlToolDelegate are general, whereas those declared by PTToolSwitching are used by the stock implementation of the tools, and the tool manager.

Declares an interface that individual tools (PTPanTool, PTAnnotEditTool, etc.) use to report on events that they cause, such as annotation added/modified, etc. It also adds methods that individual tools use for querying desired behaviour, such as if a link should be followed or not.

The tools could have held a ToolManager instance, but this protocol distils what is actually required of it from a tool’s perspective. The events aren’t dealt with by the toolmanager directly, but are passed to the tool manager’s delegate.

Allows the app to be notified of events that occur due to actions of the tools framework (such as annotation added/modified, etc.), as well as modify default Tools.framework behaviour, for example if a link should be followed or not when tapped.

##Classes

The control that displays a PDF.

A class that mediates between the PTPDFViewCtrl and the individual tools (PTPanTool, PTAnnotEditTool, etc.), and between the individual tools and an app’s ViewController. It passes events from the PTPDFViewCtrl to the active tool, facilitates switching from one tool to the next.

An abstract base class that implements the Tools.framework default and shared functionality for the PTToolSwitching protocol.

These relationships are referring to those labled in the diagram at the top of the article.

An instance of a PTToolManager is set as the PTPDFViewCtrl’s toolDelegate so that it can pass on the event to the currently active tool (PTPanTool, PTAnnotEditTool, etc.).

The PTToolManager’s tool property is the tool instance that is currently active. It is the tool to which all events are sent.

A tool has a reference back to the PTToolManager instance so that it can report changes it has made to the document (such as annotation added/modified, etc.), and to check if default behaviour should be followed (such as following a link, etc). These events aren’t used by the PTToolManager itself, but are passed to the object set as the PTToolManager’s delegate.

The PTToolManager’s delegate property receives the events passed to the PTToolManager by the collection of tools (such as annotation added/modified, etc.).