ControlledComposition

A controlled composition is a Composition that can be directly controlled by the caller.

This is the interface used by the Recomposer to control how and when a composition is invalidated and subsequently recomposed.

Normally a composition is controlled by the Recomposer but it is often more efficient for tests to take direct control over a composition by calling ControlledComposition instead of Composition.

See also
ControlledComposition

Summary

Public functions
Unit

Abandon current changes and reset composition state.
Cmn
Unit

Apply the changes calculated during setContent or recompose.
Cmn
Unit

Apply change that must occur after the main bulk of changes have been applied.
Cmn
Unit

Call when all changes, including late changes, have been applied.
Cmn
Unit
composeContent(content: @Composable () -> Unit)

Called by the parent composition in response to calling setContent.
Cmn
R
<R : Any?> delegateInvalidations(
    to: ControlledComposition?,
    groupIndex: Int,
    block: () -> R
)

Temporarily delegate all invalidations sent to this composition to the to composition.
Cmn
Unit

Dispose the value state that is no longer needed.
Cmn
ShouldPauseCallback?

Sets the shouldPause callback allowing a composition to be pausable if it is not null.
Cmn
Unit

Insert the given list of movable content with their paired state in potentially a different composition.
Cmn
Unit

Invalidate all invalidation scopes.
Cmn
Boolean
observesAnyOf(values: Set<Any>)

Returns true if any of the object instances in values is observed by this composition.
Cmn
Unit
prepareCompose(block: () -> Unit)

Execute block with isComposing set temporarily to true.
Cmn
Boolean

Recompose the composition to calculate any changes necessary to the composition state and the tree maintained by the applier.
Cmn
Unit

Record the values that were modified after the last call to recompose or from the initial call to composeContent.
Cmn
Unit
recordReadOf(value: Any)

Record that value has been read.
Cmn
Unit

Record that value has been modified.
Cmn
Unit

Throws an exception if the internal state of the composer has been corrupted and is no longer consistent.
Cmn

Public properties
Boolean

True after composeContent or recompose has been called and applyChanges is expected as the next call.
Cmn
Boolean

True if the composition is actively compositing such as when actively in a call to composeContent or recompose.
Cmn

Extension properties
CoroutineContext

The CoroutineContext that should be used to perform concurrent recompositions of this ControlledComposition when used in an environment supporting concurrent composition.
Cmn

Inherited functions
From androidx.compose.runtime.Composition
Unit

Clear the hierarchy that was created from the composition and release resources allocated for composition.
Cmn
Unit
setContent(content: @Composable () -> Unit)

Update the composition with the content described by the content composable.
Cmn

Inherited properties
From androidx.compose.runtime.Composition
Boolean

Returns true if any pending invalidations have been scheduled.
Cmn
Boolean

True if dispose has been called.
Cmn

Public functions

abandonChanges

Cmn
Added in 1.7.0
fun abandonChanges(): Unit

Abandon current changes and reset composition state. Called when recomposer cannot proceed with current recomposition loop and needs to reset composition.

applyChanges

Cmn
Added in 1.0.0
fun applyChanges(): Unit

Apply the changes calculated during setContent or recompose. If an exception is thrown by applyChanges the composition is irreparably damaged and should be disposed.

applyLateChanges

Cmn
Added in 1.2.0
fun applyLateChanges(): Unit

Apply change that must occur after the main bulk of changes have been applied. Late changes are the result of inserting movable content and it must be performed after applyChanges because, for content that have moved must be inserted only after it has been removed from the previous location. All deletes must be executed before inserts. To ensure this, all deletes are performed in applyChanges and all inserts are performed in applyLateChanges.

changesApplied

Cmn
Added in 1.2.0
fun changesApplied(): Unit

Call when all changes, including late changes, have been applied. This signals to the composition that any transitory composition state can now be discarded. This is advisory only and a controlled composition will execute correctly when this is not called.

composeContent

Cmn
Added in 1.0.0
fun composeContent(content: @Composable () -> Unit): Unit

Called by the parent composition in response to calling setContent. After this method the changes should be calculated but not yet applied. DO NOT call this method directly if this is interface is controlled by a Recomposer, either use setContent or Recomposer.composeInitial instead.

Parameters
content: @Composable () -> Unit

A composable function that describes the tree.

delegateInvalidations

