Z-Index for Annotation Stacking Order on iOS

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. So, to determine the current z-index of an annotation, you need to fetch all annotations for a page and get the index of the annotation in question in the array.

Change 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 get the annotations array for a particular page using Document.annotations(at:) and compare the annotations to the annotations in this array.

User Interface

The z-index can be changed via the annotation inspector and the annotation list. This UI feature can be disabled by setting allowAnnotationZIndexMoves of PDFConfiguration to NO.

Annotation List

The moving of annotations is also supported by reordering them in the annotation list while in edit mode. This can be disabled via the allowAnnotationZIndexMoves property on AnnotationTableViewController. This property is set to the value of PDFConfiguration.allowAnnotationZIndexMoves whenever AnnotationTableViewController is presented from within PSPDFKit.

Inspector

When an annotation supports changing the z-index (when there are at least two annotations on a page), AnnotationStyleViewController shows an Order entry, where the annotation can be moved to the front, one position forward, one position backward, or to the back.

Programmatically

You can programmatically move annotations by calling updateAnnotationsOnPage(at:updates:) on AnnotationManager and using moveAnnotation(atZIndex:toZIndex:) on the AnnotationUpdate object provided in the update block. This will move an annotation at the specified z-index to another z-index.

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

let annotation: Annotation = // Annotation to move.

guard let annotationManager = document.documentProviderForPage(at: annotation.pageIndex)?.annotationManager else { return }

do {
    try annotationManager.updateAnnotationsOnPage(at: annotation.pageIndex) { updater in
        if let currentZIndex = updater.annotations.firstIndex(of: annotation) {
            try updater.moveAnnotation(atZIndex: UInt(currentZIndex), toZIndex: 0)
        }
    }
} catch (let error) {
    // handle error
}

PSPDFAnnotation *annotation = // Annotation to move.

PSPDFAnnotationManager *annotationManager = [document documentProviderForPageAtIndex:annotation.pageIndex].annotationManager;
[annotationManager updateAnnotationsOnPageAtIndex:annotation.pageIndex error:nil withUpdateBlock:^(id<PSPDFAnnotationUpdate> annotationUpdate, NSError **updateError) {
    NSUInteger currentZIndex = [annotationUpdate.annotations indexOfObjectIdenticalTo:annotation];
    return [annotationUpdate moveAnnotationAtZIndex:currentZIndex toZIndex:0 error:**updateError];
}];

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 the insert(_:atZIndex:options:) API on Document.

Considerations

Currently, z-index moving is unsupported when using multiple annotation providers.

Also bear in mind that when specifying the z-index, either when inserting or when moving annotations, it always needs to be less than the number of annotations that will be on the document page.

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 change the z-index of the selected annotation via the inspector, the result will not become apparent before deselecting.

Some annotation types, like stamps, don’t have any editable properties other than the z-index, so we decided not to show the inspector for these annotations. These annotations must be moved using the annotation list.