Annotation Toolbar: Item Grouping

1
/*
2
 *   Copyright © 2016-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
@file:Suppress("DEPRECATION")
8

9
package com.pspdfkit.catalog.examples.java
10

11
import android.content.Context
12
import android.net.Uri
13
import android.os.Bundle
14
import android.util.Log
15
import android.widget.Toast
16
import com.pspdfkit.catalog.R
17
import com.pspdfkit.catalog.SdkExample
18
import com.pspdfkit.catalog.tasks.ExtractAssetTask
19
import com.pspdfkit.catalog.ui.CustomAnnotationCreationToolbarGroupingRule
20
import com.pspdfkit.compose.toolbar.adapter.ToolbarSubscription
21
import com.pspdfkit.compose.toolbar.state.ContextualToolbarKind
22
import com.pspdfkit.compose.toolbar.state.ToolbarAction
23
import com.pspdfkit.compose.toolbar.state.ToolbarIcon
24
import com.pspdfkit.compose.toolbar.state.ToolbarItem
25
import com.pspdfkit.configuration.activity.PdfActivityConfiguration
26
import com.pspdfkit.jetpack.compose.toolbar.nutrientToolbarCoordinator
27
import com.pspdfkit.jetpack.compose.toolbar.setMenuItemGroupingRule
28
import com.pspdfkit.ui.PdfActivity
29
import com.pspdfkit.ui.PdfActivityIntentBuilder
30
import kotlinx.collections.immutable.mutate
31

32
/**
33
 * Example of how to alter contextual toolbar menu items structure. Displayed on the annotation
34
 * creation toolbar.
35
 */
