KPdfSaveState: observe the PDF save and export flow

KPdfSaveState tracks the SDK-managed save flow — from export preparation through the platform file picker to confirmed save, cancellation, or error.

KPdfSaveState is a sealed interface that models the full lifecycle of saving the current PDF to a user-chosen location on the device. Collect it from KPdfViewerState.saveState (a StateFlow) to drive progress indicators, confirmation banners, and error handling. Trigger the flow by calling viewerState.requestSave(). The SDK then serialises the document, opens the platform native file-save picker, and progresses through the states below until a terminal state (Success, Cancelled, or Error) is reached. The state resets to Idle at the start of each new save request.

Variants

Idle · data object

No save operation is in progress. This is the initial state and the state the SDK returns to after the next requestSave() call replaces the previous terminal state.

Exporting · data object

The SDK is serialising the current PDF into bytes in preparation for writing. Display a loading indicator while in this state. The platform file picker has not opened yet.

AwaitingDestination · data class

Serialisation is complete and the platform file-save picker is open. The user has not yet chosen a destination.

requestId · Long · required

Unique identifier for this save request. Use it to correlate AwaitingDestination, Success, and Cancelled events when multiple save requests could be in flight.

suggestedFileName · String · required

The file name the SDK pre-filled in the picker, derived from the document title or a default such as document.pdf.

mimeType · String · required

The MIME type proposed to the picker, typically application/pdf.

Success · data class

The user selected a destination and the file was written successfully.

requestId · Long · required

The identifier of the completed save request, matching the AwaitingDestination.requestId for the same flow.

suggestedFileName · String · required

The file name that was used when the file was written.

mimeType · String · required

The MIME type of the saved file.

location · String? · required

A platform-specific URI or path string for the saved file, if the platform makes it available. null on platforms that do not expose the final path.

Cancelled · data class

The user dismissed the file-save picker without choosing a destination. No file was written.

requestId · Long · required

The identifier of the cancelled request.

suggestedFileName · String · required

The file name that was proposed to the picker.

mimeType · String · required

The MIME type that was proposed to the picker.

Error · data class

The save flow failed — either during serialisation or after the user chose a destination.

reason · KPdfError · required

A sealed KPdfError value describing the failure. Check reason.message for a human-readable description.

suggestedFileName · String? · required

The file name that was in use when the error occurred, if available.

mimeType · String? · required

The MIME type that was in use when the error occurred, if available.

Reacting to save state in Compose

Collect saveState with collectAsState() and branch on each variant to update your UI. Call requestSave() from a button or toolbar action to start the flow — KPdfViewerToolbar does this automatically when showSave is true.

@Composable
fun SaveControls(viewerState: KPdfViewerState) {
    val saveState by viewerState.saveState.collectAsState()

    Button(onClick = { viewerState.requestSave() }) {
        Text("Save PDF")
    }

    when (val state = saveState) {
        KPdfSaveState.Idle -> Unit

        KPdfSaveState.Exporting -> {
            LinearProgressIndicator()
            Text("Preparing PDF…")
        }

        is KPdfSaveState.AwaitingDestination -> {
            Text("Choose where to save "${state.suggestedFileName}"")
        }

        is KPdfSaveState.Success -> {
            Text("Saved successfully.")
            state.location?.let { Text("Location: $it") }
        }

        is KPdfSaveState.Cancelled -> {
            Text("Save cancelled.")
        }

        is KPdfSaveState.Error -> {
            Text("Save failed: ${state.reason.message}")
        }
    }
}

Notes

• KPdfViewerState.saveState is a StateFlow<KPdfSaveState>, so collecting it is safe on the first frame and never suspends.
• The Exporting → AwaitingDestination transition happens on a background dispatcher; do not block the main thread waiting for it.
  • If you use rememberPdfViewerState, the native file picker is already wired automatically. You only need to observe the state and react to Success or Error.
• requestId is a monotonically increasing Long. If the user triggers multiple rapid saves, each request receives a distinct identifier so you can safely ignore stale terminal states.