Dynamic Multimedia Annotation

1
/*
2
 *   Copyright © 2018-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
package com.pspdfkit.catalog.examples.kotlin
8

9
import android.content.Context
10
import android.graphics.RectF
11
import android.net.Uri
12
import androidx.activity.viewModels
13
import com.pspdfkit.annotations.LinkAnnotation
14
import com.pspdfkit.annotations.actions.UriAction
15
import com.pspdfkit.catalog.R
16
import com.pspdfkit.catalog.SdkExample
17
import com.pspdfkit.catalog.tasks.ExtractAssetTask
18
import com.pspdfkit.configuration.activity.PdfActivityConfiguration
19
import com.pspdfkit.document.PdfDocument
20
import com.pspdfkit.ui.PdfActivity
21
import com.pspdfkit.ui.PdfActivityIntentBuilder
22
import org.intellij.lang.annotations.Language
23
import java.io.File
24
import kotlin.getValue
25

26
/** This example showcases how to dynamically add multimedia content to a PDF document.  */
27
class DynamicMultimediaAnnotationExample(context: Context) : SdkExample(context, R.string.dynamicMultimediaExampleTitle, R.string.dynamicMultimediaExampleDescription) {
28
    override fun launchExample(context: Context, configuration: PdfActivityConfiguration.Builder) {
29
        // Before launching the example, we extract one video file to the private app folder. This
30
        // file will be used to dynamically add
31
        // another link annotation to the document at runtime.
32
        ExtractAssetTask.extract("media/videos/small.mp4", title, context, false, "mp4") { videoFile: File? ->
33
            // Next extract the demo document and launch it.
34
            ExtractAssetTask.extract(WELCOME_DOC, title, context) { documentFile: File? ->
35
                // For normal multimedia content playback, it is not necessary to subclass PdfActivity as no custom code is required (only
36
                // annotations using the pspdfkit:// scheme have to be present). However, if you want to dynamically add multimedia annotations
37
                // to a document, it is preferable to do this using a custom activity class (as done by this example).
38
                val intent = PdfActivityIntentBuilder.fromUri(context, Uri.fromFile(documentFile))
39
                    .configuration(configuration.build())
40
                    .activityClass(MultimediaAnnotationsActivity::class.java)
41
                    .build()
42

43
                // Pass the file system path to our video file to the activity. The activity will use the path to dynamically add a multimedia link
44
                // annotation to the PDF for opening the extracted video.
45
                intent.putExtra(MultimediaAnnotationsActivity.EXTRA_VIDEO_PATH, videoFile!!.getAbsolutePath())
46
                context.startActivity(intent)
47
            }
48
        }
49
    }
50
}
51

52
/**
53
 * This activity is part of the [DynamicMultimediaAnnotationExample] and shows how to dynamically add multimedia annotations to a PDF document.
54
 */
55
class MultimediaAnnotationsActivity : PdfActivity() {
56

57
    private val viewModel: AnnotationCreationViewModel by viewModels()
58

59
    companion object {
60
        /** This is the filesystem path of a video file we're going to dynamically add to the PDF document. */
61
        const val EXTRA_VIDEO_PATH = "videoPath"
62
    }
63

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

67
        viewModel.createObjects {
68
            // We add a video link to the first page.
69
            addVideoAnnotation()
70

71
            // We add a gallery link to the second page.
72
            addGalleryAnnotation()
73
        }
74
    }
75

76
    /**
77
     * This method adds a link annotation to a video on the local file system.
78
     */
