SavedStateRegistry
class SavedStateRegistry
kotlin.Any | |
↳ | androidx.savedstate.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 classes | |
---|---|
abstract |
Subclasses of this interface will be automatically recreated if they were previously registered via { |
abstract |
This interface marks a component that contributes to saved state. |
Public methods | |
---|---|
Bundle? |
consumeRestoredStateForKey(@NonNull key: String) Consumes saved state previously supplied by |
Boolean |
Returns if state was restored after creation and can be safely consumed with |
Unit |
registerSavedStateProvider(@NonNull key: String, @NonNull provider: SavedStateRegistry.SavedStateProvider) Registers a |
Unit |
runOnNextRecreation(@NonNull clazz: Class<out SavedStateRegistry.AutoRecreated!>) Executes the given class when the owning component restarted. |
Unit |
unregisterSavedStateProvider(@NonNull key: String) Unregisters a component previously registered by the given |
Public methods
consumeRestoredStateForKey
@MainThread @Nullable fun consumeRestoredStateForKey(@NonNull key: String): Bundle?
Consumes saved state previously supplied by SavedStateProvider
registered via registerSavedStateProvider(String, SavedStateProvider)
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(Bundle 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. |
Return | |
---|---|
Bundle? |
S with the previously saved state or null |
isRestored
@MainThread fun isRestored(): Boolean
Returns if state was restored after creation and can be safely consumed with consumeRestoredStateForKey(String)
Return | |
---|---|
Boolean |
true if state was restored. |
registerSavedStateProvider
@MainThread fun registerSavedStateProvider(
@NonNull key: String,
@NonNull 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(String)
.
If there is unconsumed value with the same key
, the value supplied by savedStateProvider
will be override 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
@MainThread fun runOnNextRecreation(@NonNull clazz: Class<out 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(SavedStateRegistryOwner)
will be called. It is called as part of dispatching of androidx.lifecycle.Lifecycle.Event#ON_CREATE
event.
Parameters | |
---|---|
clazz |
Class<out SavedStateRegistry.AutoRecreated!>: that will need to be instantiated on the next component recreation |
Exceptions | |
---|---|
IllegalStateException |
if you try to call if after Lifecycle.Event#ON_STOP was dispatched |