Custom Settings, Info and Outline UI

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.net.Uri
12
import android.os.Bundle
13
import android.view.ViewGroup
14
import android.widget.Toast
15
import androidx.compose.foundation.clickable
16
import androidx.compose.foundation.layout.Arrangement
17
import androidx.compose.foundation.layout.Column
18
import androidx.compose.foundation.layout.Row
19
import androidx.compose.foundation.layout.fillMaxWidth
20
import androidx.compose.foundation.layout.padding
21
import androidx.compose.foundation.rememberScrollState
22
import androidx.compose.foundation.verticalScroll
23
import androidx.compose.material3.Button
24
import androidx.compose.material3.ExperimentalMaterial3Api
25
import androidx.compose.material3.HorizontalDivider
26
import androidx.compose.material3.MaterialTheme
27
import androidx.compose.material3.ModalBottomSheet
28
import androidx.compose.material3.OutlinedTextField
29
import androidx.compose.material3.PrimaryTabRow
30
import androidx.compose.material3.SegmentedButton
31
import androidx.compose.material3.SegmentedButtonDefaults
32
import androidx.compose.material3.SingleChoiceSegmentedButtonRow
33
import androidx.compose.material3.Switch
34
import androidx.compose.material3.Tab
35
import androidx.compose.material3.Text
36
import androidx.compose.material3.TextButton
37
import androidx.compose.material3.rememberModalBottomSheetState
38
import androidx.compose.runtime.Composable
39
import androidx.compose.runtime.getValue
40
import androidx.compose.runtime.mutableStateOf
41
import androidx.compose.runtime.remember
42
import androidx.compose.runtime.setValue
43
import androidx.compose.ui.Alignment
44
import androidx.compose.ui.Modifier
45
import androidx.compose.ui.platform.ComposeView
46
import androidx.compose.ui.text.style.TextAlign
47
import androidx.compose.ui.unit.dp
48
import androidx.lifecycle.lifecycleScope
49
import com.pspdfkit.annotations.actions.GoToAction
50
import com.pspdfkit.catalog.R
51
import com.pspdfkit.catalog.SdkExample
52
import com.pspdfkit.catalog.tasks.ExtractAssetTask
53
import com.pspdfkit.configuration.activity.PdfActivityConfiguration
54
import com.pspdfkit.configuration.page.PageLayoutMode
55
import com.pspdfkit.configuration.page.PageScrollDirection
56
import com.pspdfkit.configuration.page.PageScrollMode
57
import com.pspdfkit.configuration.theming.ThemeMode
58
import com.pspdfkit.document.OutlineElement
59
import com.pspdfkit.document.PageBinding
60
import com.pspdfkit.document.PdfDocument
61
import com.pspdfkit.preferences.PSPDFKitPreferences
62
import com.pspdfkit.ui.PdfActivity
63
import com.pspdfkit.ui.PdfActivityIntentBuilder
64
import io.nutrient.ui.settings.SettingsOptions
65
import io.nutrient.ui.settings.TIMEOUT_DEFAULT
66
import io.nutrient.ui.settings.TIMEOUT_INFINITE
67
import kotlinx.coroutines.Dispatchers
68
import kotlinx.coroutines.launch
69
import kotlinx.coroutines.withContext
70
import java.text.DateFormat
71

72
/**
73
 * Shows how to replace the SDK's settings, document info and outline UI with your own, driven by the
74
 * SDK's own data.
75
 *
76
 * Everything here uses public API. No SDK class had to be moved or made public. Each of the three
77
 * screens is a view over data you can already reach:
78
 *
79
 * - Settings is a view over the active [PdfActivityConfiguration], [PdfActivity.getScreenTimeout]
80
 *   and [PSPDFKitPreferences]. [SettingsOptions] is public and works as the carrier.
81
 * - Document info is a view over [PdfDocument.getPdfMetadata], [PdfDocument.getPageBinding] and a
82
 *   few document properties. Every metadata getter is nullable, so read them defensively.
83
 * - The outline is a view over [PdfDocument.getOutlineAsync], which emits public [OutlineElement]s.
84
 *
85
 * The toolbar items are intercepted with `setOnToolbarItemClickListener`, which the SDK consults
86
 * before its own default action. Returning `true` suppresses the built-in screen and leaves the
87
 * toolbar untouched, so there is no need to disable items and add your own.
88
 */
