Annotation and PDF interaction customization

Apryse SDK provides various customization options for annotations interacting with documents.

Android

Customize annotation interactions in Xamarin.Android viewer

This tutorial only applies to Xamarin.Android. See Xamarin.iOS equivalent here .

You will need to use ToolManager for PDF interaction tools to work. You can build it easily using ToolManagerBuilder, a helper class for configuring and creating ToolManager. It also sets ToolManager to a specific PDFViewCtrl.

Build a default ToolManager

To build a default ToolManager, use ToolManagerBuilder and pass in an instance of PDFViewCtrl:

var mToolManager = pdftron.PDF.Config.ToolManagerBuilder.From()
    .Build(this, mPdfViewCtrl);

Build a custom ToolManager programmatically

You can customize the ToolManager programmatically with ToolManagerBuilder:

var mToolManager = pdftron.PDF.Config.ToolManagerBuilder.From()
    .SetEditInk(true)
    .SetOpenToolbar(true)
    .SetBuildInPageIndicator(false)
    .SetCopyAnnot(true)
    .DisableToolModes(new ToolManager.ToolMode[]{
        ToolManager.ToolMode.TextAnnotCreate,
        ToolManager.ToolMode.TextCreate,
        ToolManager.ToolMode.TextSquiggly,
        ToolManager.ToolMode.InkEraser,
        ToolManager.ToolMode.FormCheckboxCreate,
        ToolManager.ToolMode.RectCreate,
        ToolManager.ToolMode.TextLinkCreate
    })
    .Build(this, mPdfViewCtrl);

Supporting image stamp and image signatures

Image stamps and image signatures require a source image in order to create the annotation. If you are using PDFViewCtrl with ToolManager, will need to handle this manually in your app by implementing the methods ToolManager.AdvancedAnnotationListener.imageStamperSelected(PointF) and ToolManager.AdvancedAnnotationListener.imageSignatureSelected(PointF, int, Long).

For reference you can check out our PDFViewCtrl integration guide here

Build a custom ToolManager with style

You can also customize the ToolManager by defining an Android style resource and passing it to ToolManagerBuilder:

1. Create a custom style in your res/values/styles.xml file:For additional customization, a list of supported style attributes are defined in this table.

<style name="MyToolManager"> <!-- allow editing ink annotations (only works if annotation toolbar is present) --> <item name="edit_ink_annots">true</item> <!-- when ink selected in annotation toolbar, it should open its own ink toolbar --> <item name="open_toolbar_on_pan_ink_selected">true</item> <!-- hide the built-in page number indicator --> <item name="build_in_page_number_indicator">false</item> <!-- whether to copy marked-up text of TextMarkup annot to annotation's 'content' property upon TextMarkup annotation creation --> <item name="copy_annotated_text_to_note">true</item> <!-- remove some tools from AnnotationToolbarComponent and QuickMenu --> <item name="disable_tool_modes">@array/disable_tool_modes</item> </style>

1. In the previous step, @array/disable_tool_modes is a string array defining tool modes that should be disabled. You can define it in res/values/arrays.xml:Each <item> in the array needs to be a string matching one of the enum values from ToolManager.ToolMode.

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string-array name="disable_tool_modes">
        <item>TEXT_ANNOT_CREATE</item>
        <item>TEXT_CREATE</item>
        <item>TEXT_SQUIGGLY</item>
        <item>INK_ERASER</item>
        <item>FORM_CHECKBOX_CREATE</item>
        <item>RECT_CREATE</item>
        <item>TEXT_LINK_CREATE</item>
    </string-array>
</resources>

You can also set up ToolManagerBuilder programmatically. For a list of settings available, see the ToolManagerBuilder API.

1. Lastly, build the ToolManager using ToolManagerBuilder and pass in your custom style and an instance of PDFViewCtrl:Alternatively, you can pass the ToolManager style resource directly to ViewerConfig.Builder. You can learn more about configuring ToolManager with ViewerConfig in the viewer configuration guides.

var mToolManager = pdftron.PDF.Config.ToolManagerBuilder.From(this, Resource.Style.MyToolManager)
    .Build(this, mPdfViewCtrl);

XML style attributes

