Replace and Refresh Documents

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.activity.enableEdgeToEdge
17
import androidx.appcompat.app.AppCompatActivity
18
import androidx.compose.animation.AnimatedVisibility
19
import androidx.compose.animation.fadeIn
20
import androidx.compose.animation.fadeOut
21
import androidx.compose.animation.slideInVertically
22
import androidx.compose.animation.slideOutVertically
23
import androidx.compose.foundation.layout.Arrangement
24
import androidx.compose.foundation.layout.Box
25
import androidx.compose.foundation.layout.Row
26
import androidx.compose.foundation.layout.WindowInsets
27
import androidx.compose.foundation.layout.fillMaxSize
28
import androidx.compose.foundation.layout.padding
29
import androidx.compose.foundation.layout.statusBars
30
import androidx.compose.foundation.layout.windowInsetsPadding
31
import androidx.compose.material3.Button
32
import androidx.compose.material3.CircularProgressIndicator
33
import androidx.compose.material3.OutlinedButton
34
import androidx.compose.material3.Text
35
import androidx.compose.runtime.Composable
36
import androidx.compose.runtime.collectAsState
37
import androidx.compose.runtime.getValue
38
import androidx.compose.runtime.mutableStateOf
39
import androidx.compose.runtime.remember
40
import androidx.compose.runtime.setValue
41
import androidx.compose.ui.Alignment
42
import androidx.compose.ui.Modifier
43
import androidx.compose.ui.unit.dp
44
import com.pspdfkit.catalog.R
45
import com.pspdfkit.catalog.SdkExample
46
import com.pspdfkit.catalog.tasks.ExtractAssetTask
47
import com.pspdfkit.catalog.ui.theming.CatalogTheme
48
import com.pspdfkit.configuration.activity.PdfActivityConfiguration
49
import com.pspdfkit.document.DocumentSource
50
import com.pspdfkit.jetpack.compose.interactors.DefaultListeners
51
import com.pspdfkit.jetpack.compose.interactors.DocumentState
52
import com.pspdfkit.jetpack.compose.interactors.getDefaultDocumentManager
53
import com.pspdfkit.jetpack.compose.interactors.rememberDocumentState
54
import com.pspdfkit.jetpack.compose.views.DocumentView
55
import com.pspdfkit.utils.getSupportParcelableExtra
56

57
/**
58
 * Replacing and refreshing the displayed document **without recreating the composable**, through
59
 * [DocumentState.setCustomPdfSource] on a hoisted [DocumentState]. The contract:
60
 *
61
 * - **When it is safe to call:** any time after the [DocumentView] has composed and attached.
62
 *   Calling it before that is a silent no-op (no exception, no log).
63
 * - **The call is asynchronous.** Completion is observed through the `DocumentManager`'s
64
 *   `onDocumentLoaded` callback — it fires again for the new document once loading completes,
65
 *   the same way it does for the initial document.
66
 * - **Preserved:** the underlying fragment, the [PdfActivityConfiguration], and every listener
67
 *   registered through the `DocumentManager`.
68
 * - **Reset:** the zoom resets to 1.0 on every reload. The current page index carries over into
69
 *   the new document as-is; with `restoreLastViewedPage` enabled on the configuration (the
70
 *   default), the incoming document's own last-viewed page can then take over once loading
71
 *   completes.
72
 * - **Guard the page index before replacing:** because the index carries over unguarded,
73
 *   swapping to a document with fewer pages than the current index can crash. Set a valid page
74
 *   first — `documentState.documentConnection.setPageIndex(0)` — before calling
75
 *   [DocumentState.setCustomPdfSource] with a different, potentially shorter document.
76
 * - **Replace vs. refresh:** pass a [DocumentSource] to swap the displayed document; pass
77
 *   `null` to reload the current source (e.g. after its backing file changed on disk).
78
 * - **Keeping the reader's place:** capture [DocumentState.getViewState] before the call and
79
 *   apply [DocumentState.setViewState] from `onDocumentLoaded`. This example keeps one bundle
80
 *   per document, so switching back restores that document's page, zoom, and viewport — a
81
 *   bundle is only ever restored onto the same document it was captured from.
82
 */
