Annotation Configuration

Every annotation of a document has properties specific to its type. For example, ink annotations have a color property as well as a line width, whereas note annotations carry an icon property. When creating annotations using any of the annotation tools inside the annotation creation toolbar, newly created annotations will have their properties set to default values.

The configuration for each annotation type is governed by a set of interfaces extending AnnotationConfiguration. Annotation configuration controls allowed values, default values, and whether or not a property is editable. For every annotation type that can be created using the annotation creation toolbar, one such configuration interface exists. For example, configuration for ink annotations is provided by the InkAnnotationConfiguration. An extensive list of supported annotation configuration interfaces can be found below.

Annotation Configuration

Annotation configuration for a specific annotation type extends various property-specific configuration interfaces — one for every annotation property that is supported by the specific annotation type.

Here’s a list of available property configuration interfaces that can be implemented by annotation configuration:

Interface Description
AnnotationAggregationStrategyConfiguration Provides annotation aggregation strategy configuration.
AnnotationAlphaConfiguration Provides alpha configuration.
AnnotationBorderStyleConfiguration Provides border style configuration.
AnnotationColorConfiguration Provides foreground color configuration.
AnnotationFillColorConfiguration Provides fill color configuration.
AnnotationFontConfiguration Provides configuration for free-text annotations font.
AnnotationLineEndsConfiguration Provides line end type configuration.
AnnotationNoteIconConfiguration Provides note annotation icon configuration.
AnnotationOutlineColorConfiguration Provides outline color configuration.
AnnotationOverlayTextConfiguration Provides configuration for overlay text of redaction annotations.
AnnotationPreviewConfiguration Provides configuration regarding the inspector preview.
AnnotationTextSizeConfiguration Provides text size configuration.
AnnotationThicknessConfiguration Provides thickness configuration.

To simplify the implementation of annotation configuration, PSPDFKit ships with ready-to-use builders for all supported annotation types and annotation tools that can be created by factory methods in the corresponding annotation configuration interfaces:

Customizing Annotation Configuration

Annotation configuration can be set for each annotation type or tool via AnnotationConfigurationRegistry#put(). An instance of AnnotationConfigurationRegistry can be retrieved via PdfFragment#getAnnotationConfiguration(). The annotation creation UI (toolbar, inspector, and note editor) first queries configuration for the active annotation tool. If no configuration is set for this annotation tool, the configuration for the underlying annotation type (retrieved via AnnotationTool#toAnnotationType()) is used. The annotation editing toolbar always uses configuration for the selected annotation type.

For example, this is how you override configuration for ink annotations:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
override fun onDocumentLoaded(document: PdfDocument) {
    ...
    pdfFragment?.annotationConfiguration.put(
        AnnotationType.INK,
        InkAnnotationConfiguration.builder(context)
            // Here you can specify which color is used when creating ink annotations.
            .setDefaultColor(Color.rgb(252, 237, 140))
            // Here you can specify which colors are going to be available in the color picker.
            .setAvailableColors(
                Arrays.asList(
                    Color.rgb(244, 67, 54), // RED
                    Color.rgb(139, 195, 74), // LIGHT GREEN
                    Color.rgb(33, 150, 243), // BLUE
                    Color.rgb(252, 237, 140), // YELLOW
                    Color.rgb(233, 30, 99) // PINK
                )
            )

            // Here you can modify the thickness picker range and default thickness.
            .setDefaultThickness(5)
            .setMinThickness(1)
            .setMaxThickness(20)

            // When `true`, attributes like the default color are always used as the default when creating annotations.
            // When `false`, the last edited value is used. The value from configuration is used only when creating an annotation for the first time.
            .setForceDefaults(true)

            // Build the configuration.
            .build()
    )
}
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
@Override
public void onDocumentLoaded(@NonNull PdfDocument document) {
    ...
    getPdfFragment().getAnnotationConfiguration().put(
        AnnotationType.INK,
        InkAnnotationConfiguration.builder(this)
            // Here you can specify which color is used when creating ink annotations.
            .setDefaultColor(Color.rgb(252, 237, 140))
            // Here you can specify which colors are going to be available in the color picker.
            .setAvailableColors(
                Arrays.asList(
                    Color.rgb(244, 67, 54), // RED
                    Color.rgb(139, 195, 74), // LIGHT GREEN
                    Color.rgb(33, 150, 243), // BLUE
                    Color.rgb(252, 237, 140), // YELLOW
                    Color.rgb(233, 30, 99) // PINK
                )
            )

            // Here you can modify the thickness picker range and default thickness.
            .setDefaultThickness(5)
            .setMinThickness(1)
            .setMaxThickness(20)

           // When `true`, attributes like the default color are always used as the default when creating annotations.
           // When `false`, the last edited value is used. The value from configuration is used only when creating an annotation for the first time.
            .setForceDefaults(true)

            // Build the configuration.
            .build()
    );
}

