Custom Note Annotation Hinter Provider

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.Canvas
12
import android.graphics.ColorFilter
13
import android.graphics.Matrix
14
import android.graphics.PixelFormat
15
import android.graphics.PointF
16
import android.graphics.Rect
17
import android.graphics.RectF
18
import android.graphics.drawable.Drawable
19
import android.net.Uri
20
import android.os.Bundle
21
import android.text.TextUtils
22
import androidx.annotation.IntRange
23
import androidx.core.content.ContextCompat
24
import androidx.core.graphics.drawable.DrawableCompat
25
import com.pspdfkit.annotations.Annotation
26
import com.pspdfkit.annotations.AnnotationProvider.OnAnnotationUpdatedListener
27
import com.pspdfkit.annotations.AnnotationType
28
import com.pspdfkit.catalog.R
29
import com.pspdfkit.catalog.SdkExample
30
import com.pspdfkit.catalog.tasks.ExtractAssetTask
31
import com.pspdfkit.catalog.utils.Utils
32
import com.pspdfkit.configuration.activity.PdfActivityConfiguration
33
import com.pspdfkit.document.PdfDocument
34
import com.pspdfkit.ui.PdfActivity
35
import com.pspdfkit.ui.PdfActivityIntentBuilder
36
import com.pspdfkit.ui.drawable.PdfDrawable
37
import com.pspdfkit.ui.drawable.PdfDrawableProvider
38

39
/**
40
 * Shows how to create a custom annotation note hinter extending [PdfDrawableProvider].
41
 */
42
class CustomAnnotationNoteHinterProviderExample(context: Context) : SdkExample(
43
    context,
44
    R.string.customAnnotationNoteHinterProviderExampleTitle,
45
    R.string.customAnnotationNoteHinterProviderExampleDescription
46
) {
47
    override fun launchExample(context: Context, configuration: PdfActivityConfiguration.Builder) {
48
        // Disable default annotation hinter provider.
49
        configuration.setAnnotationNoteHintingEnabled(false)
50

51
        // We use a custom utility class to extract the example document from the assets.
52
        ExtractAssetTask.extract(WELCOME_DOC, title, context) { documentFile ->
53
            // To start the CustomAnnotationNoteHinterProviderActivity create a launch intent using the builder.
54
            val intent = PdfActivityIntentBuilder.fromUri(context, Uri.fromFile(documentFile))
55
                .configuration(configuration.build())
56
                .activityClass(CustomAnnotationNoteHinterProviderActivity::class)
57
                .build()
58

59
            // Start the activity for the extracted document.
60
            context.startActivity(intent)
61
        }
62
    }
63
}
64

65
class CustomAnnotationNoteHinterProviderActivity : PdfActivity() {
66
    override fun onCreate(savedInstanceState: Bundle?) {
67
        super.onCreate(savedInstanceState)
68

69
        val customAnnotationNoteHinter = CustomAnnotationNoteHinter(this)
70

71
        // Inject our custom hinter to the framework.
72
        requirePdfFragment().apply {
73
            // We need to register custom drawable provider so we can provide our custom hint drawables.
74
            addDrawableProvider(customAnnotationNoteHinter)
75

76
            //  We also want to react to annotation updated events in our hinter.
77
            requirePdfFragment().addOnAnnotationUpdatedListener(customAnnotationNoteHinter)
78
        }
79
    }
80
}
81

82
/**
83
 * A custom annotation note hinter provider that works only for ink annotations.
84
 */
