Annotation Configuration

1
/*
2
 *   Copyright © 2020-2026 PSPDFKit GmbH. All rights reserved.
3
 *
4
 *   The PSPDFKit Sample applications are licensed with a modified BSD license.
5
 *   Please see License for details. This notice may not be removed from this file.
6
 */
7

8
package com.pspdfkit.catalog.examples.kotlin
9

10
import android.content.Context
11
import android.graphics.Color
12
import android.graphics.Typeface
13
import android.net.Uri
14
import androidx.annotation.UiThread
15
import com.pspdfkit.annotations.AnnotationType
16
import com.pspdfkit.annotations.configuration.AnnotationProperty
17
import com.pspdfkit.annotations.configuration.FreeTextAnnotationConfiguration
18
import com.pspdfkit.annotations.configuration.InkAnnotationConfiguration
19
import com.pspdfkit.annotations.configuration.MarkupAnnotationConfiguration
20
import com.pspdfkit.catalog.R
21
import com.pspdfkit.catalog.SdkExample
22
import com.pspdfkit.catalog.tasks.ExtractAssetTask
23
import com.pspdfkit.configuration.activity.PdfActivityConfiguration
24
import com.pspdfkit.document.PdfDocument
25
import com.pspdfkit.ui.PdfActivity
26
import com.pspdfkit.ui.PdfActivityIntentBuilder
27
import com.pspdfkit.ui.PdfFragment
28
import com.pspdfkit.ui.fonts.Font
29
import com.pspdfkit.ui.special_mode.controller.AnnotationTool
30
import com.pspdfkit.ui.special_mode.controller.AnnotationToolVariant
31
import java.util.EnumSet
32

33
/**
34
 * This example shows how to change the annotation configuration in a [PdfActivity] or [PdfFragment].
35
 */
36
class AnnotationConfigurationExample(context: Context) :
37
    SdkExample(context, R.string.annotationConfigurationExampleTitle, R.string.annotationConfigurationExampleDescription) {
38

39
    override fun launchExample(context: Context, configuration: PdfActivityConfiguration.Builder) {
40
        // Extract the example document from the app's assets.
41
        ExtractAssetTask.extract(WELCOME_DOC, title, context) { documentFile ->
42
            // To start the AnnotationConfigurationExampleActivity create a launch intent using the builder.
43
            val intent = PdfActivityIntentBuilder.fromUri(context, Uri.fromFile(documentFile))
44
                .configuration(configuration.build())
45
                .activityClass(AnnotationConfigurationExampleActivity::class)
46
                .build()
47

48
            context.startActivity(intent)
49
        }
50
    }
51
}
52

53
/**
54
 * Annotation configurations can be used to define the default properties of annotations created
55
 * with annotation tools inside a [PdfFragment], as well as the available annotation properties that
56
 * can be modified when creating or editing annotations in the fragment.
57
 *
58
 * The annotation configuration is local to a specific [PdfFragment] instance, and therefore has to
59
 * be configured per [PdfFragment] instance. To change the annotation configuration, it is necessary
60
 * to extend [PdfActivity] and call the approriate APIs on the hosted fragment.
61
 */