36
class AnnotationToolbarGroupingExample(context: Context) :
37
    SdkExample(
38
        context,
39
        R.string.annotationToolbarGroupingExampleTitle,
40
        R.string.annotationToolbarGroupingExampleDescription,
41
    ) {
42

43
    override fun launchExample(context: Context, configuration: PdfActivityConfiguration.Builder) {
44
        // We use a custom utility class to extract the example document from the assets.
45
        ExtractAssetTask.extract(WELCOME_DOC, title, context) { documentFile ->
46
            val intent = PdfActivityIntentBuilder.fromUri(context, Uri.fromFile(documentFile))
47
                .configuration(configuration.build())
48
                .activityClass(AnnotationToolbarGroupingActivity::class.java)
49
                .build()
50
            context.startActivity(intent)
51
        }
52
    }
53

54
    /**
55
     * This example shows how to add items to the annotation creation toolbar and apply a custom
56
     * grouping rule. See [CustomAnnotationCreationToolbarGroupingRule] for the applied grouping.
57
     */
58
    class AnnotationToolbarGroupingActivity : PdfActivity() {
59

60
        /** Click subscription on the toolbar coordinator; closed in [onDestroy]. */
61
        private var actionSubscription: ToolbarSubscription? = null
62

63
        /** Contextual-toolbar state subscription; closed in [onDestroy]. */
64
        private var changeSubscription: ToolbarSubscription? = null
65

66
        override fun onCreate(savedInstanceState: Bundle?) {
67
            super.onCreate(savedInstanceState)
68

69
            // The activity-scoped toolbar coordinator is the state container PdfActivity's Compose
70
            // toolbars run on — customizing the contextual (annotation) toolbar goes through it.
71
            val coordinator = nutrientToolbarCoordinator()
72

73
            // Register the grouping rule that tells the toolbar how to group its menu items. This
74
            // uses the deprecated MenuItemGroupingRule bridge so existing
75
            // PresetMenuItemGroupingRule subclasses keep working; new code should implement
76
            // ContextualToolbarGroupingProvider and register it with
77
            // coordinator.setContextualToolbarGroupingProvider(...) instead.
78
            coordinator.setMenuItemGroupingRule(this, CustomAnnotationCreationToolbarGroupingRule(this))
79

80
            // The SDK rebuilds the annotation toolbar's item list every time the mode is entered,
81
            // so we observe the contextual toolbar state and (re-)apply our customizations on
82
            // every show. This replaces the legacy onPrepareContextualToolbar hook for the
83
            // annotation toolbar. The change listener needs no coroutine scope — it fires
84
            // synchronously on registration (with the current state) and on every change; a
85
            // View-based host just closes the subscription in onDestroy.
86
            changeSubscription = coordinator.addContextualToolbarChangeListener { state ->
87
                // The state carries which bar is shown and where it is docked; null means no
88
                // contextual toolbar is visible.
89
                Log.i(LOG_TAG, "Contextual toolbar changed: kind=${state?.kind} position=${state?.position}")
90
                if (state?.kind != ContextualToolbarKind.Annotation) {
91
                    return@addContextualToolbarChangeListener
92
                }
93

94
                // Append our custom "Bookmark" item — guarded so state updates after the
95
                // initial show (e.g. our own edit below) don't add it twice.
96
                if (state.items.none { it.id == R.id.pspdf_menu_custom }) {
97
                    coordinator.updateContextualItems { items ->
98
                        items.add(
99
                            ToolbarItem.Button(
100
                                actionId = "catalog.custom_bookmark",
101
                                id = R.id.pspdf_menu_custom,
102
                                contentDescription = "Bookmark",
103
                                icon = ToolbarIcon.Resource(R.drawable.ic_bookmark),
104
                                position = ToolbarItem.ItemEdge.Start,
105
                            ),
106
                        )
107
                    }
108
                }
109

110
                // The Compose counterpart of the legacy ContextualToolbar.setDraggable(false):
111
                // hides the drag handle and pins the toolbar to its current position.
112
                coordinator.setContextualToolbarDraggable(false)
113

114
                // Note: the legacy setUseBackButtonForCloseWhenHorizontal behavior is built in —
115
                // a top-docked bar leads with a back arrow, a side-docked one shows the circled
116
                // X. AnnotationToolbar.setShouldShowStylusButton(false) has no Compose
117
                // equivalent: the stylus toggle appears automatically while a stylus is
118
                // connected.
119
            }
120

121
            // Handle clicks on our custom item. Group taps and submenu child taps arrive as
122
            // SubmenuChildClicked, direct item taps as ItemClicked — our grouping rule keeps the
123
            // item standalone, but matching both is the robust pattern.
124
            actionSubscription = coordinator.addActionListener { action ->
125
                val clickedId = when (action) {
126
                    is ToolbarAction.ItemClicked -> action.id
127
                    is ToolbarAction.SubmenuChildClicked -> action.childId
128
                    else -> null
129
                }
130
                if (clickedId == R.id.pspdf_menu_custom) {
131
                    Toast.makeText(this, "Custom Action clicked", Toast.LENGTH_SHORT).show()
132

133
                    // You can even hide menu items. This shows how to toggle the image menu item
134
                    // by clicking on the custom button. Hidden items keep their slot logic but are
135
                    // removed from the row, like View.GONE on the legacy toolbar.
136
                    coordinator.updateContextualItems { items ->
137
                        items.mutate { list ->
138
                            val index = list.indexOfFirst { it.id == com.pspdfkit.R.id.pspdf__annotation_toolbar_item_image }
139
                            if (index != -1) {
140
                                val item = list[index]
141
                                list[index] = item.withVisible(!item.state.isVisible)
142
                            }
143
                        }
144
                    }
145
                }
146
            }
147
        }
148

149
        private companion object {
150
            const val LOG_TAG = "CustomToolbarGrouping"
151
        }
152

153
        override fun onDestroy() {
154
            super.onDestroy()
155
            actionSubscription?.close()
156
            changeSubscription?.close()
157
            actionSubscription = null
158
        }
159

160
        /** Returns a copy of the item with [ToolbarItem.state]'s visibility flipped to [visible]. */
161
        private fun ToolbarItem.withVisible(visible: Boolean): ToolbarItem = when (this) {
162
            is ToolbarItem.Button -> copy(state = state.copy(isVisible = visible))
163
            is ToolbarItem.Toggle -> copy(state = state.copy(isVisible = visible))
164
            is ToolbarItem.Submenu -> copy(state = state.copy(isVisible = visible))
165
        }
166
    }
167
}