Annotation Flags

1
/*
2
 *   Copyright © 2017-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.drawable.Drawable
13
import android.net.Uri
14
import android.util.Log
15
import android.view.ContextMenu
16
import android.view.Menu
17
import android.view.MenuItem
18
import android.view.View
19
import androidx.core.content.ContextCompat
20
import com.pspdfkit.annotations.Annotation
21
import com.pspdfkit.annotations.AnnotationFlags
22
import com.pspdfkit.annotations.AnnotationType
23
import com.pspdfkit.catalog.R
24
import com.pspdfkit.catalog.SdkExample
25
import com.pspdfkit.catalog.tasks.ExtractAssetTask
26
import com.pspdfkit.catalog.ui.CustomAnnotationEditingToolbarGroupingRule
27
import com.pspdfkit.configuration.activity.PdfActivityConfiguration
28
import com.pspdfkit.ui.PdfActivity
29
import com.pspdfkit.ui.PdfActivityIntentBuilder
30
import com.pspdfkit.ui.toolbar.AnnotationEditingToolbar
31
import com.pspdfkit.ui.toolbar.ContextualToolbar
32
import com.pspdfkit.ui.toolbar.ContextualToolbarMenuItem
33
import com.pspdfkit.ui.toolbar.ToolbarCoordinatorLayout
34
import kotlinx.coroutines.CoroutineScope
35
import kotlinx.coroutines.Dispatchers
36
import kotlinx.coroutines.launch
37
import java.util.EnumSet
38

39
/**
40
 * Shows how to use [com.pspdfkit.annotations.AnnotationFlags] to modify annotation
41
 * characteristics.
42
 */
43
class AnnotationFlagsExample(context: Context) :
44
    SdkExample(
45
        context,
46
        R.string.annotationFlagsExampleTitle,
47
        R.string.annotationFlagsExampleDescription,
48
    ) {
49
    override fun launchExample(context: Context, configuration: PdfActivityConfiguration.Builder) {
50
        configuration
51
            // Turn off saving, so we have the clean original document every time the example is
52
            // launched.
53
            .autosaveEnabled(false)
54
            // Notes are treated as if they had the NOZOOM flag set by default.
55
            // We override this behavior here by enabling NOZOOM flag handling for note
56
            // annotations.
57
            .setEnableNoteAnnotationNoZoomHandling(true)
58

59
        // Extract the document from the assets.
60
        ExtractAssetTask.extract(ANNOTATIONS_EXAMPLE, title, context) { documentFile ->
61
            // To start the AnnotationFlagsActivity create a launch intent using the
62
            // builder.
63
            val intent =
64
                PdfActivityIntentBuilder
65
                    .fromUri(context, Uri.fromFile(documentFile))
66
                    .configuration(configuration.build())
67
                    .activityClass(AnnotationFlagsActivity::class.java)
68
                    .build()
69

70
            context.startActivity(intent)
71
        }
72
    }
73
}
74

75
/** This example showcases supported [AnnotationFlags]. */
76
class AnnotationFlagsActivity :
77
    PdfActivity(),
