ControlledRetainScope
-
Cmn
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.
Summary
Public constructors |
|
|---|---|
|
Cmn
|
Public functions |
||
|---|---|---|
open Any? |
getExitedValueOrDefault(key: Any, defaultIfAbsent: Any?)If this scope is currently keeping exited values and has a value previously created with the given |
Cmn
|
Unit |
Calling this function will automatically mirror the state of |
Cmn
|
Unit |
Indicates that this scope should keep retained values that exit the composition. |
Cmn
|
Unit |
Stops keeping values that have exited the composition. |
Cmn
|
Protected functions |
||
|---|---|---|
open Unit |
Called when this scope first starts to keep exited values (i.e. when |
Cmn
|
open Unit |
Called when this scope stops keeping exited values (i.e. when |
Cmn
|
open Unit |
saveExitingValue(key: Any, value: Any?)Invoked when a retained value is exiting composition while this scope is keeping exited values. |
Cmn
|
Inherited functions |
||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Inherited properties |
|||
|---|---|---|---|
|
Public constructors
Public functions
getExitedValueOrDefault
open fun getExitedValueOrDefault(key: Any, defaultIfAbsent: Any?): Any?
If this scope is currently keeping exited values and has a value previously created with the given keys, its original record is returned and removed from the list of exited kept objects that this scope is tracking.
| Parameters | |
|---|---|
key: Any |
The keys to resolve a retained value that has left composition |
defaultIfAbsent: Any? |
A value to be returned if there are no retained values that have exited composition and are being held by this RetainScope for the given |
| Returns | |
|---|---|
Any? |
A retained value for |
setParentRetainStateProvider
fun setParentRetainStateProvider(parent: RetainStateProvider): Unit
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.
startKeepingExitedValues
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.
stopKeepingExitedValues
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.
| Throws | |
|---|---|
kotlin.IllegalStateException |
if |
Protected functions
onStartKeepingExitedValues
protected open fun onStartKeepingExitedValues(): Unit
Called when this scope first starts to keep exited values (i.e. when isKeepingExitedValues transitions from false to true). When this is called, implementors should prepare to begin to store values they receive from saveExitingValue.
onStopKeepingExitedValues
protected open fun onStopKeepingExitedValues(): Unit
Called when this scope stops keeping exited values (i.e. when isKeepingExitedValues transitions from true to false). After this is called, all exited values that have been kept and not restored via getExitedValueOrDefault should be retired.
Implementors MUST invoke RetainObserver.onRetired for all exited and unrestored RememberObservers when this method is invoked.
saveExitingValue
protected open fun saveExitingValue(key: Any, value: Any?): Unit
Invoked when a retained value is exiting composition while this scope is keeping 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 getExitedValueOrDefault.
The given keys are not guaranteed to be unique. To handle duplicate keys, implementors should return retained values with the same keys from getExitedValueOrDefault in the opposite order they are received by saveExitingValue.
If the implementation of this scope does not accept this value into its kept exited object list, it MUST call RetainObserver.onRetired if value implements RetainObserver.