Custom main toolbar actions

1
/*
2
 *   Copyright © 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.content.Intent
12
import android.net.Uri
13
import android.os.Bundle
14
import androidx.activity.compose.BackHandler
15
import androidx.activity.compose.setContent
16
import androidx.appcompat.app.AppCompatActivity
17
import androidx.compose.animation.AnimatedVisibility
18
import androidx.compose.animation.core.animateDpAsState
19
import androidx.compose.animation.core.tween
20
import androidx.compose.animation.fadeIn
21
import androidx.compose.animation.fadeOut
22
import androidx.compose.animation.scaleIn
23
import androidx.compose.animation.scaleOut
24
import androidx.compose.foundation.layout.Box
25
import androidx.compose.foundation.layout.BoxWithConstraints
26
import androidx.compose.foundation.layout.WindowInsets
27
import androidx.compose.foundation.layout.fillMaxSize
28
import androidx.compose.foundation.layout.fillMaxWidth
29
import androidx.compose.foundation.layout.ime
30
import androidx.compose.foundation.layout.padding
31
import androidx.compose.foundation.layout.statusBarsPadding
32
import androidx.compose.foundation.layout.width
33
import androidx.compose.foundation.shape.CircleShape
34
import androidx.compose.foundation.shape.RoundedCornerShape
35
import androidx.compose.material.icons.Icons
36
import androidx.compose.material.icons.filled.Close
37
import androidx.compose.material3.Icon
38
import androidx.compose.material3.MaterialTheme
39
import androidx.compose.material3.Surface
40
import androidx.compose.runtime.Composable
41
import androidx.compose.runtime.LaunchedEffect
42
import androidx.compose.runtime.SideEffect
43
import androidx.compose.runtime.collectAsState
44
import androidx.compose.runtime.getValue
45
import androidx.compose.runtime.mutableIntStateOf
46
import androidx.compose.runtime.mutableStateOf
47
import androidx.compose.runtime.remember
48
import androidx.compose.runtime.saveable.rememberSaveable
49
import androidx.compose.runtime.setValue
50
import androidx.compose.ui.Alignment
51
import androidx.compose.ui.Modifier
52
import androidx.compose.ui.graphics.Color
53
import androidx.compose.ui.platform.LocalDensity
54
import androidx.compose.ui.unit.dp
55
import com.pspdfkit.catalog.R
56
import com.pspdfkit.catalog.SdkExample
57
import com.pspdfkit.catalog.tasks.ExtractAssetTask
58
import com.pspdfkit.catalog.ui.theming.CatalogTheme
59
import com.pspdfkit.catalog.ui.theming.enableConfigurationEdgeToEdge
60
import com.pspdfkit.catalog.ui.theming.isNightTheme
61
import com.pspdfkit.compose.theme.MainToolbarColors
62
import com.pspdfkit.compose.theme.NutrientTheme
63
import com.pspdfkit.compose.theme.ToolbarPopupColors
64
import com.pspdfkit.compose.toolbar.composables.NutrientMainToolbar
65
import com.pspdfkit.compose.toolbar.composables.NutrientMainToolbarDefaults
66
import com.pspdfkit.compose.toolbar.composables.nutrientBackdropSource
67
import com.pspdfkit.compose.toolbar.composables.rememberNutrientBackdropState
68
import com.pspdfkit.compose.toolbar.state.ToolbarIcon
69
import com.pspdfkit.compose.toolbar.state.ToolbarItem
70
import com.pspdfkit.configuration.activity.PdfActivityConfiguration
71
import com.pspdfkit.jetpack.compose.interactors.DocumentState
72
import com.pspdfkit.jetpack.compose.interactors.rememberDocumentState
73
import com.pspdfkit.jetpack.compose.toolbar.NutrientDocumentStatusBarScrim
74
import com.pspdfkit.jetpack.compose.views.DocumentView
75
import com.pspdfkit.utils.getSupportParcelableExtra
76
import kotlinx.coroutines.delay
77
import kotlin.time.Duration.Companion.milliseconds
78

79
/**
80
 * Shows the main-toolbar customization surface in one place:
81
 *
82
 *  1. **Custom toolbar layout** — instead of mounting the toolbar edge-to-edge at the top of the
83
 *     window (the SDK default), the [NutrientMainToolbar] is placed inside a rounded, clipped,
84
 *     elevated [Surface] so it reads as a *floating pill* over the document, with a custom color
85
 *     scheme.
86
 *  2. **Custom toolbar items** — [DocumentState.setToolbarItemsProvider] inserts a custom resize
87
 *     action into the second toolbar slot that toggles the pill between a reduced (200dp) and an
88
 *     extended (300dp) width, with [DocumentState.invalidateToolbarItems] re-running the provider
89
 *     so the action's icon and label follow the current width.
90
 *  3. **Click routing** — [DocumentState.setOnToolbarItemClickListener] handles the custom item
91
 *     by its `R.id` and returns `false` for everything else so the SDK defaults keep working.
92
 *  4. **Companion chrome** — a floating close button sits next to the pill and finishes the
93
 *     example. It scales to its center when hiding, sequences with the search transition (it
94
 *     scales out before the pill expands, and back in only after the pill has collapsed), and
95
 *     follows the toolbar's immersive-mode visibility.
96
 *  5. **Status-bar scrim** — a floating toolbar sits *below* the status bar, so unlike the SDK's
97
 *     own edge-to-edge toolbar it leaves the strip above it showing the scrolling document.
98
 *     [NutrientDocumentStatusBarScrim] blurs and tints that strip, sampling the document through
99
 *     the [nutrientBackdropSource] modifier on [DocumentView].
100
 */
