Customize the settings UI

In the settings sheet, a user picks a page transition, scroll direction, page layout, and theme. Since 12.0, you have three ways to show those settings to a user, so pick the one that matches how much you want to own.

1. Show the built-in sheet. Leave settingsMenuEnabled on and let the toolbar’s settings item open it. Nothing to write.
2. Compose NutrientSettingsView. Keep Nutrient’s rows and theming, own where they appear, and replace or decorate an individual row.
3. Render your own UI. Intercept the toolbar item and read and write the same data through SettingsOptions.

Reusing the settings rows

NutrientSettingsView is a public composable in io.nutrient.ui.settings. It renders content only, with no sheet, scrim, or dialog, so presentation stays yours. Give it a bounded height, because the rows scroll inside it.

var options by remember { mutableStateOf(currentSettingsOptions) }

NutrientSettingsView(
    options = options,
    onOptionsChanged = { options = it },
)

SettingsOptions.visibleItems decides which rows appear, the same way it does for the built-in sheet. Holding the options as state and applying them to the SDK is yours to do; the composable doesn’t write to the configuration itself.

Replacing a single row

settingsItem wraps each row. It receives the row’s SettingsMenuItemType and Nutrient’s default rendering for it, so you can replace one row, decorate it, or leave it alone:

NutrientSettingsView(
    options = options,
    onOptionsChanged = { options = it },
    settingsItem = { type, default ->
        when (type) {
            // Replace this row outright.
            SettingsMenuItemType.SCROLL_DIRECTION -> MyOwnScrollDirectionRow()
            // Keep Nutrient's, with your own heading above it.
            SettingsMenuItemType.THEME -> Column { MyHeading(); default() }
            // Everything else exactly as Nutrient draws it.
            else -> default()
        }
    },
)

title is a slot too, defaulting to the localized “Settings” title the built-in sheet draws. Pass {} for no title.

Rendering your own settings UI

To replace the screen entirely, intercept the toolbar’s settings item. The SDK consults setOnToolbarItemClickListener before its default action, so returning true suppresses the built-in sheet and leaves the toolbar item in place:

setOnToolbarItemClickListener { id ->
    if (id == R.id.pspdf__menu_option_settings) {
        showMySettingsScreen()
        true
    } else {
        false
    }
}

SettingsOptions is the carrier between your UI and the SDK. Read the current values from the active PdfActivityConfiguration, PdfUi.getScreenTimeout, and PSPDFKitPreferences; render whatever controls you like; and apply the result back through the same three.

The same interception works for R.id.pspdf__menu_option_info_view and R.id.pspdf__menu_option_outline, so document info and the outline can be replaced the same way. The Catalog app’s Custom Settings, Info and Outline UI example does all three, using public APIs only.

Theming the built-in sheet

If you only want the built-in sheet to look different, style it through pspdf__settingsDialogStyle rather than replacing it. See appearance styling for the attribute list, and modal dialogs for the sheet’s width and presentation attributes.