Some test text!

keyboard_arrow_down

Get started

keyboard_arrow_down

Fundamentals

keyboard_arrow_down

Document Viewer

keyboard_arrow_down

Document Viewer components

keyboard_arrow_down

Annotation and collaboration

keyboard_arrow_down

Advanced customization

keyboard_arrow_down

Conversion

keyboard_arrow_down

Parsing and extraction

keyboard_arrow_down

Digital signatures

keyboard_arrow_down

Form filling

keyboard_arrow_down

Search

keyboard_arrow_down

Redaction

keyboard_arrow_down

Advanced topics

keyboard_arrow_down

Other frameworks

keyboard_arrow_down

Reference

keyboard_arrow_down

PDF Processing API

Create a custom tool

In this document
chevron_rightCreate an annotation creation tool
chevron_rightCreate an annotation handler tool
chevron_rightRegister the custom tool using ToolManager
chevron_rightRegister the custom tool using ViewerConfig
chevron_rightUse the custom tool
chevron_rightSwitch to another tool during motion events within the custom tool

The tools package provides several essential tool base classes that allow you to extend further. Click here for a complete list of Tools.

linkCreate an annotation creation tool

Annotation creation tool can creates an annotation. For example, RectCreate tool can draws a rectangle and creates Square annotation. You can create a custom annotation creation tool as follows:

  1. Find an annotation creation base tool class to extend:
ToolDescription
TextMarkupCreateCreates a text markup annotation. Derive from this class if you are creating annotation on text. Override createMarkup to create your Annot object.
RectCreateDraws and creates a rectangle annotation. Derive from this class if your tool requires drawing rectangle, for example, checkbox form field. Override createMarkup to create your Annot object.
OvalCreateDraws and creates an ellipse annotation. Derive from this class if your tool requires drawing ellipse. Override createMarkup to create your Annot object.
SimpleShapeCreateCreates various shape annotations such as rectangle, ellipse, ink line and more. Use this class if none of the above works for you. Override createMarkup to create your Annot object.
  1. In your custom tool mode class, override getToolMode() function, make sure it returns your custom tool mode. You can create a custom tool mode by calling: ToolManager.ToolMode.addNewMode(int), the parameter is the type of annotation that your custom tool to create.

    For example, let's create a CustomTool.java that creates rectangular cloudy annotation:

  2. Register your custom tool to ToolManager as described here.

  3. You can use your custom annotation creation tool as described here

linkCreate an annotation handler tool

An annotation handler tool can be triggered when tapping on the annotation. For example, when user tapping on a Link annotation, LinkAction tool is triggered to handle Link annotation. You can create a custom annotation handler tool as follows:

  1. Create your custom tool that extends AnnotEdit class. AnnotEdit is responsible for editing selected annotation such as moving and resizing.

  2. Override getToolMode() function which returns your custom tool mode. You can create your custom tool mode by calling ToolManager.ToolMode.addNewMode().

  3. Override onSingleTapConfirmed(MotionEvent) function to handle the annotation.

    For example, let's create a PolygonEdit.java that show a toast message when tapping on Polygon annotation:

  4. Register your custom tool to ToolManager as described here.

  5. Also register your custom tool to ToolConfig by calling ToolConfig.putAnnotationToolModePair(int, ToolManager.ToolMode). It lets Pan tool switch to the PolygonEdit tool when tapping on the Polygon annotation.

linkRegister the custom tool using ToolManager

All tools are controlled in ToolManager. To use your custom tool just like one of the default tools, you will need to let ToolManager know about your new custom tool. You can add the custom tool to ToolManager by calling ToolManager.addCustomizedTool(Tool).

linkRegister the custom tool using ViewerConfig

Alternatively, if you are using DocumentActivity or PdfViewCtrlTabHostFragment for loading PDF. You can use ViewerConfig for configuring PDF fragment. With ViewerConfig, you can add custom tool to ViewerConfig.

For example, You can register custom PolygonEdit to DocumentActivity as following:

  1. In the activity where you setup DocumentActivity or PdfViewCtrlTabHostFragment, add custom tool to ToolManagerBuilder:

    To learn more about ToolManagerBuilder and R.style.MyToolManager, see initialize ToolManager
  2. Set toolManagerBuilder to ViewerConfig:

    To learn more about ViewerConfig, see PDF fragment config
  3. Add config to DocumentActivity when opening document:

    To learn more about opening document using DocumentActivity, see show a document in an activity

linkUse the custom tool

When you want to use your custom tool, whether triggered by a button click or motion events, simply call ToolManager.setTool(ToolManager.Tool):

Now, when using the custom tool, you will see:

linkSwitch to another tool during motion events within the custom tool

You will be able to switch tool modes within the same tool in response to a motion event, such as onDown(MotionEvent), onDoubleTap(MotionEvent) and so on.

In gesture event functions, if one tool switches to another tool, that motion event will continue to be executed in the next tool. See Tools Overview. So if the custom tool wants to switch to another tool during motion event, you can set next tool mode by calling Tool.safeSetNextToolMode(ToolMode).

For example, let's override onSingleTapConfirmed in CustomTool.java, and set the next tool to be TextHighlightCreate:

Now, in response to a single tap while using your custom tool, it will switch to the TextHighlightCreate tool.

If you need to save a tool mode in preference for retrieving it at a later time, you can use .toString() on the ToolMode. Then later retrieve it via ToolMode.valueOf(String) to get back the ToolMode.