Creating a custom PDF viewer tool in Android

The tools package provides several base classes that can be extended to create and add custom tools to the viewer. Click here for a complete list of tools .

In this guide, we will create a custom rectangular cloudy annotation tool for either PDFViewCtrl or PdfViewCtrlTabHostFragment2 . It is recommended to read the following articles before continuing this guide:

• Show a document in a Fragment
• Customize viewer
• Customize ToolManager

From this tool hiearchy list , find a base tool class to extend. For example, here are some of the more commonly used base tool classes:

For our custom rectangular cloudy annotation tool, we'll be creating a class called CustomTool that inherits from RectCreate.

1. In the CustomTool class, override the getToolMode() method. This method must return a custom tool mode, which can be created by calling ToolManager.ToolMode.addNewMode(int) and specifying the custom tool's annotation type.

2. Afterwards, override the feature specific methods and implement the desired custom behavior. Add @Keep so the tool can work properly in release mode. For example here is a custom tool that handles creating rectangular cloudy annotations:

   import com.pdftron.pdf.utils.Utils;
   import com.pdftron.pdf.Point;
   import com.pdftron.pdf.Rect;
   // ...
   
   /**
   * This class is to create a rectangular cloudy annotation.
   */
   @Keep
   public class CustomTool extends RectCreate {
   
       // Since this tool creates polygon annotation, use Annot.e_Polygon as parameter.
       public static ToolManager.ToolModeBase MODE = 
               ToolManager.ToolMode.addNewMode(Annot.e_Polygon);
   
       public CustomTool(@NonNull PDFViewCtrl ctrl) {
           super(ctrl);
       }
   
       @Override
       public ToolManager.ToolModeBase getToolMode() {
           return MODE;
       }
   
       @Override
       protected Annot createMarkup(PDFDoc doc, Rect bbox) throws PDFNetException {
           Polygon poly = new Polygon(Polygon.create(doc, Annot.e_Polygon, bbox));
           ColorPt color = Utils.color2ColorPt(Color.RED);
           poly.setColor(color, 3);
           poly.setVertex(0, new Point(bbox.getX1(), bbox.getY1()));
           poly.setVertex(1, new Point(bbox.getX1(), bbox.getY2()));
           poly.setVertex(2, new Point(bbox.getX2(), bbox.getY2()));
           poly.setVertex(3, new Point(bbox.getX2(), bbox.getY1()));
           poly.setIntentName(PolyLine.e_PolygonCloud);
           poly.setBorderEffect(Markup.e_Cloudy);
           poly.setBorderEffectIntensity(2.0);
           poly.setRect(bbox);
   
           return poly;
       }
   }

All tools are controlled by an instance of ToolManager and it will need to know about the new custom tool before the tool can be used in the viewer.

• Option 1: Register using PdfViewCtrlTabHostFragment2

  A PdfViewCtrlTabHostFragment2 contains an internal reference to ToolManager. A custom tool can be added to this internal ToolManager by using the ToolManagerBuilder class. A ToolManagerBuilder object is passed to an instance of ViewerConfig and used to initialize the viewer with the custom tool. The following method can be called in an activity to add a custom tool to a PdfViewCtrlTabHostFragment2:

  // Add a custom tool to ViewerConfig and use it to initialize a PdfViewCtrlTabHostFragment2
  public PdfViewCtrlTabHostFragment2 addCustomTool(@NonNull Context context, @NonNull Uri fileUri) {
      // Create the ToolManagerBuilder builder and add our custom tool
      ToolManagerBuilder toolManagerBuilder = ToolManagerBuilder
              .from()
              .addCustomizedTool(CustomTool.MODE, CustomTool.class);
      // Add the ToolManagerBuilder builder to a ViewerConfig, that will
      // be used to initialize PdfViewCtrlTabHostFragment2
      ViewerConfig config = new ViewerConfig.Builder()
              .toolManagerBuilder(toolManagerBuilder)
              .build();
      // Create the custom PdfViewCtrlTabHostFragment2 using the custom ViewerConfig object
      return ViewerBuilder2.withUri(fileUri)
              .usingConfig(config)
              .build(context);
  }

• Option 2: Register using PDFViewCtrl

  Alternatively if PDFViewCtrl is used and set up with a ToolManager, you can simply add the custom tool directly to ToolManager by calling:

  // Add a custom tool to ToolManager using PDFViewCtrl
  public void addCustomTool(@NonNull ToolManager toolManager, @NonNull PDFViewCtrl pdfViewCtrl) {
      // Create our custom tool
      Tool customTool = new CustomTool(pdfViewCtrl);
      // Then add it to ToolManager
      toolManager.addCustomizedTool(customTool);
  }

  You can learn more about setting up PDFViewCtrl with ToolManager in the ToolManager customization guide .

To use the custom tool, set it to an instance of ToolManager as follows:

• Option 1: Using PdfViewCtrlTabHostFragment2

  public void useCustomTool(@NonNull PdfViewCtrlTabHostFragment2 fragment) {
      // Create our custom tool
      ToolManager toolManager = fragment.getCurrentPdfViewCtrlFragment().getToolManager();
      ToolManager.Tool customTool = toolManager.createTool(CustomTool.MODE, toolManager.getTool());
      // Then set it in ToolManager
      toolManager.setTool(customTool);
  }

• Option 2: Using PDFViewCtrl

  public void useCustomTool(@NonNull ToolManager toolManager, @NonNull PDFViewCtrl pdfViewCtrl) {
      // Create our custom tool
      Tool customTool = new CustomTool(pdfViewCtrl);
      // Then add it to ToolManager
      toolManager.addCustomizedTool(customTool);
  }

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

You will be able to switch tool modes within the same tool class 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 for more information ). So if the custom tool wants to switch to another tool during a motion event, you can set the 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:

@Override
public boolean onSingleTapConfirmed(MotionEvent e) {
    mNextToolMode = safeSetNextToolMode(ToolManager.ToolMode.TEXT_HIGHLIGHT);
    return false;
}

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