78
    ToolbarCoordinatorLayout.OnContextualToolbarLifecycleListener {
79
    override fun onPause() {
80
        super.onPause()
81
        setOnContextualToolbarLifecycleListener(null)
82
    }
83

84
    override fun onResume() {
85
        super.onResume()
86
        setOnContextualToolbarLifecycleListener(this)
87
    }
88

89
    override fun onCreateOptionsMenu(menu: Menu): Boolean {
90
        super.onCreateOptionsMenu(menu)
91
        menu.add(0, R.id.reset_all_flags, 0, "Reset All Flags")
92
        return true
93
    }
94

95
    override fun onOptionsItemSelected(item: MenuItem): Boolean {
96
        if (item.itemId == R.id.reset_all_flags) {
97
            setFlagsOnAllAnnotations(EnumSet.of(AnnotationFlags.PRINT, AnnotationFlags.NOZOOM))
98
            return true
99
        }
100
        return super.onOptionsItemSelected(item)
101
    }
102

103
    override fun onCreateContextMenu(menu: ContextMenu, v: View, menuInfo: ContextMenu.ContextMenuInfo?) {
104
        super.onCreateContextMenu(menu, v, menuInfo)
105

106
        // In this example we handle only single annotation selection.
107
        val fragment = pdfFragment ?: return
108
        if (fragment.selectedAnnotations.size != 1) return
109
        val annotation = fragment.selectedAnnotations[0]
110

111
        // Populate contextual menu.
112
        menuInflater.inflate(R.menu.flags_example, menu)
113

114
        menu.findItem(R.id.toggle_read_only_flag).title =
115
            if (!annotation.hasFlag(AnnotationFlags.READONLY)) "Enable Read-Only Flag" else "Disable Read-Only Flag"
116

117
        menu.findItem(R.id.toggle_hidden_flag).title =
118
            if (!annotation.hasFlag(AnnotationFlags.HIDDEN)) "Enable Hidden Flag" else "Disable Hidden Flag"
119

120
        menu.findItem(R.id.toggle_print_flag).title =
121
            if (!annotation.hasFlag(AnnotationFlags.PRINT)) "Enable Print Flag" else "Disable Print Flag"
122

123
        menu.findItem(R.id.toggle_no_view_flag).title =
124
            if (!annotation.hasFlag(AnnotationFlags.NOVIEW)) "Enable No-View Flag" else "Disable No-View Flag"
125

126
        menu.findItem(R.id.toggle_locked_flag).title =
127
            if (!annotation.hasFlag(AnnotationFlags.LOCKED)) "Enable Locked Flag" else "Disable Locked Flag"
128

129
        menu.findItem(R.id.toggle_locked_contents_flag).title =
130
            if (!annotation.hasFlag(AnnotationFlags.LOCKEDCONTENTS)) "Enable Locked-Contents Flag" else "Disable Locked-Contents Flag"
131

132
        // No-zoom flag is supported only for Note, File and Stamp, and free-text annotations (but not callouts).
133
        val noZoomMenuItem = menu.findItem(R.id.toggle_no_zoom_flag)
134
        if (annotation.type == AnnotationType.NOTE ||
135
            annotation.type == AnnotationType.FREETEXT ||
136
            annotation.type == AnnotationType.FILE ||
137
            annotation.type == AnnotationType.STAMP
138
        ) {
139
            noZoomMenuItem.isVisible = true
140
            noZoomMenuItem.title =
141
                if (!annotation.hasFlag(AnnotationFlags.NOZOOM)) "Enable No-Zoom Flag" else "Disable No-Zoom Flag"
142
        } else {
143
            noZoomMenuItem.isVisible = false
144
        }
145
    }
146

147
    override fun onContextItemSelected(item: MenuItem): Boolean {
148
        // In this example we handle only single annotation selection.
149
        val fragment = pdfFragment ?: return super.onContextItemSelected(item)
150
        if (fragment.selectedAnnotations.size != 1) return super.onContextItemSelected(item)
151
        val annotation = fragment.selectedAnnotations[0]
152

153
        return when (item.itemId) {
154
            R.id.reset_all_flags -> {
155
                annotation.flags = EnumSet.of(AnnotationFlags.PRINT, AnnotationFlags.NOZOOM)
156
                true
157
            }
158

159
            R.id.toggle_read_only_flag -> {
160
                toggleAnnotationFlag(annotation, AnnotationFlags.READONLY)
161
                true
162
            }
163

164
            R.id.toggle_hidden_flag -> {
165
                toggleAnnotationFlag(annotation, AnnotationFlags.HIDDEN)
166
                true
167
            }
168

169
            R.id.toggle_print_flag -> {
170
                toggleAnnotationFlag(annotation, AnnotationFlags.PRINT)
171
                true
172
            }
173

174
            R.id.toggle_no_view_flag -> {
175
                toggleAnnotationFlag(annotation, AnnotationFlags.NOVIEW)
176
                true
177
            }
178

179
            R.id.toggle_locked_flag -> {
180
                toggleAnnotationFlag(annotation, AnnotationFlags.LOCKED)
181
                true
182
            }
183

184
            R.id.toggle_locked_contents_flag -> {
185
                toggleAnnotationFlag(annotation, AnnotationFlags.LOCKEDCONTENTS)
186
                true
187
            }
188

189
            R.id.toggle_no_zoom_flag -> {
190
                toggleAnnotationFlag(annotation, AnnotationFlags.NOZOOM)
191
                true
192
            }
193

194
            else -> {
195
                super.onContextItemSelected(item)
196
            }
197
        }
198
    }
199

200
    override fun onPrepareContextualToolbar(toolbar: ContextualToolbar<*>) {
201
        // Add item to annotation editing toolbar that will show our context menu for toggling flags
202
        // on selected annotation.
203
        if (toolbar is AnnotationEditingToolbar) {
204
            // In this example we handle only single annotation selection.
205
            val fragment = pdfFragment ?: return
206
            if (fragment.selectedAnnotations.size != 1) return
207

208
            // Set custom grouping rule for our extended editing toolbar.
209
            toolbar.setMenuItemGroupingRule(CustomAnnotationEditingToolbarGroupingRule(this))
210

211
            // Get the existing menu items so we can add our item later.
212
            val menuItems = toolbar.menuItems
213

214
            // Create our custom menu item.
215
            val settingsDrawable: Drawable =
216
                ContextCompat.getDrawable(this, R.drawable.ic_settings)
217
                    ?: return
218
            val customItem =
219
                ContextualToolbarMenuItem.createSingleItem(
220
                    this,
221
                    R.id.pspdf_menu_custom,
222
                    settingsDrawable,
223
                    "Annotation flags",
224
                    Color.MAGENTA,
225
                    Color.CYAN,
226
                    ContextualToolbarMenuItem.Position.END,
227
                    false,
228
                )
229
            // Register it to for context menu.
230
            registerForContextMenu(customItem)
231

232
            // Tell the toolbar about our new item.
233
            menuItems.add(customItem)
234
            toolbar.setMenuItems(menuItems)
235

236
            // Add a listener so we can handle clicking on our item.
237
            toolbar.setOnMenuItemClickListener { _, menuItem ->
238
                if (menuItem.id == R.id.pspdf_menu_custom) {
239
                    menuItem.showContextMenu()
240
                    true
241
                } else {
242
                    false
243
                }
244
            }
245
        }
246
    }
247

248
    override fun onDisplayContextualToolbar(toolbar: ContextualToolbar<*>) {}
249

250
    override fun onRemoveContextualToolbar(toolbar: ContextualToolbar<*>) {}
251

252
    /** Sets/unsets [AnnotationFlags] on single annotation. */
253
    private fun setFlagOnAnnotation(annotation: Annotation, flag: AnnotationFlags, isSet: Boolean) {
254
        val flags = annotation.flags
255
        if (isSet) {
256
            flags.add(flag)
257
        } else {
258
            flags.remove(flag)
259
        }
260
        annotation.flags = flags
261
    }
262

263
    /** Set flags on all annotations in document. */
264
    private fun setFlagsOnAllAnnotations(newFlags: EnumSet<AnnotationFlags>) {
265
        val doc = document ?: return
266

267
        CoroutineScope(Dispatchers.Main).launch {
268
            try {
269
                val annotations =
270
                    doc.annotationProvider.getAllAnnotationsOfType(
271
                        EnumSet.allOf(AnnotationType::class.java),
272
                    )
273
                annotations.forEach { annotation -> annotation.flags = newFlags }
274
            } catch (e: Exception) {
275
                Log.e(LOG_TAG, "Failed to set flags on annotations", e)
276
            }
277
        }
278
    }
279

280
    /** Toggles single annotation flag. */
281
    private fun toggleAnnotationFlag(annotation: Annotation, flag: AnnotationFlags) {
282
        setFlagOnAnnotation(annotation, flag, !annotation.hasFlag(flag))
283
    }
284

285
    companion object {
286
        private const val LOG_TAG = "AnnotationFlagsActivity"
287
    }
288
}