62
class AnnotationConfigurationExampleActivity : PdfActivity() {
63

64
    @UiThread
65
    override fun onDocumentLoaded(document: PdfDocument) {
66
        super.onDocumentLoaded(document)
67

68
        // Configurations can be defined for any given annotation type...
69
        configureFreeTextAnnotationType()
70
        // ... or for particular annotation tools and their tool variants.
71
        configureInkTool()
72

73
        // This example shows how to disable the annotation inspector for highlight annotations.
74
        configureHighlightWithNoEditableProperties()
75
    }
76

77
    private fun configureFreeTextAnnotationType() {
78
        // The annotation configuration can be configured through `PdfFragment` for each annotation type.
79
        requirePdfFragment().annotationConfiguration.put(
80
            AnnotationType.FREETEXT,
81
            FreeTextAnnotationConfiguration.builder(this)
82
                // Configure which color is used when creating free-text annotations.
83
                .setDefaultColor(Color.rgb(0, 0, 0))
84
                // Configure which colors are going to be available in the color picker.
85
                .setAvailableColors(
86
                    listOf(
87
                        Color.rgb(255, 255, 255),
88
                        Color.rgb(224, 224, 224),
89
                        Color.rgb(158, 158, 158),
90
                        Color.rgb(66, 66, 66),
91
                        Color.rgb(0, 0, 0)
92
                    )
93
                )
94
                // Configure the custom font to use
95
                .setForceDefaults(true)
96
                .setDefaultFont(Font("Meddon", Typeface.SANS_SERIF))
97
                // Configure the default text size (in pt).
98
                .setDefaultTextSize(24f)
99
                // Only the color property will be editable in the annotation inspector.
100
                .setSupportedProperties(EnumSet.of(AnnotationProperty.COLOR, AnnotationProperty.FONT))
101
                // Disable the annotation preview for free-text annotation.
102
                .setPreviewEnabled(false)
103
                .build()
104
        )
105
    }
106

107
    private fun configureInkTool() {
108
        // In addition to defining configurations per annotation type, you can specify different
109
        // configurations based on the annotation tool that is used to create annotations. For example,
110
        // multiple tools exist that can create ink annotations, such as the `AnnotationTool.INK` or
111
        // the `AnnotationTool.SIGNATURE`, and each of them can have a different configuration which
112
        // defines default properties, and the set of modifiable properties.
113
        requirePdfFragment().annotationConfiguration.put(
114
            AnnotationTool.INK,
115
            InkAnnotationConfiguration.builder(this)
116
                // Configure which color is used when creating ink annotations.
117
                .setDefaultColor(Color.rgb(252, 237, 140))
118
                // Configure which colors are going to be available in the color picker.
119
                .setAvailableColors(
120
                    listOf(
121
                        Color.rgb(244, 67, 54), // RED
122
                        Color.rgb(139, 195, 74), // LIGHT GREEN
123
                        Color.rgb(33, 150, 243), // BLUE
124
                        Color.rgb(252, 237, 140), // YELLOW
125
                        Color.rgb(233, 30, 99) // PINK
126
                    )
127
                )
128
                // Configure thickness picker range and default thickness.
129
                .setDefaultThickness(5f)
130
                .setMinThickness(1f)
131
                .setMaxThickness(20f)
132
                // When `true` attributes like default color are always used as default when
133
                // creating annotations. When `false` last edited value is used, value from
134
                // configuration is used only when creating annotation for the first time.
135
                .setForceDefaults(true)
136
                .setPreviewEnabled(false)
137
                .build()
138
        )
139

140
        // Annotation configuration can be also specified for the annotation tool variant.
141
        requirePdfFragment().annotationConfiguration.put(
142
            AnnotationTool.INK,
143
            AnnotationToolVariant.fromPreset(AnnotationToolVariant.Preset.HIGHLIGHTER),
144
            InkAnnotationConfiguration.builder(this)
145
                // Configure which color is used when creating ink annotations.
146
                .setDefaultColor(Color.rgb(252, 237, 140))
147
                // Configure which colors are going to be available in the color picker.
148
                .setAvailableColors(
149
                    listOf(
150
                        Color.rgb(244, 67, 54), // RED
151
                        Color.rgb(139, 195, 74), // LIGHT GREEN
152
                        Color.rgb(33, 150, 243), // BLUE
153
                        Color.rgb(252, 237, 140), // YELLOW
154
                        Color.rgb(233, 30, 99) // PINK
155
                    )
156
                )
157
                // Configure thickness picker range and default thickness.
158
                .setDefaultThickness(5f)
159
                .setMinThickness(1f)
160
                .setMaxThickness(20f)
161
                .setForceDefaults(true)
162
                .setPreviewEnabled(false)
163
                .build()
164
        )
165
    }
166

167
    /**
168
     * Shows how to disable annotation inspector for highlight annotation.
169
     */
170
    private fun configureHighlightWithNoEditableProperties() {
171
        requirePdfFragment().annotationConfiguration.put(
172
            AnnotationType.HIGHLIGHT,
173
            MarkupAnnotationConfiguration.builder(this, AnnotationType.HIGHLIGHT)
174
                // Makes yellow default highlight color.
175
                .setDefaultColor(Color.rgb(252, 237, 140))
176
                // Configure no supported properties. This disables annotation inspector.
177
                .setSupportedProperties(EnumSet.noneOf(AnnotationProperty::class.java))
178
                .build()
179
        )
180
    }
181
}