Attributes	Description	Format
edit_ink_annots	Controls whether editing ink annotations is allowed (only works if annotation toolbar is present) Default value: false	Format: boolean
open_toolbar_on_pan_ink_selected	Whether annotation toolbar should open when Ink is selected from quick menu (only works if annotation toolbar is present) Default value: false	Format: boolean
build_in_page_number_indicator	Whether to use/show the built-in page number indicator Default value: true	Format: boolean
annot_permission_check	Whether to check annotation author's permission Default value: false	Format: boolean
show_author_dialog	Whether to show author dialog the first time the user annotates Default value: false	Format: boolean
copy_annotated_text_to_note	Whether to copy marked-up text of TextMarkup annot to annotation's 'content' property upon TextMarkup annotation creation Default value: false	Format: boolean
stylus_as_pen	Whether to enable using stylus to draw without having to enter ink tool Default value: false	Format: boolean
ink_smoothing_enabled	Whether to smooth ink annotations Default value: true	Format: boolean
auto_select_annotation	Whether to auto-select annotations after they are created Default value: true	Format: boolean
quick_menu_disable	Whether disable showing quick menu Default value: false	Format: boolean
double_tap_to_zoom	Whether double-tapping should zoom the viewer Default value: true	Format: boolean
auto_resize_freetext	Whether can auto resize free text bounding box when editing Default value: false	Format: boolean
realtime_annot_edit	Whether annotation editing is real time Default value: true	Format: boolean
edit_freetext_on_tap	Whether can edit freetext on tap Default value: false	Format: boolean
show_saved_signatures	Whether can show saved signatures in signature dialog Default value: true	Format: boolean
show_annot_indicator	Whether can show indicator for annotations with comments Default value: true	Format: boolean
disable_tool_modes	Array of tools to disable Default value: null	Format: reference
disable_annot_editing_by_types	Array of annotation types to disable editing Default value: null	Format: reference

iOS

Customize annotation interactions in Xamarin.iOS viewer

This tutorial only applies to Xamarin.iOS. See Xamarin.Android equivalent here .

Annotation and PDF interaction is implemented within the open-source Tools.framework. This includes annotation creation & selection, text selection, form filling and link following.

The behavior is implemented via a collection of "Tools": classes that derive from the abstract base class PTTool and that are coordinated by a PTToolManager. The PTToolManager provides the ability to customize tool behavior, and enable/disable the ability for users to create or edit annotations (both in general and on an annotation type by annotation type basis).

Create and edit annotations

To disable (or re-enable) the ability to create or edit annotations, options can be altered as shown below. When disabled, the relevant annotation tool is removed from the annotation toolbar, and from the UIMenuController.

// disables all text annotation types (highlights, underlines, etc.)
ToolManager.HighlightAnnotationOptions.CanCreate = false;
ToolManager.HighlightAnnotationOptions.CanEdit = false;
ToolManager.UnderlineAnnotationOptions.CanCreate = false;
ToolManager.UnderlineAnnotationOptions.CanEdit = false;
ToolManager.StrikeOutAnnotationOptions.CanCreate = false;
ToolManager.StrikeOutAnnotationOptions.CanEdit = false;
ToolManager.SquigglyAnnotationOptions.CanCreate = false;
ToolManager.SquigglyAnnotationOptions.CanEdit = false;

Annotation interaction and UIMenuController

Further control over annotation interaction behaviour via the PTToolManagerDelegate protocol.

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

1. PTToolManager.ShouldSelectAnnotationThis 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. PTToolManager.ShouldShowMenuThis 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. PTToolManager.ShouldHandleLinkAnnotationThis method is called just before a link is followed. The link is provided so that alternate action can be taken if required.
4. PTToolManager.ShouldSwitchToToolThis method is called just before a tool is activated. The tool is available for the decision making process.

Example

The sample code uses ShouldShowMenu 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.

mToolManager.ShouldShowMenu = (sender, menuController, annotation, pageNumber) =>
{
    // remove all items except signature and free text
    if (mToolManager.Tool is pdftron.PDF.Tools.PanTool)
    {
        menuController.MenuItems = removeQuickMenuItem(menuController.MenuItems);
    }
    return true;
};

UIMenuItem[] removeQuickMenuItem(UIMenuItem[] items) {
    var itemsArray = new List<UIMenuItem>(items);
    var itemsToRemove = new List<String> {
        "Note",
        "Ink",
        "Arrow",
        "Line",
        "Rectangle",
        "Ellipse"
    };

    for (int i = 0; i < items.Length; i++) {
        var itemStr = PDFViewCtrlToolsUtil.ToolsBundle.GetLocalizedString(items[i].Title, null);
        if (itemsToRemove.Contains(itemStr)) {
            itemsArray.Remove(items[i]);
        }
    }
    return itemsArray.ToArray();
}

Default Menu Options	Customized Menu Options

Override classes

Tools.framework frequently creates new instances of objects defined within the framework (e.g. a new instance of PTAnnotEditTool is created when a user taps on an annotation). In order to customize certain aspects of the default behavior, it is required to create and use a subclass of the built-in tool. To enable this without requiring source code modification, Tools.framework includes a system to "inject" an externally defined subclass that will be used by the Tools.framework during its normal operation. This is done via the PTOverrides class as follows:

// EGAnnotEditTool is an externally defined class that derives from PTAnnotEditTool
var cls = new Class(typeof(PTAnnotEditTool));
var own = new Class(typeof(EGAnnotEditTool));
PTOverrides.OverrideClass(cls, own);

Note that in order to be compatible with the external override system, the base class must conform to the PTOverridable protocol.

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 by first 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.)

Then create the Xamarin binding as described here: Create Tools package from PDFViewCtrlTools Objective-C source code .