Z-Index for annotation stacking order on Android

The annotation z-index defines the stacking order of annotations on a page. An annotation with a lower z-index will be positioned at the back of the page, whereas annotations with a higher number will be positioned on top of annotations with a lower z-index. This means the annotations with a lower z-index will be obscured if the annotations are overlapping.

A z-index of 0 means that the annotation is all the way at the back, while the highest z-index means that the annotation is at the front.

By default, when creating and adding new annotations, the new annotations will be added on top of existing annotations.

Determine the z-index of an annotation

The z-index is not a property on an annotation, but it is defined by the index in the annotations array of a page. To determine the current z-index of an annotation, you need to call AnnotationProvider#getZIndex(Annotation).

Change the z-index of an annotation

There are multiple ways an annotation z-index can be changed, either via the user interface or programmatically with the API.

User interface

The z-index can be changed via the annotation inspector and the annotation list.

You can control whether the z-index editing is enabled in the annotation inspector via the AnnotationConfiguration.Builder#setZIndexEditingEnabled() method. For more information on how to use AnnotationConfiguration objects, see here.

To control whether the z-index reordering is enabled in the annotation list, use PdfActivityConfiguration.Builder#setAnnotationListReorderingEnabled().

Programmatically

You can programmatically move annotations by calling AnnotationProvider#moveAnnotation(), or AnnotationProvider#moveAnnotationAsync() for asynchronous operations. There are three different calls in each variation: one that moves the annotation to the specified position; one where you specify the page index, the current z-index, and where to move the z-index; and the last one, where you specify the annotation and the move action, as defined by the AnnotationZIndexMove object. These are all the methods:

• moveAnnotation(Annotation annotation, int toZIndex)

• moveAnnotationAsync(Annotation annotation, int toZIndex)

• moveAnnotation(int pageIndex, int fromZIndex, int toZIndex)

• moveAnnotationAsync(int pageIndex, int fromZIndex, int toZIndex)

• moveAnnotation(Annotation annotation, AnnotationZIndexMove zIndexMove)

• moveAnnotationAsync(Annotation annotation, AnnotationZIndexMove zIndexMove)

To move an annotation all the way to the back (to z-index 0), you can use the following code snippet:

val annotationProvider = pdfFragment.getDocument().getAnnotationProvider()
val annotation = annotationProvider.getAnnotations(pageIndex)[2]
annotationProvider.moveAnnotationAsync(annotation, 0).subscribe()

AnnotationProvider annotationProvider = pdfFragment.getDocument().getAnnotationProvider();
Annotation annotation = annotationProvider.getAnnotations(pageIndex).get(2);
annotationProvider.moveAnnotationAsync(annotation, 0).subscribe();

Add a new annotation at a specific z-index

When adding a new annotation, you can also specify the z-index it should be inserted at. This can be done with AnnotationProvider#addAnnotationToPage(@NonNull Annotation annotation, int zIndex) and its asynchronous variation, AnnotationProvider#addAnnotationToPageAsync(@NonNull Annotation annotation, int zIndex).

Considerations

When specifying the z-index, either when inserting or moving annotations, it always needs to be less than the number of annotations that will be on the document page (and non-negative).

There are a few annotation types that always float on top of other annotations, since they are not drawn on the PDF page but are overlaid as views, and therefore don’t respect the z-index. These annotations are note, sound, and link annotations.

Selected annotations are always rendered on top, so if you move the selected annotation via the inspector, its current position will be briefly shown after the change.