101
class MainToolbarCustomizationExample(context: Context) :
102
    SdkExample(context, R.string.mainToolbarCustomizationExampleTitle, R.string.mainToolbarCustomizationExampleDescription) {
103
    override fun launchExample(context: Context, configuration: PdfActivityConfiguration.Builder) {
104
        ExtractAssetTask.extract(WELCOME_DOC, title, context) { documentFile ->
105
            val intent = Intent(context, MainToolbarCustomizationActivity::class.java)
106
            intent.putExtra(MainToolbarCustomizationActivity.EXTRA_URI, Uri.fromFile(documentFile))
107
            context.startActivity(intent)
108
        }
109
    }
110
}
111

112
class MainToolbarCustomizationActivity : AppCompatActivity() {
113
    override fun onCreate(savedInstanceState: Bundle?) {
114
        super.onCreate(savedInstanceState)
115

116
        val uri = intent.getSupportParcelableExtra(EXTRA_URI, Uri::class.java)!!
117
        val configuration = PdfActivityConfiguration.Builder(this)
118
            .defaultToolbarEnabled(false)
119
            // Keep the floating pill to a single row: don't render the document title overlay
120
            // strip below the toolbar items.
121
            .documentTitleOverlayEnabled(false)
122
            .build()
123

124
        enableConfigurationEdgeToEdge(configuration)
125
        setContent {
126
            CatalogTheme(darkTheme = configuration.isNightTheme) {
127
                FloatingToolbarDocument(uri, configuration, onClose = { finish() })
128
            }
129
        }
130
    }
131

132
    companion object {
133
        const val EXTRA_URI = "MainToolbarCustomizationActivity.DocumentUri"
134
    }
135
}
136