89
class CustomSdkUiExample(context: Context) :
90
    SdkExample(context, R.string.customSdkUiExampleTitle, R.string.customSdkUiExampleDescription) {
91
    override fun launchExample(context: Context, configuration: PdfActivityConfiguration.Builder) {
92
        ExtractAssetTask.extract(WELCOME_DOC, title, context) { documentFile ->
93
            val intent = PdfActivityIntentBuilder
94
                .fromUri(context, Uri.fromFile(documentFile))
95
                .configuration(configuration.build())
96
                .activityClass(CustomSdkUiActivity::class)
97
                .build()
98
            context.startActivity(intent)
99
        }
100
    }
101
}
102

103
/** Which of our own panes is showing. */
104
private enum class CustomPane(val label: String) {
105
    Settings("Settings"),
106
    DocumentInfo("Document info"),
107
    Outline("Outline"),
108
}
109

110
/** The editable and read-only values our document info pane shows. */
111
data class CustomDocumentInfo(
112
    val title: String,
113
    val author: String,
114
    val subject: String,
115
    val keywords: String,
116
    val pageBinding: PageBinding,
117
    val isEditable: Boolean,
118
    val readOnlyRows: List<Pair<String, String>>,
119
)
120

121
/** One outline row, flattened out of the [OutlineElement] tree so it can be shown as a list. */
122
data class CustomOutlineRow(val title: String, val depth: Int, val pageLabel: String?, val pageIndex: Int?)
123

124
/**
125
 * A [PdfActivity] that keeps the standard settings, document info and outline toolbar items but
126
 * opens its own UI for each of them.
127
 */