For a complete example of how to customize annotation configuration, see AnnotationConfigurationExample inside the Catalog app.

Disabling Annotation Properties

To remove a certain property from all annotation types that support it, disable the property in annotation configuration for all annotation types.

For example, to disable the annotation note option in the annotation editing toolbar, the ANNOTATION_NOTE property must be removed from the annotation configuration of all types that support annotation notes:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
override fun onDocumentLoaded(document: PdfDocument) {
    ...
    val annotationConfigurationRegistry = pdfFragment.annotationConfiguration

    val annotationTypesWithNotes = listOf(
        AnnotationType.INK,
        AnnotationType.LINE,
        AnnotationType.POLYLINE,
        AnnotationType.SQUARE,
        AnnotationType.CIRCLE,
        AnnotationType.POLYGON,
        AnnotationType.FREETEXT,
        AnnotationType.UNDERLINE,
        AnnotationType.SQUIGGLY,
        AnnotationType.STRIKEOUT,
        AnnotationType.HIGHLIGHT,
        AnnotationType.STAMP,
        AnnotationType.FILE,
        AnnotationType.REDACT)

    // We'll disable the `ANNOTATION_NOTE` property for every annotation type that supports notes.
    for (annotationType in annotationTypesWithNotes) {
        annotationConfigurationRegistry.put(
            annotationType,
            AnnotationConfiguration.builder(this, annotationType)
                .disableProperty(AnnotationProperty.ANNOTATION_NOTE)
                .build())
    }
    ...
}
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
@Override
public void onDocumentLoaded(@NonNull PdfDocument document) {
    ...
    AnnotationConfigurationRegistry annotationConfigurationRegistry = getPdfFragment().getAnnotationConfiguration();

    List<AnnotationType> annotationTypesWithNotes = Arrays.asList(
        AnnotationType.INK,
        AnnotationType.LINE,
        AnnotationType.POLYLINE,
        AnnotationType.SQUARE,
        AnnotationType.CIRCLE,
        AnnotationType.POLYGON,
        AnnotationType.FREETEXT,
        AnnotationType.UNDERLINE,
        AnnotationType.SQUIGGLY,
        AnnotationType.STRIKEOUT,
        AnnotationType.HIGHLIGHT,
        AnnotationType.STAMP,
        AnnotationType.FILE,
        AnnotationType.REDACT);

    // We'll disable the `ANNOTATION_NOTE` property for every annotation type that supports notes.
    for (AnnotationType annotationType : annotationTypesWithNotes) {
        annotationConfigurationRegistry.put(
            annotationType,
            AnnotationConfiguration.builder(this, annotationType)
                .disableProperty(AnnotationProperty.ANNOTATION_NOTE)
                .build());
    }
    ...
}

Ink Aggregation Strategy

By default, ink drawing is automatically split into annotations based on the timing of strokes and the distance between drawn points. This feature can be controlled via AnnotationAggregationStrategyConfiguration, which is currently supported for ink annotations.

If you want to have ink strokes merged into a single annotation instead, change the default aggregation strategy to AnnotationAggregationStrategy#MERGE_IF_POSSIBLE. This will aggregate all compatible ink strokes into a single annotation, i.e. strokes that have the same color, thickness, and alpha value:

Copy
1
2
3
4
5
6
7
8
pdfFragment?.annotationConfiguration.put(
    AnnotationType.INK,
    InkAnnotationConfiguration.builder(context)
        // PSPDFKit 5.3+ defaults to `AUTOMATIC`.
        // `MERGE_IF_POSSIBLE` matches the older version's behavior.
        .setAnnotationAggregationStrategy(AnnotationAggregationStrategy.MERGE_IF_POSSIBLE)
        .build()
)
Copy
1
2
3
4
5
6
7
8
getPdfFragment().getAnnotationConfiguration().put(
    AnnotationType.INK,
    InkAnnotationConfiguration.builder(this)
        // PSPDFKit 5.3+ defaults to `AUTOMATIC`.
        // `MERGE_IF_POSSIBLE` matches the older version's behavior.
        .setAnnotationAggregationStrategy(AnnotationAggregationStrategy.MERGE_IF_POSSIBLE)
        .build()
);