137
@Composable
138
private fun FloatingToolbarDocument(uri: Uri, configuration: PdfActivityConfiguration, onClose: () -> Unit) {
139
    val documentState = rememberDocumentState(uri, configuration)
140

141
    // The floating pill's current width. The custom toolbar item toggles it between the reduced
142
    // and extended widths; the provider below reads it to pick the item's icon and label.
143
    var pillWidthDp by rememberSaveable { mutableIntStateOf(EXTENDED_PILL_WIDTH_DP) }
144

145
    // Customize the toolbar items and route the custom item's clicks. Safe to set before the
146
    // DocumentView attaches — DocumentState applies both once the fragment connects.
147
    LaunchedEffect(documentState) {
148
        documentState.setToolbarItemsProvider { defaultItems -> customizeToolbarItems(defaultItems, pillWidthDp) }
149
        documentState.setOnToolbarItemClickListener { id ->
150
            when (id) {
151
                R.id.custom_action1 -> {
152
                    pillWidthDp = if (pillWidthDp == REDUCED_PILL_WIDTH_DP) EXTENDED_PILL_WIDTH_DP else REDUCED_PILL_WIDTH_DP
153
                    // Re-run the provider so the resize action flips between reduce and extend.
154
                    documentState.invalidateToolbarItems()
155
                    true
156
                }
157

158
                // Everything else keeps the SDK's default handling (search, outline, settings, …).
159
                else -> false
160
            }
161
        }
162
    }
163

164
    // The DocumentView publishes its fragment-scoped toolbar coordinator here once the UI is ready.
165
    // It is null until then, so render the toolbar only once it is non-null.
166
    val coordinator by documentState.toolbarCoordinator.collectAsState()
167

168
    // Shared between the document (which records into it) and the status-bar scrim (which blurs it).
169
    val backdrop = rememberNutrientBackdropState()
170

171
    // True while an overlay view (thumbnail grid / outline / document info) is shown. We use it to
172
    // push that overlay's content below the floating toolbar so it isn't hidden behind the pill.
173
    val overlayViewShown by documentState.viewWithOverlappingToolbarShown.collectAsState()
174
    val toolbarSizePx = documentState.getContextualToolbarSizePx()
175
    SideEffect {
176
        documentState.setContentViewTopPadding(if (overlayViewShown) toolbarSizePx else 0)
177
    }
178

179
    // Let the SDK handle back the layered way: close the contextual toolbar / overlay first.
180
    val imeVisible = WindowInsets.ime.getBottom(LocalDensity.current) > 0
181
    BackHandler(enabled = overlayViewShown && !imeVisible) {
182
        documentState.handleBackPress()
183
    }
184

185
    // No box-wide contentAlignment: by default children sit top-start (top-left). Only the main
186
    // toolbar is explicitly centered below. This keeps the contextual toolbar and any other overlay
187
    // left-aligned at their natural position rather than being pinned to the top-center.
188
    Box(
189
        modifier = Modifier
190
            .fillMaxSize(),
191
    ) {
192
        // The document fills the whole screen and sits *behind* the floating toolbar.
193
        // nutrientBackdropSource records its pixels so the status-bar scrim below can blur them —
194
        // it has to be the first child, because the scrim samples whatever drew before it.
195
        DocumentView(
196
            documentState = documentState,
197
            modifier = Modifier
198
                .fillMaxSize()
199
                .nutrientBackdropSource(backdrop),
200
        )
201

202
        // The pill is offset by statusBarsPadding(), so without this the document scrolls visibly
203
        // under the system clock. This variant works out when to show itself: only with the SDK
204
        // toolbar disabled, only once the page has actually moved up into the strip, and never in
205
        // immersive mode — so zooming out to fit the page takes the scrim away with it.
206
        NutrientDocumentStatusBarScrim(
207
            documentState = documentState,
208
            state = backdrop,
209
            modifier = Modifier.align(Alignment.TopCenter),
210
        )
211

212
        // The floating, rounded, elevated toolbar. Its colors are a parameter below; NutrientTheme
213
        // supplies everything else the SDK pieces read (icons, the XML-derived scheme).
214
        NutrientTheme {
215
            coordinator?.let { c ->
216
                // The inline-search session is registered whenever inline search is enabled; its
217
                // isActive flow flips while the search bar is showing. Expand the pill to full
218
                // width for the search UI and collapse it back afterwards.
219
                val searchSession by c.searchSession.collectAsState()
220
                val searchActive = searchSession?.isActive?.collectAsState()?.value == true
221

222
                // The frame's visibility flips with immersive mode (tap-to-hide chrome) — the same
223
                // flag NutrientMainToolbar animates on. The cross follows it so it hides and shows
224
                // together with the toolbar.
225
                val frame by c.frame.collectAsState()
226

227
                // Sequence the search transition instead of running both animations at once:
228
                // opening search first scales the cross out, *then* expands the pill; closing
229
                // search first collapses the pill, *then* scales the cross back in.
230
                var crossShownForSearch by remember { mutableStateOf(true) }
231
                var pillExpandedForSearch by remember { mutableStateOf(false) }
232
                LaunchedEffect(searchActive) {
233
                    if (searchActive) {
234
                        crossShownForSearch = false
235
                        pillExpandedForSearch = true
236
                    } else {
237
                        pillExpandedForSearch = false
238
                        delay(PILL_WIDTH_ANIMATION_MS.milliseconds)
239
                        crossShownForSearch = true
240
                    }
241
                }
242

243
                BoxWithConstraints(modifier = Modifier.fillMaxWidth()) {
244
                    // Animate the width value itself: animateContentSize only reacts to the
245
                    // *content* measuring differently, so a constraint swap like
246
                    // width(300.dp) ↔ fillMaxWidth snaps instead of animating — which also read
247
                    // as a flicker together with the toolbar's internal row↔search-bar crossfade.
248
                    val pillWidth by animateDpAsState(
249
                        targetValue = if (pillExpandedForSearch) maxWidth else pillWidthDp.dp,
250
                        animationSpec = tween(durationMillis = PILL_WIDTH_ANIMATION_MS),
251
                        label = "pillWidth",
252
                    )
253
                    // The Row is end-aligned, so removing the cross keeps the pill pinned to the
254
                    // end edge and only the row's start edge moves.
255
                    Box(
256
                        modifier = Modifier
257
                            .statusBarsPadding()
258
                            .fillMaxWidth(),
259
                    ) {
260
                        // Scales in/out around its own center (the default transform origin).
261
                        AnimatedVisibility(
262
                            modifier = Modifier.align(Alignment.CenterStart),
263
                            visible = crossShownForSearch && frame.isVisible,
264
                            enter = scaleIn(animationSpec = tween(durationMillis = CROSS_ANIMATION_MS)),
265
                            exit = scaleOut(animationSpec = tween(durationMillis = CROSS_ANIMATION_MS)),
266
                        ) {
267
                            Surface(
268
                                onClick = onClose,
269
                                shape = CircleShape,
270
                                color = MaterialTheme.colorScheme.primary,
271
                                shadowElevation = 8.dp,
272
                                modifier = Modifier.padding(8.dp),
273
                            ) {
274
                                Icon(
275
                                    imageVector = Icons.Default.Close,
276
                                    contentDescription = "Close example",
277
                                    tint = Color.White,
278
                                    modifier = Modifier.padding(10.dp),
279
                                )
280
                            }
281
                        }
282
                        // The pill is the toolbar's own chrome — shape, shadow and colors are
283
                        // parameters — and the animated width is a plain modifier on the
284
                        // toolbar's outermost node. The wrapper already offsets the status bar, so
285
                        // the toolbar reserves no insets of its own.
286
                        NutrientMainToolbar(
287
                            coordinator = c,
288
                            modifier = Modifier
289
                                .align(Alignment.CenterEnd)
290
                                .padding(horizontal = 12.dp, vertical = 8.dp)
291
                                .width(pillWidth),
292
                            shape = RoundedCornerShape(28.dp),
293
                            shadowElevation = 8.dp,
294
                            windowInsets = NutrientMainToolbarDefaults.NoWindowInsets,
295
                            colors = floatingToolbarColors(),
296
                            enter = fadeIn(animationSpec = tween(durationMillis = 300)),
297
                            exit = fadeOut(animationSpec = tween(durationMillis = 300)),
298
                        )
299
                    }
300
                }
301
            }
302
        }
303
    }
304
}
305