128
class CustomSdkUiActivity : PdfActivity() {
129
    private var pane by mutableStateOf<CustomPane?>(null)
130
    private var outlineRows by mutableStateOf<List<CustomOutlineRow>>(emptyList())
131

132
    override fun onCreate(savedInstanceState: Bundle?) {
133
        super.onCreate(savedInstanceState)
134

135
        setOnToolbarItemClickListener { id ->
136
            when (id) {
137
                MENU_OPTION_SETTINGS -> {
138
                    pane = CustomPane.Settings
139
                    true
140
                }
141

142
                MENU_OPTION_DOCUMENT_INFO -> {
143
                    pane = CustomPane.DocumentInfo
144
                    true
145
                }
146

147
                MENU_OPTION_OUTLINE -> {
148
                    loadOutline()
149
                    pane = CustomPane.Outline
150
                    true
151
                }
152

153
                else -> false
154
            }
155
        }
156

157
        // Host our own Compose UI above the document. The activity is the lifecycle owner, so a
158
        // ComposeView added to the content view needs no further wiring.
159
        val content = findViewById<ViewGroup>(android.R.id.content)
160
        content.addView(
161
            ComposeView(this).apply {
162
                setContent {
163
                    MaterialTheme {
164
                        val current = pane
165
                        if (current != null) {
166
                            CustomSdkUiSheet(
167
                                initialPane = current,
168
                                settings = readSettings(),
169
                                documentInfo = document?.let(::readDocumentInfo),
170
                                outlineRows = outlineRows,
171
                                onDismiss = { pane = null },
172
                                onApplySettings = { changed ->
173
                                    pane = null
174
                                    applySettings(changed)
175
                                },
176
                                onSaveDocumentInfo = { edited ->
177
                                    pane = null
178
                                    saveDocumentInfo(edited)
179
                                },
180
                                onOutlineRowClick = { row ->
181
                                    pane = null
182
                                    row.pageIndex?.let { setPageIndex(it) }
183
                                },
184
                            )
185
                        }
186
                    }
187
                }
188
            },
189
        )
190
    }
191

192
    // Settings -------------------------------------------------------------------------------
193

194
    /** Reads the values the SDK's own settings dialog is opened with. */
195
    private fun readSettings(): SettingsOptions {
196
        val pdfConfiguration = configuration.configuration
197
        return SettingsOptions(
198
            scrollDirection = pdfConfiguration.scrollDirection,
199
            scrollMode = pdfConfiguration.scrollMode,
200
            layoutMode = pdfConfiguration.layoutMode,
201
            themeMode = pdfConfiguration.themeMode,
202
            screenTimeoutMillis = screenTimeout,
203
            visibleItems = configuration.settingsMenuItemShown,
204
            sepia = pdfConfiguration.isSepia,
205
        )
206
    }
207

208
    /** Applies changed settings back. */
209
    private fun applySettings(changed: SettingsOptions) {
210
        val preferences = PSPDFKitPreferences.get(this)
211
        screenTimeout = changed.screenTimeoutMillis
212

213
        // PdfConfiguration is a data class, so copy() is the supported way to derive one.
214
        // PdfConfiguration.Builder(existingConfiguration) is deprecated in favour of it.
215
        val pdfConfiguration = configuration.configuration.copy(
216
            scrollDirection = changed.scrollDirection,
217
            scrollMode = changed.scrollMode,
218
            layoutMode = changed.layoutMode,
219
            isSepia = changed.sepia,
220
        )
221

222
        // Changing the configuration recreates the document view, so do this last.
223
        configuration = PdfActivityConfiguration.Builder(configuration)
224
            .configuration(pdfConfiguration)
225
            .themeMode(changed.themeMode)
226
            .build()
227
    }
228

229
    // Document info --------------------------------------------------------------------------
230

231
    /** Reads the values the SDK's own document info screen shows. */
232
    private fun readDocumentInfo(document: PdfDocument): CustomDocumentInfo {
233
        val metadata = document.pdfMetadata
234
        val dateFormat = DateFormat.getDateTimeInstance(DateFormat.MEDIUM, DateFormat.SHORT)
235
        return CustomDocumentInfo(
236
            title = metadata.title ?: "",
237
            author = metadata.author ?: "",
238
            subject = metadata.subject ?: "",
239
            keywords = metadata.keywords?.joinToString(", ") ?: "",
240
            pageBinding = document.pageBinding,
241
            // A document that cannot be saved is shown, but not offered for editing.
242
            isEditable = document.isWritableAndCanSave,
243
            readOnlyRows = listOfNotNull(
244
                "Pages" to document.pageCount.toString(),
245
                metadata.producer?.let { "PDF producer" to it },
246
                metadata.creator?.let { "Content creator" to it },
247
                metadata.creationDate?.let { "Created" to dateFormat.format(it) },
248
                metadata.modificationDate?.let { "Modified" to dateFormat.format(it) },
249
            ),
250
        )
251
    }
252

253
    /**
254
     * Writes the edited values back and saves. [PdfDocument.saveIfModified] does disk work and can
255
     * throw, so it belongs off the main thread.
256
     */
257
    private fun saveDocumentInfo(edited: CustomDocumentInfo) {
258
        val document = document ?: return
259
        val metadata = document.pdfMetadata
260
        metadata.title = edited.title.ifBlank { null }
261
        metadata.author = edited.author.ifBlank { null }
262
        metadata.subject = edited.subject.ifBlank { null }
263
        metadata.keywords = edited.keywords
264
            .split(',')
265
            .map { it.trim() }
266
            .filter { it.isNotEmpty() }
267
            .ifEmpty { null }
268
        document.pageBinding = edited.pageBinding
269

270
        lifecycleScope.launch {
271
            val message = try {
272
                if (withContext(Dispatchers.IO) { document.saveIfModified() }) {
273
                    "Document info saved"
274
                } else {
275
                    "Nothing to save"
276
                }
277
            } catch (e: Exception) {
278
                "Could not save: ${e.message}"
279
            }
280
            Toast.makeText(this@CustomSdkUiActivity, message, Toast.LENGTH_SHORT).show()
281
        }
282
    }
283

284
    // Outline --------------------------------------------------------------------------------
285

286
    /**
287
     * Reads the document outline. getOutlineAsync is used rather than getOutline because the
288
     * blocking form must not be called on the main thread.
289
     */
290
    private fun loadOutline() {
291
        val document = document ?: return
292
        lifecycleScope.launch {
293
            outlineRows = try {
294
                val elements = withContext(Dispatchers.IO) { document.outlineAsync.blockingGet() }
295
                elements.flatten(depth = 0)
296
            } catch (e: Exception) {
297
                Toast.makeText(this@CustomSdkUiActivity, "Could not read the outline: ${e.message}", Toast.LENGTH_SHORT)
298
                    .show()
299
                emptyList()
300
            }
301
        }
302
    }
303

304
    /** Flattens the outline tree into indented rows. */
305
    private fun List<OutlineElement>.flatten(depth: Int): List<CustomOutlineRow> = flatMap { element ->
306
        listOf(
307
            CustomOutlineRow(
308
                title = element.title,
309
                depth = depth,
310
                pageLabel = element.pageLabel,
311
                pageIndex = (element.action as? GoToAction)?.pageIndex,
312
            ),
313
        ) + element.children.flatten(depth + 1)
314
    }
315
}
316

317
// UI -----------------------------------------------------------------------------------------
318

