Tools overview

Apryse SDK provides tools libraries containing many annotation and document interaction tools.

Android

Annotation tools overview for Xamarin.Android viewer

What are annotation interactive tools?

The principal means of user interaction with the document being viewed, other than buttons, is the currently active tool. Selection, panning, and annotation creation, are all achieved using different tools. We provide many default tools to provide a full viewing experience out of the box. But fortunately API hooks for the tools appearance and logic is provided, so you can always achieve whatever customization you like using our existing API, or with your changes.

By default each annotation type has an associated tool to allow you to create those annotations. It's possible to create multiple tools for the same annotation type, for example a rectangle tool with a default color of blue and another tool with a default color of red. When creating a custom annotation you'll need to create an associated annotation tool to define how the user can create that annotation.

Technical overview

The tools listed above handle interactions by receiving touch and gesture events forwarded from PDFViewCtrl. When touches or gestures are made, PDFViewCtrl sends corresponding events to its ToolManager.

The ToolManager is then responsible for passing the event to the current tool. If the current tool has fully handled the event, the event processing is finished. If the current tool cannot fully handle the event, the tool manager then forwards the event to the next tool.

The Tool class implements the ToolManager.Tool interface, thus handling all events passed to it from ToolManager. The ToolManager is responsible for passing the event to the current tool. If the current tool has fully handled the event, the processing of the event is finished. If the current tool cannot fully handle the event, the tool manager then forwards the event to the next tool.

Annotation and its creation tool

The following table shows which tool mode is selected when a new annotation is created:

Tool	ToolMode	Annot
AreaMeasureCreate	AREA_MEASURE_CREATE	Polygon
ArrowCreate	ARROW_CREATE	Line
CalloutCreate	CALLOUT_CREATE	FreeText
CheckboxFieldCreate	FORM_CHECKBOX_CREATE	Widget
CloudCreate	CLOUD_CREATE	Polygon
DigitalSignature	DIGITAL_SIGNATURE	Widget
FileAttachmentCreate	FILE_ATTACHMENT_CREATE	FileAttachment
FreehandCreate	INK_CREATE	Ink
FreeTextCreate	TEXT_CREATE	FreeText
LineCreate	LINE_CREATE	Line
OvalCreate	OVAL_CREATE	Circle
PerimeterMeasureCreate	PERIMETER_MEASURE_CREATE	PolyLine
PolygonCreate	POLYGON_CREATE	Polygon
PolylineCreate	POLYLINE_CREATE	PolyLine
RectCreate	RECT_CREATE	Square
RectLinkCreate	RECT_LINK	Link
RubberStampCreate	RUBBER_STAMPER	RubberStamp
RulerCreate	RULER_CREATE	Line
StickyNoteCreate	TEXT_ANNOT_CREATE	Text
Signature	SIGNATURE	Widget
SignatureFieldCreate	FORM_SIGNATURE_CREATE	Widget
SoundCreate	SOUND_CREATE	Sound
TextFieldCreate	FORM_TEXT_FIELD_CREATE	Widget
TextHighlightCreate	TEXT_HIGHLIGHT	Highlight
TextLinkCreate	TEXT_LINK_CREATE	Link
TextSquigglyCreate	TEXT_SQUIGGLY	Squiggly
TextStrikeoutCreate	TEXT_STRIKEOUT	StrikeOut
TextUnderlineCreate	TEXT_UNDERLINE	Underline

Annotation and its handling tool

The following table shows which tool mode is selected when an annotation is selected for editing/handling:

Annot	Tool	ToolMode
Circle	AnnotEdit	ANNOT_EDIT
FileAttachment	AnnotEdit	ANNOT_EDIT
FreeText	AnnotEdit	ANNOT_EDIT
Highlight	AnnotEditTextMarkup	ANNOT_EDIT_TEXT_MARKUP
Ink	Eraser	INK_ERASER
Line	AnnotEditLine	ANNOT_EDIT_LINE
Link	LinkAction	LINK_ACTION
PolyLine	AnnotEditAdvancedShape	ANNOT_EDIT_ADVANCED_SHAPE
Polygon	AnnotEditAdvancedShape	ANNOT_EDIT_ADVANCED_SHAPE
RichMedia	RichMedia	RICH_MEDIA
Sound	AnnotEdit	ANNOT_EDIT
StrikeOut	AnnotEditTextMarkup	ANNOT_EDIT_TEXT_MARKUP
Square	AnnotEdit	ANNOT_EDIT
Squiggly	AnnotEditTextMarkup	ANNOT_EDIT_TEXT_MARKUP
Underline	AnnotEditTextMarkup	ANNOT_EDIT_TEXT_MARKUP

The ToolManager uses the Pan tool as its default tool. The Pan tool handles almost all user actions, such as tapping on an annotation, long-pressing to show the Quick Menu, and so forth. When the user taps on an annotation, the Pan tool is exchanged for a new tool for handling the tap event, the identity of the new tool corresponding to the selected annotation. For example, if, while using the Pan tool, the user taps on a Link annotation, the Pan tool will set the next tool to be the LinkAction tool. Then, the Link annotation will be handled by the LinkAction tool using LinkAction.onSingleTapConfirmed(MotionEvent). Besides gesture events such as onSingleTapConfirmed, onUp, and so forth, ToolManager.onQuickMenuClicked(QuickMenuItem) also follows the same flow.

