SavedStateRegistry

Artifact: androidx.savedstate:savedstate

View Source

Added in 1.0.0

---

Kotlin |Java

Common/AllAndroid/JVM

• Cmn

  class SavedStateRegistry

---

An interface for plugging in components that consume and contribute to the saved state.

This object's lifetime is bound to the lifecycle of the owning component. When the activity or fragment is recreated, a new instance of this object is created as well.

Summary

Nested types
interface SavedStateRegistry.AutoRecreated Subclasses of this interface will be automatically recreated if they were previously registered via runOnNextRecreation.
fun interface SavedStateRegistry.SavedStateProvider Contributes to the saved state.

Public functions
SavedState?	@MainThread consumeRestoredStateForKey(key: String) Consumes the saved state previously supplied by a SavedStateProvider registered via registerSavedStateProvider with the given key.	Cmn android
SavedStateRegistry.SavedStateProvider?	getSavedStateProvider(key: String) Returns the SavedStateProvider previously registered with registerSavedStateProvider, or null if no provider has been registered with the given key.	Cmn android
Unit	@MainThread registerSavedStateProvider(     key: String,     provider: SavedStateRegistry.SavedStateProvider ) Registers a SavedStateProvider with the given key.	Cmn android
Unit	@MainThread runOnNextRecreation(clazz: Class<SavedStateRegistry.AutoRecreated>) Executes the given class when the owning component restarted.	android
Unit	@MainThread unregisterSavedStateProvider(key: String) Unregisters a component previously registered with the given key.	Cmn android

Public properties
Boolean	isRestored Returns true if the state was restored after creation and can be safely consumed with consumeRestoredStateForKey, false otherwise.	Cmn android

Public functions

consumeRestoredStateForKey

Cmn android

Added in 1.0.0

@MainThread
fun consumeRestoredStateForKey(key: String): SavedState?

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

This call clears the internal reference to the returned saved state. Subsequent calls with the same key will return null.

All unconsumed values are saved during state saving.

Call this method after the corresponding component has been created. Calling it before creation results in an IllegalArgumentException. Lifecycle.Event.ON_CREATE signals that a saved state can be safely consumed.

Parameters
key: String	The key with which the SavedStateProvider was previously registered.

Returns
SavedState?	The previously saved state, or null if none exists or it has already been consumed.

getSavedStateProvider

Cmn android

Added in 1.2.0

fun getSavedStateProvider(key: String): SavedStateRegistry.SavedStateProvider?

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

Parameters
key: String	The key used to register the SavedStateProvider.

registerSavedStateProvider

Cmn android

Added in 1.0.0

@MainThread
fun registerSavedStateProvider(
    key: String,
    provider: SavedStateRegistry.SavedStateProvider
): Unit

Registers a SavedStateProvider with the given key.

This SavedStateProvider will be called during the state saving phase. The returned state will be associated with the given key and can be consumed after restoration via consumeRestoredStateForKey.

If there is an unconsumed value with the same key, the value supplied by the SavedStateProvider overrides it and is written to the resulting saved state.

If a provider was already registered with the given key, throws an IllegalArgumentException.

Parameters
key: String	The key with which the returned saved state is associated.
provider: SavedStateRegistry.SavedStateProvider	The SavedStateProvider to get the 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
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 with the given key.

Parameters
key: String	The key with which the component was previously registered.

Public properties

isRestored

Cmn android

Added in 1.0.0

val isRestored: Boolean

Returns true if the state was restored after creation and can be safely consumed with consumeRestoredStateForKey, false otherwise.