306
/** Duration of the pill's width animation (resize action and search expansion). */
307
private const val PILL_WIDTH_ANIMATION_MS = 500
308

309
/** Duration of the close button's scale-to-center show/hide animation. */
310
private const val CROSS_ANIMATION_MS = 300
311

312
/** The pill width the custom resize action shrinks the toolbar to. */
313
private const val REDUCED_PILL_WIDTH_DP = 200
314

315
/** The pill width the custom resize action grows the toolbar back to. */
316
private const val EXTENDED_PILL_WIDTH_DP = 300
317

318
/**
319
 * Builds the customized item list from the SDK defaults: inserts a single custom resize action
320
 * into the second toolbar slot. While the pill is extended the action offers to reduce it to
321
 * [REDUCED_PILL_WIDTH_DP]; while reduced it offers to extend it back to [EXTENDED_PILL_WIDTH_DP].
322
 * The action stays pinned in the row ([ToolbarItem.OverflowBehavior.AlwaysShow]) so it never
323
 * disappears into the overflow menu at the reduced width.
324
 */
325
private fun customizeToolbarItems(defaultItems: List<ToolbarItem>, pillWidthDp: Int): List<ToolbarItem> {
326
    val isReduced = pillWidthDp == REDUCED_PILL_WIDTH_DP
327
    val resizeAction = ToolbarItem.Button(
328
        actionId = "catalog.resize_toolbar",
329
        id = R.id.custom_action1,
330
        contentDescription = if (isReduced) {
331
            "Extend toolbar to ${EXTENDED_PILL_WIDTH_DP}dp"
332
        } else {
333
            "Reduce toolbar to ${REDUCED_PILL_WIDTH_DP}dp"
334
        },
335
        // The pill is pinned to the end of the screen, so extending grows it leftwards and
336
        // reducing shrinks it rightwards — mirror that in the arrow direction.
337
        icon = ToolbarIcon.Resource(
338
            if (isReduced) com.pspdfkit.R.drawable.pspdf__ic_chevron_left else com.pspdfkit.R.drawable.pspdf__ic_chevron_right,
339
        ),
340
        overflowBehavior = ToolbarItem.OverflowBehavior.AlwaysShow,
341
    )
342
    // The SDK bakes the XML theme's action-bar icon tint into every default item, and at render
343
    // time a baked tint wins over the Compose scheme. Strip it so every icon follows
344
    // MainToolbarColors.iconColor from floatingToolbarColors() — otherwise the pill recolors with
345
    // the Material scheme (e.g. on a dark-mode switch) while the default icons keep the XML tint.
346
    return defaultItems.map { it.withUntintedIcon() }.toMutableList().apply { add(1, resizeAction) }
347
}
348

