This HTML page is not optimized for LLM or AI agent consumption. Fetch the Markdown version instead: /guides/android/annotations/custom-annotation-editing-controls.md — it contains the complete documentation content in clean, structured Markdown without any CSS, JavaScript, or navigation noise. Customize annotation creation toolbar in Android PDF viewer | Nutrient

Customizing the annotation creation toolbar in our Android PDF viewer

Markdown version of this page, suitable for AI agents and automation

You can control which annotation tools are enabled in the annotation creation toolbar. You can also 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 annotation creation toolbar that hosts all the enabled annotation tools. When a user taps a tool in the toolbar, the activity enters annotation mode for that tool. To change the toolbar itself, its items, their grouping, its dock, or to react to its taps, see customizing contextual toolbars.

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, so you can 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() creates 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 a specific variant, use the PdfFragment#enterAnnotatingMode() overload that takes both the annotation tool and the annotation tool variant:

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

To synchronize annotation tool variants with the iOS version, two exceptions 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 fragment enters creation mode, it calls the listener and gives 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
}