SavedStateHandle

SavedStateHandle()

Creates a handle with the empty state.

SavedStateHandle(initialState: Map<String, Any?>)

Creates a handle with the given initial arguments.

@MainThread
fun clearSavedStateProvider(key: String): Unit

Clear any SavedStateProvider that was previously set via setSavedStateProvider.

Note: calling this method within SavedStateProvider.saveState is supported, but will only affect future state saving operations.

@MainThread
operator fun contains(key: String): Boolean

@MainThread
operator fun <T : Any?> get(key: String): T?

Returns a value associated with the given key.

Note: If T is an Array of Parcelable classes, note that you should always use Array<Parcelable> and create a typed array from the result as going through process death and recreation (or using the Don't keep activities developer option) will result in the type information being lost, thus resulting in a ClassCastException if you directly try to assign the result to an Array<CustomParcelable> value.

val typedArray = savedStateHandle.get<Array<Parcelable>>("KEY").map {
  it as CustomParcelable
}.toTypedArray()

@MainThread
fun <T : Any?> getLiveData(key: String): MutableLiveData<T>

Returns a androidx.lifecycle.LiveData that access data associated with the given key.

@MainThread
fun <T : Any?> getLiveData(key: String, initialValue: T): MutableLiveData<T>

Returns a androidx.lifecycle.LiveData that access data associated with the given key.

`LiveData<String> liveData = savedStateHandle.get(KEY, "defaultValue");`

Keep in mind that 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 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);
}`

Note: If T is an Array of Parcelable classes, note that you should always use Array<Parcelable> and create a typed array from the result as going through process death and recreation (or using the Don't keep activities developer option) will result in the type information being lost, thus resulting in a ClassCastException if you directly try to observe the result as an Array<CustomParcelable>.

val typedArrayLiveData = savedStateHandle.getLiveData<Array<Parcelable>>(
  "KEY"
).map { array ->
  // Convert the Array<Parcelable> to an Array<CustomParcelable>
  array.map { it as CustomParcelable }.toTypedArray()
}

@MainThread
fun <T : Any?> getStateFlow(key: String, initialValue: T): StateFlow<T>

Returns a StateFlow that will emit the currently active value associated with the given key.

val flow = savedStateHandle.getStateFlow(KEY, "defaultValue")

Since this is a StateFlow there will always be a value available which, is why an initial value must be provided. The value of this flow is changed by making a call to set, passing in the key that references this flow.

If there is already a value associated with the given key, the initial value will be ignored.

Note: If T is an Array of Parcelable classes, note that you should always use Array<Parcelable> and create a typed array from the result as going through process death and recreation (or using the Don't keep activities developer option) will result in the type information being lost, thus resulting in a ClassCastException if you directly try to collect the result as an Array<CustomParcelable>.

val typedArrayFlow = savedStateHandle.getStateFlow<Array<Parcelable>>(
  "KEY"
).map { array ->
  // Convert the Array<Parcelable> to an Array<CustomParcelable>
  array.map { it as CustomParcelable }.toTypedArray()
}

@MainThread
fun keys(): Set<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.

@MainThread
fun <T : Any?> remove(key: String): T?

Removes a value associated with the given key. If there is a LiveData and/or StateFlow associated with the given key, they will be removed as well.

All changes to androidx.lifecycle.LiveDatas or StateFlows previously returned by SavedStateHandle.getLiveData or getStateFlow won't be reflected in the saved state. Also that LiveData or StateFlow won't receive any updates about new values associated by the given key.

@MainThread
operator fun <T : Any?> set(key: String, value: T?): Unit

Associate the given value with the key. The value must have a type that could be stored in android.os.Bundle

This also sets values for any active LiveDatas or Flows.

@MainThread
fun setSavedStateProvider(
    key: String,
    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.