Cmn
Added in 1.2.0
fun <R : Any?> delegateInvalidations(
    to: ControlledComposition?,
    groupIndex: Int,
    block: () -> R
): R

Temporarily delegate all invalidations sent to this composition to the to composition. This is used when movable content moves between compositions. The recompose scopes are not redirected until after the move occurs during applyChanges and applyLateChanges. This is used to compose as if the scopes have already been changed.

disposeUnusedMovableContent

Cmn
Added in 1.2.0
@InternalComposeApi
fun disposeUnusedMovableContent(state: MovableContentState): Unit

Dispose the value state that is no longer needed.

getAndSetShouldPauseCallback

Cmn
Added in 1.8.0-alpha06
fun getAndSetShouldPauseCallback(shouldPause: ShouldPauseCallback?): ShouldPauseCallback?

Sets the shouldPause callback allowing a composition to be pausable if it is not null. Setting the callback to null disables pausing.

Returns
ShouldPauseCallback?

the previous value of the callback which will be restored once the callback is no longer needed.
See also
PausableComposition

insertMovableContent

Cmn
Added in 1.2.0
@InternalComposeApi
fun insertMovableContent(
    references: List<Pair<MovableContentStateReference, MovableContentStateReference?>>
): Unit

Insert the given list of movable content with their paired state in potentially a different composition. If the second part of the pair is null then the movable content should be inserted as new. If second part of the pair has a value then the state should be moved into the referenced location and then recomposed there.

invalidateAll

Cmn
Added in 1.0.0
fun invalidateAll(): Unit

Invalidate all invalidation scopes. This is called, for example, by Recomposer when the Recomposer becomes active after a previous period of inactivity, potentially missing more granular invalidations.

observesAnyOf

Cmn 
fun observesAnyOf(values: Set<Any>): Boolean

Returns true if any of the object instances in values is observed by this composition. This allows detecting if values changed by a previous composition will potentially affect this composition.

prepareCompose

Cmn
Added in 1.0.0
fun prepareCompose(block: () -> Unit): Unit

Execute block with isComposing set temporarily to true. This allows treating invalidations reported during prepareCompose as if they happened while composing to avoid double invalidations when propagating changes from a parent composition while before composing the child composition.

recompose

Cmn
Added in 1.0.0
fun recompose(): Boolean

Recompose the composition to calculate any changes necessary to the composition state and the tree maintained by the applier. No changes have been made yet. Changes calculated will be applied when applyChanges is called.

Returns
Boolean

returns true if any changes are pending and applyChanges should be called.

recordModificationsOf

Cmn 
fun recordModificationsOf(values: Set<Any>): Unit

Record the values that were modified after the last call to recompose or from the initial call to composeContent. This should be called before recompose is called to record which parts of the composition need to be recomposed.

Parameters
values: Set<Any>

the set of values that have changed since the last composition.

recordReadOf

Cmn
Added in 1.0.0
fun recordReadOf(value: Any): Unit

Record that value has been read. This is used primarily by the Recomposer to inform the composer when the a MutableState instance has been read implying it should be observed for changes.

Parameters
value: Any

the instance from which a property was read

recordWriteOf

Cmn
Added in 1.0.0
fun recordWriteOf(value: Any): Unit

Record that value has been modified. This is used primarily by the Recomposer to inform the composer when the a MutableState instance been change by a composable function.

verifyConsistent

Cmn
Added in 1.0.0
@InternalComposeApi
fun verifyConsistent(): Unit

Throws an exception if the internal state of the composer has been corrupted and is no longer consistent. Used in testing the composer itself.

Public properties

hasPendingChanges

Cmn
Added in 1.0.0
val hasPendingChanges: Boolean

True after composeContent or recompose has been called and applyChanges is expected as the next call. An exception will be throw in composeContent or recompose is called while there are pending from the previous composition pending to be applied.

isComposing

Cmn
Added in 1.0.0
val isComposing: Boolean

True if the composition is actively compositing such as when actively in a call to composeContent or recompose.

Extension properties

recomposeCoroutineContext

Cmn 
@ExperimentalComposeApi
val ControlledComposition.recomposeCoroutineContext: CoroutineContext

The CoroutineContext that should be used to perform concurrent recompositions of this ControlledComposition when used in an environment supporting concurrent composition.

See Recomposer.runRecomposeConcurrentlyAndApplyChanges as an example of configuring such an environment.