85
private class CustomAnnotationNoteHinter(private val pdfActivity: PdfActivity) : PdfDrawableProvider(), OnAnnotationUpdatedListener {
86
    private val noteIcon: Drawable = ContextCompat.getDrawable(pdfActivity, R.drawable.ic_pin_drop)
87
        ?: throw IllegalStateException("Can't retrieve note drawable from resources.")
88

89
    override suspend fun getDrawablesForPage(
90
        context: Context,
91
        document: PdfDocument,
92
        @IntRange(from = 0) pageIndex: Int
93
    ): List<PdfDrawable> {
94
        return document.annotationProvider.getAnnotations(pageIndex)
95
            .asSequence()
96
            .filter { it.type == AnnotationType.INK }
97
            .map { NoteInkHinterDrawable(pdfActivity, noteIcon, it) }
98
            .toList()
99
    }
100

101
    // We notify change to provided drawables whenever any ink annotation changes (is created, updated or removed).
102
    override fun onAnnotationCreated(annotation: Annotation) = notifyDrawablesChangedIfSupported(annotation)
103
    override fun onAnnotationUpdated(annotation: Annotation) = notifyDrawablesChangedIfSupported(annotation)
104
    override fun onAnnotationRemoved(annotation: Annotation) = notifyDrawablesChangedIfSupported(annotation)
105

106
    private fun notifyDrawablesChangedIfSupported(annotation: Annotation) {
107
        if (annotation.type == AnnotationType.INK) {
108
            notifyDrawablesChanged()
109
        }
110
    }
111

112
    // There's no need to update note hinter drawables on Annotation Z-order changes. This method is a no-op.
113
    override fun onAnnotationZOrderChanged(pageIndex: Int, oldOrder: List<Annotation>, newOrder: List<Annotation>) = Unit
114
}
115

116
private class NoteInkHinterDrawable internal constructor(
117
    private val activity: PdfActivity,
118
    private val noteIcon: Drawable,
119
    private val annotation: Annotation
120
) : PdfDrawable() {
121
    private val viewBoundingBoxRounded: Rect = Rect()
122
    private val pdfBoundingBox: RectF = RectF()
123
    private val viewPoint: PointF = PointF()
124
    private val viewBoundingBox: RectF = RectF()
125
    private val widthPx: Int
126
    private val heightPx: Int
127
    private val halfWidthPx: Int
128
    private val halfHeightPx: Int
129

130
    init {
131
        annotation.getBoundingBox(pdfBoundingBox)
132
        widthPx = Utils.dpToPx(activity, 24)
133
        heightPx = Utils.dpToPx(activity, 24)
134
        halfWidthPx = widthPx / 2
135
        halfHeightPx = heightPx / 2
136
    }
137

138
    override fun draw(canvas: Canvas) {
139
        invalidateSelf()
140
        if (TextUtils.isEmpty(annotation.contents)) {
141
            return
142
        }
143
        DrawableCompat.setTint(noteIcon, annotation.color)
144
        noteIcon.bounds = viewBoundingBoxRounded
145
        noteIcon.draw(canvas)
146
    }
147

148
    override fun setAlpha(@IntRange(from = 0, to = 255) alpha: Int) {
149
        noteIcon.alpha = ALPHA
150
    }
151

152
    override fun setColorFilter(colorFilter: ColorFilter?) {
153
        noteIcon.colorFilter = colorFilter
154
    }
155

156
    @Deprecated("Deprecated in Java")
157
    override fun getOpacity(): Int {
158
        return PixelFormat.TRANSLUCENT
159
    }
160

161
    override fun updatePdfToViewTransformation(matrix: Matrix) {
162
        super.updatePdfToViewTransformation(matrix)
163

164
        annotation.getBoundingBox(pdfBoundingBox)
165
        viewPoint.set(pdfBoundingBox.centerX(), pdfBoundingBox.centerY())
166

167
        activity.requirePdfFragment().viewProjection.toViewPoint(viewPoint, annotation.pageIndex)
168

169
        viewBoundingBox.set(
170
            viewPoint.x - halfWidthPx,
171
            viewPoint.y - halfHeightPx,
172
            viewPoint.x + halfWidthPx,
173
            viewPoint.y + halfHeightPx
174
        )
175
        viewBoundingBox.round(viewBoundingBoxRounded)
176
    }
177

178
    companion object {
179
        private const val ALPHA = 255
180
    }
181
}