79
    private fun addVideoAnnotation() {
80
        // Get the rect for the link annotation we want to add. We're using absolute page coordinates here, but your app can use different positioning techniques
81
        // like for example using multimedia position data that you would retrieve from your server. This rect is in the center of the page, so tapping the
82
        // page will trigger the video.
83
        val linkAnnotationRect = RectF(0f, 768f, 768f, 256f)
84

85
        // We're going to place the video on the first page of the document.
86
        val pageIndex = 0
87

88
        // The activity was launched with the path to a video on the local file system. We're going to use this file for playback with the multimedia annotation.
89
        val videoPathUri = intent.getStringExtra(EXTRA_VIDEO_PATH)?.let { Uri.fromFile(File(it)) }
90
            ?: throw IllegalStateException("No string value found for $EXTRA_VIDEO_PATH.")
91

92
        // Create the link annotation. The LinkAnnotation constructor takes the index of the page on which the annotation will be added.
93
        val multimediaLinkAnnotation = LinkAnnotation(pageIndex).apply {
94
            // Set the position of the link annotation on the page.
95
            boundingBox = linkAnnotationRect
96

97
            // To let the link point to the multimedia content, we have to set a UriAction on the link. The UriAction encodes the actual URL of the content.
98
            // The multimedia URL uses the pspdfkit:// URL scheme, has optional options in square brackets, followed by the local file system URI of the file.
99
            // Note the the videoPathUri also carries a file:// scheme which is required for video discovery. For a comprehensive list of supported URI formats
100
            // and options, please consult our Multimedia Annotation online guides at: https://nutrient.io/guides/android/annotations/multimedia-annotations/
101
            action = UriAction("pspdfkit://[autoplay:true]$videoPathUri")
102
        }
103

104
        // Add the annotation to the document and show it.
105
        requirePdfFragment().addAnnotationToPage(multimediaLinkAnnotation, false)
106

107
        // The line above uses the fragment to add the annotation to the document. This will immediately update the rendered page too, making the newly added
108
        // annotation visible. Alternatively, you can use the document's annotation provider, and manually trigger an annotation updated notification on the
109
        // fragment. Like so:
110
        //
111
        //   document.annotationProvider.addAnnotationToPage(multimediaLinkAnnotation)
112
        //   fragment.notifyAnnotationHasChanged(multimediaLinkAnnotation)
113
    }
114

115
    /**
116
     * This method adds a link annotation to a custom gallery on the local file system.
117
     */
118
    private fun addGalleryAnnotation() {
119
        // This example defines a custom JSON content for the gallery. It writes this JSON to a local file and then create an annotation pointing to the file.
120
        // See our online guides at https://nutrient.io/guides/android/annotations/multimedia-annotations/ for a full specification of the JSON format
121
        // used by galleries.
122
        @Language("JSON")
123
        val galleryJson = """
124
            [
125
              {
126
                "contentURL": "https://farm4.staticflickr.com/3701/13630138733_abf2411bd1_z.jpg",
127
                "caption": "This is a local image. Captions are optional"
128
              },
129
              {
130
                "contentURL": "https://farm3.staticflickr.com/2157/3527157206_f3ebec9909_z.jpg",
131
                "caption": "This is a local image. Captions are optional"
132
              }
133
            ]
134
        """.trimIndent()
135

136
        // Write the JSON to a local gallery file on the file system. It is important that the file uses the .gallery file extension so that Nutrient can
137
        // recognize the file for showing a gallery.
138
        val outputFile = filesDir.resolve("sample.gallery").apply {
139
            // For the sake of this example, we recreate the gallery file from scratch. We therefore delete it if it already exists.
140
            if (exists()) delete()
141
            // Write the whole JSON to the output file.
142
            writeText(galleryJson)
143
        }
144

145
        // Get the rect for the link annotation we want to add. We're using absolute page coordinates here. These are the same coordinates used by the video
146
        // annotation created in the method above, but we're adding the gallery to the second page (instead of the first one).
147
        val linkAnnotationRect = RectF(0f, 768f, 768f, 256f)
148

149
        // We're going to place the gallery on the second page of the document.
150
        val pageIndex = 1
151

152
        // Pointing the link to the gallery file is enough for showing the gallery. It is essential that Uri.fromFile() is used, so that the path inside the
153
        // link annotation has the correct format and includes the file:// URL scheme.
154
        val galleryPathUri = Uri.fromFile(outputFile)
155

156
        // Create the link annotation. The LinkAnnotation constructor takes the index of the page on which the annotation will be added.
157
        val galleryLinkAnnotation = LinkAnnotation(pageIndex).apply {
158
            // Set the position of the link annotation on the page.
159
            boundingBox = linkAnnotationRect
160

161
            // To let the link point to the gallery file, we have to set a UriAction on the link. The UriAction encodes the actual URL of the content.
162
            // The multimedia URL uses the pspdfkit:// URL scheme followed by the local file system URI of the file. Galleries don't support multimedia options.
163
            // Note the the galleryPathUri also carries a file:// scheme which is required for gallery discovery. For a comprehensive list of supported URI
164
            // formats, please consult our Multimedia Annotation online guides at: https://nutrient.io/guides/android/annotations/multimedia-annotations/
165
            action = UriAction("pspdfkit://$galleryPathUri")
166
        }
167

168
        // Add the annotation to the document and show it.
169
        pdfFragment?.addAnnotationToPage(galleryLinkAnnotation, false)
170
    }
171
}