83
class CustomPdfSourceExample(context: Context) :
84
    SdkExample(context, R.string.customPdfSourceExampleTitle, R.string.customPdfSourceExampleDescription) {
85
    override fun launchExample(context: Context, configuration: PdfActivityConfiguration.Builder) {
86
        // Extract both documents up front so the swap button has a target ready.
87
        ExtractAssetTask.extract(WELCOME_DOC, title, context) { firstDocument ->
88
            ExtractAssetTask.extract(ANNOTATIONS_EXAMPLE, title, context) { secondDocument ->
89
                val intent = Intent(context, CustomPdfSourceActivity::class.java)
90
                    .putExtra(CustomPdfSourceActivity.EXTRA_FIRST, Uri.fromFile(firstDocument))
91
                    .putExtra(CustomPdfSourceActivity.EXTRA_SECOND, Uri.fromFile(secondDocument))
92
                    // The catalog-prepared configuration carries the catalog theme and the
93
                    // user's preference toggles — pass it through instead of rebuilding.
94
                    .putExtra(CustomPdfSourceActivity.EXTRA_CONFIG, configuration.build())
95
                context.startActivity(intent)
96
            }
97
        }
98
    }
99
}
100

101
class CustomPdfSourceActivity : AppCompatActivity() {
102
    override fun onCreate(savedInstanceState: Bundle?) {
103
        enableEdgeToEdge()
104
        super.onCreate(savedInstanceState)
105
        val first = intent.getSupportParcelableExtra(EXTRA_FIRST, Uri::class.java)!!
106
        val second = intent.getSupportParcelableExtra(EXTRA_SECOND, Uri::class.java)!!
107
        val configuration = intent.getSupportParcelableExtra(EXTRA_CONFIG, PdfActivityConfiguration::class.java)
108

109
        setContent {
110
            CatalogTheme {
111
                CustomPdfSourceDocument(first, second, configuration)
112
            }
113
        }
114
    }
115

116
    companion object {
117
        const val EXTRA_FIRST = "CustomPdfSourceActivity.FirstDocument"
118
        const val EXTRA_SECOND = "CustomPdfSourceActivity.SecondDocument"
119
        const val EXTRA_CONFIG = "CustomPdfSourceActivity.Configuration"
120
    }
121
}
122