319
@OptIn(ExperimentalMaterial3Api::class)
320
@Composable
321
private fun CustomSdkUiSheet(
322
    initialPane: CustomPane,
323
    settings: SettingsOptions,
324
    documentInfo: CustomDocumentInfo?,
325
    outlineRows: List<CustomOutlineRow>,
326
    onDismiss: () -> Unit,
327
    onApplySettings: (SettingsOptions) -> Unit,
328
    onSaveDocumentInfo: (CustomDocumentInfo) -> Unit,
329
    onOutlineRowClick: (CustomOutlineRow) -> Unit,
330
) {
331
    var pane by remember { mutableStateOf(initialPane) }
332

333
    ModalBottomSheet(
334
        onDismissRequest = onDismiss,
335
        sheetState = rememberModalBottomSheetState(skipPartiallyExpanded = true),
336
    ) {
337
        PrimaryTabRow(selectedTabIndex = pane.ordinal) {
338
            CustomPane.entries.forEach { entry ->
339
                Tab(
340
                    selected = entry == pane,
341
                    onClick = { pane = entry },
342
                    text = { Text(entry.label) },
343
                )
344
            }
345
        }
346
        Column(
347
            modifier = Modifier
348
                .fillMaxWidth()
349
                .verticalScroll(rememberScrollState())
350
                .padding(horizontal = 24.dp, vertical = 12.dp),
351
            verticalArrangement = Arrangement.spacedBy(12.dp),
352
        ) {
353
            when (pane) {
354
                CustomPane.Settings -> SettingsPane(settings, onDismiss, onApplySettings)
355
                CustomPane.DocumentInfo -> DocumentInfoPane(documentInfo, onDismiss, onSaveDocumentInfo)
356
                CustomPane.Outline -> OutlinePane(outlineRows, onOutlineRowClick)
357
            }
358
        }
359
    }
360
}
361

362
@Composable
363
private fun SettingsPane(options: SettingsOptions, onDismiss: () -> Unit, onApply: (SettingsOptions) -> Unit) {
364
    // SettingsOptions holds plain mutable fields rather than Compose state, so edit a local copy and
365
    // hand a finished one back on apply.
366
    var scrollDirection by remember { mutableStateOf(options.scrollDirection) }
367
    var scrollMode by remember { mutableStateOf(options.scrollMode) }
368
    var layoutMode by remember { mutableStateOf(options.layoutMode) }
369
    var themeMode by remember { mutableStateOf(options.themeMode) }
370
    var keepScreenOn by remember { mutableStateOf(options.screenTimeoutMillis == TIMEOUT_INFINITE) }
371

372
    ChoiceRow("Scroll direction", PageScrollDirection.entries, scrollDirection) { scrollDirection = it }
373
    ChoiceRow("Page transition", PageScrollMode.entries, scrollMode) { scrollMode = it }
374
    ChoiceRow("Page layout", PageLayoutMode.entries, layoutMode) { layoutMode = it }
375
    ChoiceRow("Theme", ThemeMode.entries, themeMode) { themeMode = it }
376

377
    Row(
378
        modifier = Modifier.fillMaxWidth(),
379
        verticalAlignment = Alignment.CenterVertically,
380
        horizontalArrangement = Arrangement.SpaceBetween,
381
    ) {
382
        Text("Keep screen on", style = MaterialTheme.typography.bodyLarge)
383
        Switch(checked = keepScreenOn, onCheckedChange = { keepScreenOn = it })
384
    }
385

386
    ActionRow(confirmLabel = "Apply", onDismiss = onDismiss) {
387
        // Reuse the SDK's own carrier, and copy() keeps the values this UI does not offer.
388
        onApply(
389
            options.copy().apply {
390
                this.scrollDirection = scrollDirection
391
                this.scrollMode = scrollMode
392
                this.layoutMode = layoutMode
393
                this.themeMode = themeMode
394
                screenTimeoutMillis = if (keepScreenOn) TIMEOUT_INFINITE else TIMEOUT_DEFAULT
395
            },
396
        )
397
    }
398
}
399

