Select or deselect annotations on Android

To be able to select annotations in a document, certain preconditions need to be met:

• The document must have the ANNOTATIONS_AND_FORMS permission enabled.

• Your Nutrient license must include annotation editing.

• Annotation editing must be enabled by the PdfConfiguration — which is the default — both in general and for the type of the annotation to be selected.

• The annotation must not have the READONLY flag set.

General selection

To select an annotation in the user interface (UI), tap it. This will automatically invoke the annotation editing mode. To unselect an annotation, tap it again.

Annotations can be programmatically selected using PdfFragment methods:

• selectAnnotation for single selection

• selectAnnotations for multi-selection

Multi-selection

If you want to select multiple annotations, start the multi-selection mode. This can be done two ways.

The first is by tapping the selection tool in the annotation creation toolbar.

The second is by long-clicking a selected annotation until a popup toolbar appears and then choosing SELECT MORE…

Multi-selection across page bounds isn’t supported; all selected annotations need to be on the same page.

Selecting

When multi-selection mode is active:

• Tap an annotation to toggle its selected state.

• Drag a selection rectangle from an empty space on the page, and all annotations touched/contained within the selection rectangle will be added to the selection.

Swiping pages during multi-selection mode is disabled, as having it enabled would make it impossible to use rectangle selection. However, the thumbnail bar at the bottom of the screen can be used to navigate to other pages.

Dragging and dropping

Multi-selection can be moved and resized, which will affect all selected annotations, but only if all of the selected annotations are editable.

Editing annotation properties

If all selected annotations share the same AnnotationType, the annotation inspector can be used to change property values — such as colors and sizes — of all selected annotations at once. A mixed selection of annotation types won’t allow you to open the property inspector.

Observing selection changes

To observe selection changes, an instance of the OnAnnotationSelectedListener interface can be implemented and registered with your PdfFragment instance. It has the following callback methods, and they’ll be called regardless of if the selection happens by user interaction or programmatically:

• onPrepareAnnotationSelection is called before an annotation is selected. By returning false, you can prevent the annotation from being selected.

• onAnnotationSelected is called for each annotation after it’s selected.

• onAnnotationSelectionFinished marks the end of the selection process and will inform you about all the currently selected annotations.

The deselection of annotations can be tracked by the OnAnnotationDeselectedListener.

Note that changing the current selection will first deselect any selected annotations before selecting the new ones.

Grouping

Annotations can be grouped and ungrouped with the popup toolbar.

• The GROUP item will show up if at least two annotations are selected and they’re not grouped or not in the same group.

• The UNGROUP item is available if at least one of the selected items is part of a group.

Internally, grouping is handled by setting an annotation’s group property, and this property can be set to an arbitrary string. We provide a method to create a new group name, makeNewGroupId, but you’re not obliged to use it; you can pick any name you like. All annotations on the same page with the same group value are considered a group. The group information is stored in the PDF document, but it’s a proprietary property of our SDK and will only work with our viewer. If a grouped annotation is selected, all other members of the group will be selected.

The following code snippet shows how to query all grouped annotations of a page and organize them by their group name:

val groupedAnnotations = document.annotationProvider.getAnnotations(pageIndex)
    .filter { it.group != null }  // Skip ungrouped annotations,
    .groupBy { it.group }

var groupedAnnotations = new HashMap<String, ArrayList<Annotation>>();
for (var annotation : document.getAnnotationProvider().getAnnotations(pageIndex)) {
    var group = annotation.getGroup();
    if (group != null) { // Skip ungrouped annotations.
        if (!groupedAnnotations.containsKey(group)) {
            groupedAnnotations.put(group, new ArrayList<>());
        }
        groupedAnnotations.get(group).add(annotation);
    }
}