SavedStateHandle
class SavedStateHandle
kotlin.Any | |
↳ | androidx.lifecycle.SavedStateHandle |
A handle to saved state passed down to androidx.lifecycle.ViewModel
. You should use SavedStateViewModelFactory
if you want to receive this object in ViewModel
's constructor.
This is a key-value map that will let you write and retrieve objects to and from the saved state. These values will persist after the process is killed by the system and remain available via the same object.
You can read a value from it via get(String)
or observe it via androidx.lifecycle.LiveData
returned by getLiveData(String)
.
You can write a value to it via set(String, Object)
or setting a value to androidx.lifecycle.MutableLiveData
returned by getLiveData(String)
.
Summary
Public constructors | |
---|---|
<init>(@NonNull initialState: MutableMap<String!, Any!>) Creates a handle with the given initial arguments. |
|
<init>() Creates a handle with the empty state. |
Public methods | |
---|---|
Unit |
clearSavedStateProvider(@NonNull key: String) Clear any |
Boolean | |
T? |
Returns a value associated with the given key. |
MutableLiveData<T> |
getLiveData(@NonNull key: String) Returns a |
MutableLiveData<T> |
getLiveData(@NonNull key: String, initialValue: T) Returns a |
MutableSet<String!> |
keys() Returns all keys contained in this |
T? |
Removes a value associated with the given key. |
Unit |
Associate the given value with the key. |
Unit |
setSavedStateProvider(@NonNull key: String, @NonNull provider: SavedStateRegistry.SavedStateProvider) Set a |
Public constructors
<init>
SavedStateHandle(@NonNull initialState: MutableMap<String!, Any!>)
Creates a handle with the given initial arguments.
<init>
SavedStateHandle()
Creates a handle with the empty state.
Public methods
clearSavedStateProvider
@MainThread fun clearSavedStateProvider(@NonNull key: String): Unit
Clear any SavedStateProvider
that was previously set via setSavedStateProvider(String, SavedStateProvider)
. Note: calling this method within SavedStateProvider#saveState()
is supported, but will only affect future state saving operations.
Parameters | |
---|---|
key |
String: a key previously used with setSavedStateProvider |
contains
@MainThread fun contains(@NonNull key: String): Boolean
Return | |
---|---|
Boolean |
true if there is value associated with the given key. |
get
@MainThread @Nullable fun <T : Any!> get(@NonNull key: String): T?
Returns a value associated with the given key.
getLiveData
@MainThread @NonNull fun <T : Any!> getLiveData(@NonNull key: String): MutableLiveData<T>
Returns a androidx.lifecycle.LiveData
that access data associated with the given key.
See Also
getLiveData
@MainThread @NonNull fun <T : Any!> getLiveData(
@NonNull key: String,
initialValue: T
): MutableLiveData<T>
Returns a androidx.lifecycle.LiveData
that access data associated with the given key.
<code>LiveData<String> liveData = savedStateHandle.get(KEY, "defaultValue"); </code>LiveData can have
null
as a valid value. If the initialValue
is null
and the data does not already exist in the SavedStateHandle
, the value of the returned LiveData
will be set to null
and observers will be notified. You can call getLiveData(String)
if you want to avoid dispatching null
to observers.
<code>String defaultValue = ...; // nullable LiveData<String> liveData; if (defaultValue != null) { liveData = savedStateHandle.getLiveData(KEY, defaultValue); } else { liveData = savedStateHandle.getLiveData(KEY); } </code>
Parameters | |
---|---|
key |
String: The identifier for the value |
initialValue |
T: If no value exists with the given key , a new one is created with the given initialValue . Note that passing null will create a LiveData with null value. |
keys
@MainThread @NonNull fun keys(): MutableSet<String!>
Returns all keys contained in this SavedStateHandle
Returned set contains all keys: keys used to get LiveData-s, to set SavedStateProviders and keys used in regular set(String, Object)
.
remove
@MainThread @Nullable fun <T : Any!> remove(@NonNull key: String): T?
Removes a value associated with the given key. If there is a LiveData
associated with the given key, it will be removed as well.
All changes to androidx.lifecycle.LiveData
previously returned by SavedStateHandle#getLiveData(String)
won't be reflected in the saved state. Also that LiveData
won't receive any updates about new values associated by the given key.
Parameters | |
---|---|
key |
String: a key |
Return | |
---|---|
T? |
a value that was previously associated with the given key. |
set
@MainThread fun <T : Any!> set(
@NonNull key: String,
@Nullable value: T?
): Unit
Associate the given value with the key. The value must have a type that could be stored in android.os.Bundle
Parameters | |
---|---|
<T> |
any type that can be accepted by Bundle. |
setSavedStateProvider
@MainThread fun setSavedStateProvider(
@NonNull key: String,
@NonNull provider: SavedStateRegistry.SavedStateProvider
): Unit
Set a SavedStateProvider
that will have its state saved into this SavedStateHandle. This provides a mechanism to lazily provide the Bundle
of saved state for the given key.
Calls to get
with this same key will return the previously saved state as a Bundle
if it exists.
Bundle previousState = savedStateHandle.get("custom_object"); if (previousState != null) { // Convert the previousState into your custom object } savedStateHandle.setSavedStateProvider("custom_object", () -> { Bundle savedState = new Bundle(); // Put your custom object into the Bundle, doing any conversion required return savedState; });Note: calling this method within
SavedStateProvider#saveState()
is supported, but will only affect future state saving operations.
Parameters | |
---|---|
key |
String: a key which will populated with a Bundle produced by the provider |
provider |
SavedStateRegistry.SavedStateProvider: a SavedStateProvider which will receive a callback to SavedStateProvider#saveState() when the state should be saved |