400
@Composable
401
private fun DocumentInfoPane(info: CustomDocumentInfo?, onDismiss: () -> Unit, onSave: (CustomDocumentInfo) -> Unit) {
402
    if (info == null) {
403
        Text("The document is still loading.")
404
        return
405
    }
406

407
    var title by remember { mutableStateOf(info.title) }
408
    var author by remember { mutableStateOf(info.author) }
409
    var subject by remember { mutableStateOf(info.subject) }
410
    var keywords by remember { mutableStateOf(info.keywords) }
411
    var pageBinding by remember { mutableStateOf(info.pageBinding) }
412

413
    if (!info.isEditable) {
414
        Text("This document cannot be saved, so the fields are read only.", style = MaterialTheme.typography.bodySmall)
415
    }
416

417
    listOf(
418
        Triple("Title", title) { value: String -> title = value },
419
        Triple("Author", author) { value: String -> author = value },
420
        Triple("Subject", subject) { value: String -> subject = value },
421
        Triple("Keywords, comma separated", keywords) { value: String -> keywords = value },
422
    ).forEach { (label, value, onChange) ->
423
        OutlinedTextField(
424
            value = value,
425
            onValueChange = onChange,
426
            label = { Text(label) },
427
            enabled = info.isEditable,
428
            modifier = Modifier.fillMaxWidth(),
429
        )
430
    }
431

432
    val bindings = listOf(PageBinding.LEFT_EDGE, PageBinding.RIGHT_EDGE)
433
    Text("Page binding", style = MaterialTheme.typography.labelLarge)
434
    SingleChoiceSegmentedButtonRow(modifier = Modifier.fillMaxWidth()) {
435
        bindings.forEachIndexed { index, binding ->
436
            SegmentedButton(
437
                selected = binding == pageBinding,
438
                onClick = { pageBinding = binding },
439
                enabled = info.isEditable,
440
                shape = SegmentedButtonDefaults.itemShape(index = index, count = bindings.size),
441
            ) {
442
                Text(if (binding == PageBinding.LEFT_EDGE) "Left" else "Right")
443
            }
444
        }
445
    }
446

447
    HorizontalDivider(modifier = Modifier.padding(vertical = 4.dp))
448

449
    info.readOnlyRows.forEach { (label, value) ->
450
        Row(modifier = Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.SpaceBetween) {
451
            Text(label, style = MaterialTheme.typography.bodyMedium)
452
            Text(value, style = MaterialTheme.typography.bodyMedium, textAlign = TextAlign.End)
453
        }
454
    }
455

456
    ActionRow(confirmLabel = "Save", enabled = info.isEditable, onDismiss = onDismiss) {
457
        onSave(
458
            info.copy(
459
                title = title,
460
                author = author,
461
                subject = subject,
462
                keywords = keywords,
463
                pageBinding = pageBinding,
464
            ),
465
        )
466
    }
467
}
468

469
@Composable
470
private fun OutlinePane(rows: List<CustomOutlineRow>, onRowClick: (CustomOutlineRow) -> Unit) {
471
    if (rows.isEmpty()) {
472
        Text("This document has no outline.")
473
        return
474
    }
475
    rows.forEach { row ->
476
        Row(
477
            modifier = Modifier
478
                .fillMaxWidth()
479
                .clickable(enabled = row.pageIndex != null) { onRowClick(row) }
480
                .padding(start = (row.depth * 16).dp, top = 8.dp, bottom = 8.dp),
481
            horizontalArrangement = Arrangement.SpaceBetween,
482
        ) {
483
            Text(row.title, style = MaterialTheme.typography.bodyLarge)
484
            row.pageLabel?.let { Text(it, style = MaterialTheme.typography.bodyMedium) }
485
                ?: row.pageIndex?.let { Text("${it + 1}", style = MaterialTheme.typography.bodyMedium) }
486
        }
487
        HorizontalDivider()
488
    }
489
}
490

491
/** A labelled single choice row over the values of one configuration enum. */
492
@Composable
493
private fun <T : Enum<T>> ChoiceRow(label: String, values: List<T>, selected: T, onSelect: (T) -> Unit) {
494
    Column(verticalArrangement = Arrangement.spacedBy(4.dp)) {
495
        Text(label, style = MaterialTheme.typography.labelLarge)
496
        SingleChoiceSegmentedButtonRow(modifier = Modifier.fillMaxWidth()) {
497
            values.forEachIndexed { index, value ->
498
                SegmentedButton(
499
                    selected = value == selected,
500
                    onClick = { onSelect(value) },
501
                    shape = SegmentedButtonDefaults.itemShape(index = index, count = values.size),
502
                ) {
503
                    Text(value.name.lowercase().replace('_', ' ').replaceFirstChar { it.uppercase() })
504
                }
505
            }
506
        }
507
    }
508
}
509

510
/** The dismiss and confirm buttons shared by the editable panes. */
511
@Composable
512
private fun ActionRow(confirmLabel: String, enabled: Boolean = true, onDismiss: () -> Unit, onConfirm: () -> Unit) {
513
    Row(
514
        modifier = Modifier
515
            .fillMaxWidth()
516
            .padding(bottom = 24.dp),
517
        horizontalArrangement = Arrangement.End,
518
    ) {
519
        TextButton(onClick = onDismiss) { Text("Close") }
520
        Button(enabled = enabled, onClick = onConfirm) { Text(confirmLabel) }
521
    }
522
}