Customizing the annotation creation toolbar in our Android PDF viewer

You can control which annotation tools are enabled in the annotation creation toolbar, as well as build your own custom views and user interfaces for creating and editing annotations. This guide describes the existing Nutrient APIs for accomplishing this.

Controlling which annotation tools are enabled

You can control which annotation tools are enabled in the annotation creation toolbar via #enabledAnnotationTools. Passing null or an empty list to this method means that all supported annotation tools are enabled. For example:

// In this example, you want to enable all annotation tools except the `IMAGE` tool.
val enabledAnnotationTools = AnnotationTool.values().toMutableList()
enabledAnnotationTools.remove(AnnotationTool.IMAGE)


val config =
    PdfActivityConfiguration.Builder(context)
        // By default, all supported annotation tools are enabled.
        // You can selectively enable certain tools by providing them here.
        .enabledAnnotationTools(enabledAnnotationTools)
        .build()

Certain AnnotationTools are enabled only when their underlying annotation type, AnnotationTool#toAnnotationType, is editable and annotation editing is enabled.

Entering annotation mode

You can build your own custom views and user interfaces for creating and editing annotations.

The default PdfActivity comes with an AnnotationToolbar that hosts all the available annotation tools. When a user taps an icon from the toolbar, the activity will enter annotation mode for the tapped tool.

In your code, you can enter annotation mode by calling PdfFragment#enterAnnotatingMode with the desired AnnotationTool value as the argument:

// Enters the signature annotation mode. After tapping the document, the user will be asked to enter a signature.
val tool = AnnotationTool.SIGNATURE
pdfFragment.enterAnnotatingMode(tool)

Browse the available AnnotationTool values to see which tools you can use. For example, to select the ink eraser, you can use AnnotationTool.ERASER.

To leave annotation mode (switching back to the normal viewing mode), you can call PdfFragment#exitCurrentlyActiveMode:

// Leaves a previously launched annotation mode.
pdfFragment.exitCurrentlyActiveMode()

PdfFragment#exitCurrentlyActiveMode can also be used to leave other special modes — for example, text selection.

Annotation tool variants

Annotation tools can also have specified variants, and this allows you to have the same annotation tools with different presets. Annotation tool variants are defined by the AnnotationToolVariant class. This class serves as a wrapper around the string that specifies the name of the variant. Keep in mind that the same variant can be bound to multiple annotation tools. So for example, you can have an ink, line, and highlight tool, all in a “yellow” variant.

To initialize the AnnotationToolVariant object, you can use one of the three static constructors (which one you use depends upon your use case):

  • AnnotationToolVariant.defaultVariant() will create the default variant used by the framework for most of the tools.
  • AnnotationToolVariant.fromPreset() allows you to create the variant from the AnnotationToolVariant.Preset enum, which specifies variants used by our framework.
  • AnnotationToolVariant.fromName() creates your custom variant with the specified name.

To start annotation mode with the specified annotation tool variant, use the version of PdfFragment#enterAnnotatingMode() that has both the annotation tool and annotation tool variant as parameters, like so:

val tool = AnnotationTool.INK
pdfFragment.enterAnnotatingMode(tool, AnnotationToolVariant.fromName("my_red_thin_ink_variant"))

To synchronize annotation tool variants with the iOS version, there are two exemptions where we start annotation mode with specific variants. One is the Magic Ink tool, which uses AnnotationTool.MAGIC_INK with the variant you can get via AnnotationToolVariant.fromPresets(Preset.MAGIC). The other one is the free text callout tool, which uses AnnotationTool.FREETEXT_CALLOUT with the variant you can get via AnnotationToolVariant.fromPresets(Preset.CALLOUT).

Our framework comes with the following predefined annotation tool variant presets (specified in the AnnotationToolVariant.Preset enum class):

  • PEN — Preset for the pen variant of the ink, used with AnnotationTool.INK in the framework.
  • HIGHLIGHTER — Preset for the highlighter variant of the ink, used with AnnotationTool.INK in the framework.
  • MAGIC— Preset for the magic variant, used with AnnotationTool.MAGIC_INK in the framework.
  • CALLOUT — Preset for the callout variant, used with AnnotationTool.FREETEXT_CALLOUT in the framework.
  • ARROW — Preset for the arrow variant, used with AnnotationTool.LINE in the framework.
  • DEFAULT — Preset for all other tools that have no variant specified.

To start one of our tools programmatically, use the AnnotationToolVariant.fromPreset() creator — for example:

// Start the pen tool.
val tool = AnnotationTool.INK
val toolVariant = AnnotationToolVariant.fromPreset(AnnotationTool.Preset.PEN)
pdfFragment.enterAnnotatingMode(tool, variant)

Mode listeners

If you need more control of the annotation creation mode, you can register an OnAnnotatingModeChangeListener on the fragment. Once the creation mode is entered, the listener will be called, giving you access to the AnnotatingController. The controller object gives you access to all properties of the currently created annotation (color, size, style, etc.):

class ExampleActivity : PdfActivity(), OnAnnotatingModeChangeListener {


    // ...


    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        pdfFragment.addOnAnnotatingModeChangeListener(this)
    }


    override fun onEnterAnnotatingMode(controller: AnnotatingController) {
        controller.color = Color.RED
        controller.thickness = 10
    }


    /**
     * This method is called whenever the current annotation mode is replaced by another one —
     * for example, when subsequently calling `enterAnnotatingMode(...)`.
     */
    override fun onChangeAnnotatingMode(controller: AnnotatingController) = Unit


    /**
     * This is called when the current annotation mode is left —
     * for example, when calling `fragment.exitCurrentlyActiveMode()`.
     */
    override fun onExitAnnotatingMode(controller: AnnotatingController) = Unit
}