iOS

Annotation tools overview for Xamarin.iOS viewer

About Tools

Apryse for iOS includes Tools.framework, an open-source framework that implements virtually all of the SDK's UI functionality. Because the tools framework is open source, the Apryse UI is customizable without restriction or limitation.

The tools framework itself is optional. Without it, the PTPDFViewCtrl will display a PDF with scrolling and zooming, but will not support text selection, interactive annotation handling, etc.

The Tools framework covers of two major aspects:

1. **PDF Interaction tools:**PDF interaction tools are those that handle the user's direct interaction with the PDF, that is touching the PDF directly. This functionality includes:

• Text selection
• Annotation creation/modification/deletion
• Form filling
• Signatures
• Link following
• Multimedia handling

1. **UI Controls:**The UI controls are views that are separate from the PDF:

• PDF outline (table of contents)
• User-created bookmarks
• Annotation toolbar
• Annotation listing
• Page manipulation via a grid of thumbnails

The Tools framework does not rely on any special or private access to Apryse APIs. The PDF interaction tools are implemented entirely by implementing the PTPDFViewCtrl's PTPDFViewCtrlToolDelegate protocol and using PDFNet.framework's public and cross-platform APIs. The UI controls rely solely on PDFNet.framework.

The tools source code is provided as part of the SDK and so it can be customized as required for your app, or simply referenced as sample code.

PDF Interaction Tools

Overview

The PDF interaction tools implement the functionality that occurs when the user touches the PDF itself.

The interaction tools use a "manager" class, the aptly named PTToolManager, that serves as the PTPDFViewCtrltoolDelegate. It receives events, and passes the information to a set of tools that it mediates. Each of these tools is a class that implements the functionality for some particular purpose, such as text selection, form filling, ink drawing, and so on.

Tool manager event handling

The PTToolManger is responsible for passing the event to its current tool. If the current tool has fully handled the event, it returns true, and no further event processing takes place. If the current tool cannot fully handle the event, it returns false, and the tool manager replaces its current tool with a new one (provided by the old tool's getNewTool method), and forwards the event to it for further processing.

The control flow is illustrated below:

How events are handled by Tools.framework.

Example: Tapping on an annotation

As a concrete example, the steps outlined below illustrate how a tap on an annotation would be handled. We will assume that the user is not actively "doing something" on the PDF, so that PTToolManager's tool at the time of the tap is the general purpose PTPanTool.

1. The user taps the PDF displayed by the PTPDFViewCtrl.
2. The tap event is forwarded to the PTPDFViewCtrl's toolDelegate object, which is the Tool.framework's PTToolManager.
3. The PTToolManager receives the event, and sends it to its current tool, which as discussed is the PTPanTool.
4. The PTPanTool checks what, if anything (link, form field, etc.), was tapped. In this example, it was a markup annotation. The PTPanTool "knows" this needs to be handled by the PTAnnotEditTool, and internally notes this for future use in its method getNewTool.
5. The PTPanTool returns false, indicating to the PTToolManager that event processing has not been completed.
6. The PTToolManager calls PTPanTool's method getNewTool, which returns a new tool, in this case an PTAnnotEditTool, which should continue handling the event.
7. The PTToolManager sets its current tool to the instance of the new PTAnnotEditTool, which causes the PTPanTool to be destroyed.
8. The PTToolManager sends the tap event to the PTAnnotEditTool, which handles the event by selecting the annotation.
9. The PTAnnotEditTool returns true from the tap event, indicating to the PTToolManager that it has been fully handled the event and it does not to be further processed by another tool.

While the above may initially seem long, it is following a fairly simple pattern: a tool implements specific responses to touch events, and tell the tool manager if they have fully handled the event or not. If so, that is the end of the event processing; if not, a new tool is created and the event is sent to it.

Event walkthrough

To understand the above flow in code terms, it is most useful to look at the "tool loop" (method runToolLoop:) in the PTToolManager. Here is the essence of the loop for a tap event:

BOOL handled = YES;
do {
    // The tool manager calls the event method, handleTap:, on the current tool, self.tool.
    // If the tool was able to finish processing the event, it returns true; otherwise, false.
    // For example, when using the PanTool (in charge of general scrolling), a tap on empty page space or an image would return true, but a tap on an annotation or form field would return false.
    handled = [self.tool handleTap:gestureRecognizer];
    
    // did the tool finish processing this event?
    if( !handled )
    {
        // If the current tool did not finish handling the event, it needs to be handled by a different tool. The current tool is responsible for indicating which tool type should be used next, via its getNewTool method.
        // For example, if a tap were detected to occur on annotation, it is likely that that the tool that should handle this event is the AnnotEditTool, and so an instance of AnnotEditTool would be returned by getNewTool.
        self.tool = [self.tool getNewTool];
    }
 
// continue to loop until the event has been handled. 
} while (!handled);

For a further look on how interaction tools work, see the article about how to create a new tool.