Custom toolkeyboard_arrow_down

Creating a new tool

com.pdftron: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 oval annotation. Derive from this class if your tool requires drawing oval. Override createMarkup to create your Annot object.
SimpleShapeCreateCreates various shape annotations such as rectangle, oval, 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:

import android.graphics.Color;
import android.support.annotation.NonNull;

import com.pdftron.common.PDFNetException;
import com.pdftron.pdf.annots.Markup;
import com.pdftron.pdf.annots.PolyLine;
import com.pdftron.pdf.annots.Polygon;
import com.pdftron.pdf.tools.RectCreate;
import com.pdftron.pdf.tools.ToolManager;
import com.pdftron.pdf.utils.Utils;

/**
 * This class is for creating rectangular cloudy annotation.
 */
public class CustomTool extends RectCreate {

    // As 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;
    }
}
  1. Register your custom tool to ToolManager as described here.

  2. 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:

import android.support.annotation.NonNull;
import android.view.MotionEvent;
import android.widget.Toast;

import com.pdftron.pdf.PDFViewCtrl;

public class PolygonEdit extends AnnotEdit {
    public static final ToolManager.ToolModeBase MODE = ToolManager.ToolMode.addNewMode();

    public PolygonEdit(@NonNull PDFViewCtrl ctrl) {
        super(ctrl);
    }

    @Override
    public ToolManager.ToolModeBase getToolMode() {
        return MODE;
    }

    @Override
    public boolean onSingleTapConfirmed(MotionEvent e) {
        Toast.makeText(mPdfViewCtrl.getContext(), "Polygon is tapped", Toast.LENGTH_SHORT).show();
        return super.onSingleTapConfirmed(e);
    }
}
  1. Register your custom tool to ToolManager as described here.

  2. 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.

// As PolygonEdit tool is handling Polygon annotation,
// the annotation type parameter is Annot.e_Polygon
ToolConfig.getInstance().putAnnotationToolModePair(Annot.e_Polygon, PolygonEdit.MODE);

linkRegister the custom tool to 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).

mToolManager.addCustomizedTool(new CustomTool(mPdfViewCtrl));

linkRegister custom tool by 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:
ToolManagerBuilder toolManagerBuilder = ToolManagerBuilder
      .from(mPdfViewCtrl, R.style.MyToolManager)
      .addCustomizedTool(PolygonEdit.MODE, PolygonEdit.class);
To learn more about ToolManagerBuilder and R.style.MyToolManager, see initialize ToolManager
  1. Set toolManagerBuilder to ViewerConfig:
ViewerConfig.Builder builder = new ViewerConfig.Builder();
ViewerConfig config = builder
    ...
    .setToolManagerBuilder(toolManagerBuilder)
    .build();
To learn more about ViewerConfig, see PDF fragment config
  1. Add config to DocumentActivity when opening document:
final Uri localFile = Uri.fromFile(new File("myLocalFilePath"));
DocumentActivity.openDocument(context, localFile, config);
To learn more about opening document through DocumentActivity, see using 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):

mToolManager.setTool(mToolManager.createTool(CustomTool.MODE, mToolManager.getTool()));

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:

@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.

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.