ControlledRetainedValuesStore

kotlin.Any
   ↳ androidx.compose.runtime.retain.RetainedValuesStore
     ↳ androidx.compose.runtime.retain.ControlledRetainedValuesStore

A ControlledRetainedValuesStore is effectively a "Mutable" RetainedValuesStore. This store can be used to define a custom retain scenario and supports nesting within another RetainedValuesStore via setParentRetainStateProvider.

This class can be used to create your own retention scenario. A retention scenario is a situation in which content is transiently removed from the composition hierarchy and can be restored with the retained values from the previous composition.

When using this class to create your own retention scenario, call startRetainingExitedValues to make this store start retaining exited values state before any content is transiently removed. When the transiently removed content is restored, call stopRetainingExitedValues after all content has been restored. You can use androidx.compose.runtime.Recomposer.scheduleFrameEndCallback or androidx.compose.runtime.Composer.scheduleFrameEndCallback to ensure that all content has settled in subcompositions and movable content that may not be realized or applied in as part of a composition that is currently ongoing.

To create a ControlledRetainedValuesStore that is managed entirely within the composition hierarchy, you can use retainControlledRetainedValuesStore to create a ControlledRetainedValuesStore that is automatically parented to the current LocalRetainedValuesStore.

Summary

Public constructors
Cmn

Public functions
open Any?
getExitedValueOrElse(key: Any, defaultValue: Any?)

If this store is currently retaining exited values and has a value previously created with the given key, its original record is returned and removed from the list of exited kept objects that this store is tracking.
Cmn
Unit

Calling this function will automatically mirror the state of isRetainingExitedValues to match parent's state.
Cmn
Unit

Indicates that this store should continue to retain values that exit the composition.
Cmn
Unit

Stops retaining values that exit the composition.
Cmn

Protected functions
open Unit

Called when this store first starts to retain exited values (i.e. when isRetainingExitedValues transitions from false to true).
Cmn
open Unit

Called when this store stops retaining exited values (i.e. when isRetainingExitedValues transitions from true to false).
Cmn
open Unit
saveExitingValue(key: Any, value: Any?)

Invoked when a retained value is exiting composition while this store is retaining exited values.
Cmn

Public properties
Int

Returns the number of calls to startRetainingExitedValues - stopRetainingExitedValues.
Cmn

Inherited functions
From androidx.compose.runtime.retain.RetainedValuesStore
final Unit

Registers the given observer with this RetainStateProvider to be notified when the value of isRetainingExitedValues changes.
Cmn
final Unit

Removes a previously registered observer.
Cmn
Unit

Called to increment the number of requests to retain exited values.
Cmn
Unit

Clears a previous call to requestRetainExitedValues.
Cmn

Inherited properties
From androidx.compose.runtime.retain.RetainedValuesStore
final Boolean

Returns whether retained values should continue to be held when they are removed from the composition hierarchy.
Cmn
Int
Cmn

Public constructors

ControlledRetainedValuesStore

Cmn
Added in 1.10.0-beta01
ControlledRetainedValuesStore()

Public functions

getExitedValueOrElse

Cmn 
open fun getExitedValueOrElse(key: Any, defaultValue: Any?): Any?

If this store is currently retaining exited values and has a value previously created with the given key, its original record is returned and removed from the list of exited kept objects that this store is tracking.

Parameters
key: Any

The keys to resolve a retained value that has left composition
defaultValue: Any?

A value to be returned if there are no retained values that have exited composition and are being held by this RetainedValuesStore for the given key.
Returns
Any?

A retained value for key if there is one and it hasn't already re-entered composition, otherwise defaultValue.

setParentRetainStateProvider

Cmn
Added in 1.10.0-beta01
fun setParentRetainStateProvider(parent: RetainStateProvider): Unit

Calling this function will automatically mirror the state of isRetainingExitedValues to match parent's state. This is an addition to requests made on the ControlledRetainedValuesStore, so retaining exited values is a function of whether the parent is retaining exited values OR this store has been requested to retain exited values.

A ControlledRetainedValuesStore can only have one parent. If a new parent is provided, it will replace the old one and will match the new parent's isRetainingExitedValues state. This may cause this store to start or stop retaining exited values if this store has no other active requests from startRetainingExitedValues.

startRetainingExitedValues

Cmn
Added in 1.10.0-beta01
fun startRetainingExitedValues(): Unit

Indicates that this store should continue to retain values that exit the composition. If this store is already in this mode, the store will not change states. The number of times this function is called is tracked and must be matched by the same number of calls to stopRetainingExitedValues before the kept values will be retired.

stopRetainingExitedValues

Cmn
Added in 1.10.0-beta01
fun stopRetainingExitedValues(): Unit

Stops retaining values that exit the composition. This function cancels a request that previously began by calling startRetainingExitedValues. If startRetainingExitedValues has been called more than stopRetainingExitedValues, the store will continue to retain values that have exited the composition until stopRetainingExitedValues has been called the same number of times as startRetainingExitedValues.

Throws
kotlin.IllegalStateException

if stopRetainingExitedValues is called more times than startRetainingExitedValues

Protected functions

onStartRetainingExitedValues

Cmn 
protected open fun onStartRetainingExitedValues(): Unit

Called when this store first starts to retain exited values (i.e. when isRetainingExitedValues transitions from false to true). When this is called, implementors should prepare to begin to store values they receive from saveExitingValue.

onStopRetainingExitedValues

Cmn 
protected open fun onStopRetainingExitedValues(): Unit

Called when this store stops retaining exited values (i.e. when isRetainingExitedValues transitions from true to false). After this is called, all exited values that have been kept and not restored via getExitedValueOrElse should be retired.

Implementors MUST invoke RetainObserver.onRetired for all exited and unrestored RememberObserver when this method is invoked.

saveExitingValue

Cmn 
protected open fun saveExitingValue(key: Any, value: Any?): Unit

Invoked when a retained value is exiting composition while this store is retaining exited values. It is up to the implementation of this method to decide whether and how to store these values so that they can later be retrieved by getExitedValueOrElse.

The given key are not guaranteed to be unique. To handle duplicate keys, implementors should return retained values with the same keys from getExitedValueOrElse in the opposite order they are received by saveExitingValue.

If the implementation of this store does not accept this value into its kept exited object list, it MUST call RetainObserver.onRetired if value implements RetainObserver.

Public properties

retainExitedValuesRequestsFromSelf

Cmn
Added in 1.10.0-beta01
val retainExitedValuesRequestsFromSelf: Int

Returns the number of calls to startRetainingExitedValues - stopRetainingExitedValues. Effectively, the total number of active requests to this ControlledRetainedValuesStore.

Note that this value ignores any parent state. It only counts explicit requests from the user to startRetainingExitedValues. This store could still be retaining if this value is 0 if the parent store is retaining. This is useful if you want to track your contributions to this store's state, ignoring the parent.