> 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/xamarin/annotation/tools-overview.md). # Tools overview Discover how Apryse SDK provides a comprehensive set of annotation and document interaction tools for Xamarin.Android viewer. Learn about the various interactive tools available and how to customize t Apryse SDK provides tools libraries containing many annotation and document interaction tools. {% tabs %} {% tab title="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`](https://sdk.apryse.com/api/xamarinandroid/pdfnet/api/pdftron.PDF.PDFViewCtrl.html). When touches or gestures are made, `PDFViewCtrl` sends corresponding events to its [`ToolManager`](https://sdk.apryse.com/api/xamarinandroid/tools/api/pdftron.PDF.Tools.ToolManager.html). 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. ![](https://653871032-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgjsBtuYmcKhWOdM9VCg4%2Fuploads%2Fgit-blob-f4a9aeb1ec5f14f75232fb7f0e458fb76e103f38%2F6f270a7d76aae9a93d66a7b27a5e849f454c6d14-992x267.png?alt=media) ## 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`](https://sdk.apryse.com/api/xamarinandroid/tools/api/pdftron.PDF.Tools.DigitalSignature.html) | `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. {% endtab %} {% tab title="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`](https://sdk.apryse.com/api/xamarinios/tools/api/pdftron.PDF.PDFViewCtrl.html) 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](https://sdk.apryse.com/api/xamarinios/pdfnet/api/index.html) and [cross-platform](#tool-manager-event-handling) 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`](https://sdk.apryse.com/api/xamarinios/tools/api/pdftron.PDF.Tools.PTToolManager.html), 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: ![](https://653871032-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgjsBtuYmcKhWOdM9VCg4%2Fuploads%2Fgit-blob-ad0d20ab343bee0f189b32ac44fe0ba2c1703468%2F3968e47547dfbb106c1e826a74e19930f39f5792-820x442.png?alt=media) 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`](https://sdk.apryse.com/api/xamarinios/tools/api/pdftron.PDF.Tools.PTToolManager.html). 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`](https://sdk.apryse.com/api/xamarinios/tools/api/pdftron.PDF.Tools.PTToolManager.html). Here is the essence of the loop for a tap event: {% code lineNumbers="true" %} ```objc 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); ``` {% endcode %} For a further look on how interaction tools work, see the article about how to [create a new tool](/ios/ui-customization/custom-tool.md). {% endtab %} {% endtabs %} --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.apryse.com/xamarin/annotation/tools-overview.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.