SavedStateRegistry
public final 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 |
|---|
public interface SavedStateRegistry.AutoRecreatedSubclasses of this interface will be automatically recreated if they were previously registered via |
public fun interface SavedStateRegistry.SavedStateProviderContributes to the saved state. |
Public methods |
|
|---|---|
final SavedState |
Consumes the saved state previously supplied by a |
final SavedStateRegistry.SavedStateProvider |
Returns the |
final boolean |
Returns |
final void |
@MainThreadRegisters a |
final void |
Executes the given class when the owning component restarted. |
final void |
Unregisters a component previously registered with the given |
Public methods
consumeRestoredStateForKey
@MainThread
public final SavedState consumeRestoredStateForKey(@NonNull String key)
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 | |
|---|---|
@NonNull String key |
The key with which the |
| Returns | |
|---|---|
SavedState |
The previously saved state, or |
getSavedStateProvider
public final SavedStateRegistry.SavedStateProvider getSavedStateProvider(@NonNull String key)
Returns the SavedStateProvider previously registered with registerSavedStateProvider, or null if no provider has been registered with the given key.
| Parameters | |
|---|---|
@NonNull String key |
The key used to register the |
isRestored
@MainThread
public final boolean isRestored()
Returns true if the state was restored after creation and can be safely consumed with consumeRestoredStateForKey, false otherwise.
registerSavedStateProvider
@MainThread
public final void registerSavedStateProvider(
@NonNull String key,
@NonNull SavedStateRegistry.SavedStateProvider provider
)
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 | |
|---|---|
@NonNull String key |
The key with which the returned saved state is associated. |
@NonNull SavedStateRegistry.SavedStateProvider provider |
The |
runOnNextRecreation
@MainThread
public final void runOnNextRecreation(
@NonNull Class<@NonNull SavedStateRegistry.AutoRecreated> clazz
)
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 | |
|---|---|
@NonNull Class<@NonNull SavedStateRegistry.AutoRecreated> clazz |
that will need to be instantiated on the next component recreation |
| Throws | |
|---|---|
IllegalArgumentException |
if you try to call if after |
unregisterSavedStateProvider
@MainThread
public final void unregisterSavedStateProvider(@NonNull String key)
Unregisters a component previously registered with the given key.