ControlledRetainScope

public class ControlledRetainScope : RetainScope()

A ControlledRetainScope is effectively a "Mutable" RetainScope. This scope can be used to define a custom retain scenario and supports nesting within another RetainScope 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 startKeepingExitedValues to make this scope start keeping exited values state before any content is transiently removed. When the transiently removed content is restored, call stopKeepingExitedValues after all content has been restored. You can use Recomposer.scheduleFrameEndCallback or 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.

Functions

public fun setParentRetainStateProvider(parent: RetainStateProvider)

Calling this function will automatically mirror the state of isKeepingExitedValues to match parent's state. This is an addition to requests made on the ControlledRetainScope, so keeping exited values is a function of whether the parent is keeping exited values OR this scope has been requested to keep exited values.

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

public fun startKeepingExitedValues(): Unit

Indicates that this scope should keep retained values that exit the composition. If this scope is already in this mode, the scope 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 stopKeepingExitedValues before the kept values will be retired.

public fun stopKeepingExitedValues(): Unit

Stops keeping values that have exited the composition. This function cancels a request that previously began by calling startKeepingExitedValues. If startKeepingExitedValues has been called more than stopKeepingExitedValues, the scope will continue to keep retained values that have exited the composition until stopKeepingExitedValues has been called the same number of times as startKeepingExitedValues.