123
@Composable
124
private fun CustomPdfSourceDocument(first: Uri, second: Uri, baseConfiguration: PdfActivityConfiguration?) {
125
    val context = androidx.compose.ui.platform.LocalContext.current
126
    val configuration = remember(baseConfiguration) {
127
        // Layer the example's needs on top of the catalog-prepared configuration (theme,
128
        // preference toggles) instead of discarding it.
129
        (baseConfiguration?.let { PdfActivityConfiguration.Builder(it) } ?: PdfActivityConfiguration.Builder(context))
130
            // The buttons below occupy the strip where the document title overlay would render.
131
            .documentTitleOverlayEnabled(false)
132
            .build()
133
    }
134
    // The state is hoisted once with the FIRST document; swapping never recreates it — the
135
    // fragment, configuration, and DocumentManager listeners all survive the source change.
136
    // File-backed documents open through their Uri (native, memory-mapped); a stream-backed
137
    // DataProvider would buffer the whole document onto the Java heap.
138
    val documentState = rememberDocumentState(first, configuration)
139

140
    // Which source is currently requested, and whether a swap/refresh is still loading.
141
    var showingSecond by remember { mutableStateOf(false) }
142
    var isLoading by remember { mutableStateOf(false) }
143
    var loadedDocumentTitle by remember { mutableStateOf<String?>(null) }
144

145
    // Continuity across the swap: each document's view state (page, zoom, viewport) is captured
146
    // when leaving it and re-applied from onDocumentLoaded when returning to it — a bundle is
147
    // only ever restored onto the SAME document it was captured from. A refresh restores the
148
    // state it captured right before the call, so the reader keeps their place.
149
    val savedViewStates = remember { mutableMapOf<Boolean, Bundle?>() }
150
    var pendingViewStateRestore by remember { mutableStateOf<Bundle?>(null) }
151

152
    // The buttons follow the SDK chrome: hidden while the UI is hidden (immersive mode) and
153
    // while any special mode is active (annotation / document / content editing — signaled by a
154
    // non-null contextual toolbar), so they never sit under the top-docked contextual bar or
155
    // distract from an active tool.
156
    var uiVisible by remember { mutableStateOf(true) }
157
    val coordinator by documentState.toolbarCoordinator.collectAsState()
158
    val modeActive = coordinator?.contextualToolbar?.collectAsState()?.value != null
159

160
    Box(Modifier.fillMaxSize()) {
161
        DocumentView(
162
            documentState = documentState,
163
            modifier = Modifier.fillMaxSize(),
164
            documentManager = getDefaultDocumentManager(
165
                documentListener = DefaultListeners.documentListeners(
166
                    // The completion signal for setCustomPdfSource: fires again for the new
167
                    // document once the asynchronous replacement/refresh finishes.
168
                    onDocumentLoaded = { document ->
169
                        isLoading = false
170
                        loadedDocumentTitle = document.title
171
                        // Restore the page, zoom, and viewport captured for THIS document —
172
                        // applied after load so it also wins over restoreLastViewedPage.
173
                        pendingViewStateRestore?.let { documentState.setViewState(it) }
174
                        pendingViewStateRestore = null
175
                    },
176
                ),
177
                uiListener = DefaultListeners.uiListeners(
178
                    onImmersiveModeEnabled = { immersive -> uiVisible = !immersive },
179
                ),
180
            ),
181
        )
182

183
        // Anchored below the SDK main toolbar (status-bar strip + the standard 56dp toolbar
184
        // row) — the bottom edge belongs to the thumbnail bar. Fixed clearance on purpose:
185
        // measuring through the fragment would read 0 before it attaches.
186
        AnimatedVisibility(
187
            visible = uiVisible && !modeActive,
188
            enter = slideInVertically { -it } + fadeIn(),
189
            exit = slideOutVertically { -it } + fadeOut(),
190
            modifier = Modifier
191
                .align(Alignment.TopCenter)
192
                .windowInsetsPadding(WindowInsets.statusBars)
193
                .padding(top = 56.dp + 12.dp),
194
        ) {
195
            SourceButtons(
196
                showingSecond = showingSecond,
197
                isLoading = isLoading,
198
                onSwap = {
199
                    // Capture the leaving document's place FIRST (before the page-index guard
200
                    // below clobbers it), so switching back restores page, zoom, and viewport.
201
                    savedViewStates[showingSecond] = documentState.getViewState()
202
                    // Guard the page index BEFORE replacing: it carries over into the new
203
                    // document unguarded, and a shorter document can crash on an out-of-range
204
                    // index. Page 0 is always valid.
205
                    documentState.documentConnection.setPageIndex(0)
206
                    isLoading = true
207
                    showingSecond = !showingSecond
208
                    // The incoming document's own saved place, if it was visited before.
209
                    pendingViewStateRestore = savedViewStates[showingSecond]
210
                    val target = if (showingSecond) second else first
211
                    // Replace: asynchronous — completion arrives in onDocumentLoaded above.
212
                    documentState.setCustomPdfSource(DocumentSource(target))
213
                },
214
                onRefresh = {
215
                    // Same-document reload: capture now, restore from onDocumentLoaded — the
216
                    // reload alone would reset the zoom to 1.0.
217
                    pendingViewStateRestore = documentState.getViewState()
218
                    isLoading = true
219
                    // Refresh: null reloads the CURRENT source (same completion signal).
220
                    documentState.setCustomPdfSource(null)
221
                },
222
            )
223
        }
224

225
        if (isLoading) {
226
            CircularProgressIndicator(Modifier.align(Alignment.Center))
227
        }
228
    }
229
    // Back unwinds like PdfActivity: while a mode or an overlay view is active, let the SDK
230
    // close it the layered way (contextual toolbar first, then the overlay); only the default
231
    // viewer state lets the system back finish the example. Both gate signals are observable
232
    // flows, so the handler's enabled state never goes stale.
233
    val overlayShown by documentState.viewWithOverlappingToolbarShown.collectAsState()
234
    BackHandler(enabled = modeActive || overlayShown) {
235
        documentState.handleBackPress()
236
    }
237
}
238

239
@Composable
240
private fun SourceButtons(showingSecond: Boolean, isLoading: Boolean, onSwap: () -> Unit, onRefresh: () -> Unit) {
241
    Row(horizontalArrangement = Arrangement.spacedBy(12.dp)) {
242
        Button(enabled = !isLoading, onClick = onSwap) {
243
            Text(if (showingSecond) "Show first document" else "Show second document")
244
        }
245
        OutlinedButton(enabled = !isLoading, onClick = onRefresh) {
246
            Text("Refresh")
247
        }
248
    }
249
}