SavedStateHandle
public
final
class
SavedStateHandle
extends Object
java.lang.Object | |
↳ | androidx.lifecycle.SavedStateHandle |
A handle to saved state passed down to 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
LiveData
returned
by getLiveData(String)
.
You can write a value to it via set(String, Object)
or setting a value to
MutableLiveData
returned by getLiveData(String)
.
Summary
Public constructors | |
---|---|
SavedStateHandle(Map<String, Object> initialState)
Creates a handle with the given initial arguments. |
|
SavedStateHandle()
Creates a handle with the empty state. |
Public methods | |
---|---|
void
|
clearSavedStateProvider(String key)
Clear any |
boolean
|
contains(String key)
|
<T>
T
|
get(String key)
Returns a value associated with the given key. |
<T>
MutableLiveData<T>
|
getLiveData(String key)
Returns a |
<T>
MutableLiveData<T>
|
getLiveData(String key, T initialValue)
Returns a |
Set<String>
|
keys()
Returns all keys contained in this
Returned set contains all keys: keys used to get LiveData-s, to set SavedStateProviders and
keys used in regular |
<T>
T
|
remove(String key)
Removes a value associated with the given key. |
<T>
void
|
set(String key, T value)
Associate the given value with the key. |
void
|
setSavedStateProvider(String key, SavedStateRegistry.SavedStateProvider provider)
Set a |
Inherited methods | |
---|---|
Public constructors
SavedStateHandle
public SavedStateHandle (Map<String, Object> initialState)
Creates a handle with the given initial arguments.
Parameters | |
---|---|
initialState |
Map |
SavedStateHandle
public SavedStateHandle ()
Creates a handle with the empty state.
Public methods
clearSavedStateProvider
public void clearSavedStateProvider (String key)
Clear any SavedStateRegistry.SavedStateProvider
that was previously set via
setSavedStateProvider(String, SavedStateProvider)
.
Note: calling this method within SavedStateRegistry.SavedStateProvider.saveState()
is supported, but
will only affect future state saving operations.
Parameters | |
---|---|
key |
String : a key previously used with setSavedStateProvider(String, SavedStateRegistry.SavedStateProvider)
|
contains
public boolean contains (String key)
Parameters | |
---|---|
key |
String |
Returns | |
---|---|
boolean |
true if there is value associated with the given key. |
get
public T get (String key)
Returns a value associated with the given key.
Parameters | |
---|---|
key |
String |
Returns | |
---|---|
T |
getLiveData
public MutableLiveData<T> getLiveData (String key)
Returns a LiveData
that access data associated with the given key.
Parameters | |
---|---|
key |
String |
Returns | |
---|---|
MutableLiveData<T> |
See also:
getLiveData
public MutableLiveData<T> getLiveData (String key, T initialValue)
Returns a LiveData
that access data associated with the given key.
LiveData<String> liveData = savedStateHandle.get(KEY, "defaultValue");
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.
String defaultValue = ...; // nullable
LiveData<String> liveData;
if (defaultValue != null) {
liveData = savedStateHandle.getLiveData(KEY, defaultValue);
} else {
liveData = savedStateHandle.getLiveData(KEY);
}
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.
|
Returns | |
---|---|
MutableLiveData<T> |
keys
public Set<String> keys ()
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)
.
Returns | |
---|---|
Set<String> |
remove
public T remove (String key)
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 LiveData
previously
returned by 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 |
Returns | |
---|---|
T |
a value that was previously associated with the given key. |
set
public void set (String key, T value)
Associate the given value with the key. The value must have a type that could be stored in
Bundle
Parameters | |
---|---|
key |
String |
value |
T |
setSavedStateProvider
public void setSavedStateProvider (String key, SavedStateRegistry.SavedStateProvider provider)
Set a SavedStateRegistry.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(String)
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
SavedStateRegistry.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
SavedStateRegistry.SavedStateProvider.saveState() when the state should be saved
|