349
/** Returns a copy of the item whose icon has no baked tint, deferring to the Compose scheme. */
350
private fun ToolbarItem.withUntintedIcon(): ToolbarItem {
351
    val untintedIcon = when (val icon = icon) {
352
        is ToolbarIcon.Resource -> icon.copy(tint = null)
353
        is ToolbarIcon.Vector -> icon.copy(tint = null)
354
        else -> icon
355
    }
356
    return when (this) {
357
        is ToolbarItem.Button -> copy(icon = untintedIcon)
358
        is ToolbarItem.Toggle -> copy(icon = untintedIcon)
359
        is ToolbarItem.Submenu -> copy(icon = untintedIcon)
360
    }
361
}
362

363
/**
364
 * The floating toolbar's colors — passed straight to `NutrientMainToolbar(colors = …)`, which
365
 * provides them to its items, title, overflow popup and any slot content. This is the single
366
 * place to re-skin the pill.
367
 */
368
@Composable
369
private fun floatingToolbarColors(): MainToolbarColors {
370
    /** Background color shared by the floating pill and the close button. */
371
    val background = MaterialTheme.colorScheme.primary
372
    return MainToolbarColors(
373
        backgroundColor = background,
374
        textColor = Color.White,
375
        popup = ToolbarPopupColors(backgroundColor = background),
376
        titleTextColor = Color.White,
377
    )
378
}