SavedStateRegistry

An interface for plugging components that consumes and contributes to the saved state.

This objects lifetime is bound to the lifecycle of owning component: when activity or fragment is recreated, new instance of the object is created as well.

Summary

Nested types

Subclasses of this interface will be automatically recreated if they were previously registered via runOnNextRecreation.

This interface marks a component that contributes to saved state.

Public functions
SavedState?

Consumes saved state previously supplied by SavedStateProvider registered via registerSavedStateProvider with the given key.
Cmn
android
SavedStateRegistry.SavedStateProvider?

Get a previously registered SavedStateProvider.
Cmn
android
Unit

Registers a SavedStateProvider by the given key.
Cmn
android
Unit

Executes the given class when the owning component restarted.
android
Unit

Unregisters a component previously registered by the given key
Cmn
android

Public properties
Boolean

Whether the state was restored after creation and can be safely consumed with consumeRestoredStateForKey.
Cmn
android

Public functions

consumeRestoredStateForKey

Cmn android
Added in 1.0.0
@MainThread
fun consumeRestoredStateForKey(key: String): SavedState?

Consumes saved state previously supplied by SavedStateProvider registered via registerSavedStateProvider with the given key.

This call clears an internal reference to returned saved state, so if you call it second time in the row it will return null.

All unconsumed values will be saved during onSaveInstanceState(SavedState savedState)

This method can be called after super.onCreate(savedStateBundle) of the corresponding component. Calling it before that will result in IllegalArgumentException. Lifecycle.Event.ON_CREATE can be used as a signal that a saved state can be safely consumed.

Parameters
key: String

a key with which SavedStateProvider was previously registered.
Returns
SavedState?

S with the previously saved state or {@code null}

getSavedStateProvider

Cmn android
Added in 1.2.0
fun getSavedStateProvider(key: String): SavedStateRegistry.SavedStateProvider?

Get a previously registered SavedStateProvider.

Parameters
key: String

The key used to register the SavedStateProvider when it was registered with registerSavedStateProvider(String, SavedStateProvider).

Returns the SavedStateProvider previously registered with registerSavedStateProvider or null if no provider has been registered with the given key.

registerSavedStateProvider

Cmn android
Added in 1.0.0
@MainThread
fun registerSavedStateProvider(
    key: String,
    provider: SavedStateRegistry.SavedStateProvider
): Unit

Registers a SavedStateProvider by the given key. This savedStateProvider will be called during state saving phase, returned object will be associated with the given key and can be used after the restoration via .consumeRestoredStateForKey.

If there is unconsumed value with the same key, the value supplied by savedStateProvider will be overridden and will be written to resulting saved state.

If a provider was already registered with the given key, an implementation should throw an IllegalArgumentException

Parameters
key: String

a key with which returned saved state will be associated
provider: SavedStateRegistry.SavedStateProvider

savedStateProvider to get saved state.

runOnNextRecreation

android
Added in 1.0.0
@MainThread
fun runOnNextRecreation(clazz: Class<SavedStateRegistry.AutoRecreated>): Unit

Executes the given class when the owning component restarted.

The given class will be automatically instantiated via default constructor and method AutoRecreated.onRecreated will be called. It is called as part of dispatching of androidx.lifecycle.Lifecycle.Event.ON_CREATE event.

Parameters
clazz: Class<SavedStateRegistry.AutoRecreated>

that will need to be instantiated on the next component recreation
Throws
kotlin.IllegalArgumentException

if you try to call if after Lifecycle.Event.ON_STOP was dispatched

unregisterSavedStateProvider

Cmn android
Added in 1.0.0
@MainThread
fun unregisterSavedStateProvider(key: String): Unit

Unregisters a component previously registered by the given key

Parameters
key: String

a key with which a component was previously registered.

Public properties

isRestored

Cmn android
Added in 1.0.0
val isRestored: Boolean

Whether the state was restored after creation and can be safely consumed with consumeRestoredStateForKey.

isRestored == true if state was restored