{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

ControlledComposition

public sealed interface ControlledComposition extends Composition


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 methods

abstract void

Apply the changes calculated during setContent or recompose.

abstract void

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

abstract void

Call when all changes, including late changes, have been applied.

abstract void
composeContent(@Composable @NonNull Function0<Unit> content)

Called by the parent composition in response to calling setContent.

abstract @NonNull R
<R extends Object> delegateInvalidations(
    ControlledComposition to,
    int groupIndex,
    @NonNull Function0<@NonNull R> block
)

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

abstract void

Dispose the value state that is no longer needed.

abstract boolean

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

abstract void

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

abstract void

Invalidate all invalidation scopes.

abstract boolean

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

abstract boolean

Returns true if any of the object instances in values is observed by this composition.

abstract void
prepareCompose(@NonNull Function0<Unit> block)

Execute block with isComposing set temporarily to true.

abstract boolean

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

abstract void

Record the values that were modified after the last call to recompose or from the initial call to composeContent.

abstract void

Record that value has been read.

abstract void

Record that value has been modified.

abstract void

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

Extension functions

default final @NonNull CoroutineContext

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

Inherited methods

From androidx.compose.runtime.Composition
abstract void

Clear the hierarchy that was created from the composition and release resources allocated for composition.

abstract boolean

Returns true if any pending invalidations have been scheduled.

abstract boolean

True if dispose has been called.

abstract void
setContent(@Composable @NonNull Function0<Unit> content)

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

Public methods

applyChanges

abstract void applyChanges()

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

abstract void applyLateChanges()

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

abstract void changesApplied()

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

abstract void composeContent(@Composable @NonNull Function0<Unit> content)

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
@Composable @NonNull Function0<Unit> content

A composable function that describes the tree.

delegateInvalidations

abstract @NonNull R <R extends Object> delegateInvalidations(
    ControlledComposition to,
    int groupIndex,
    @NonNull Function0<@NonNull R> block
)

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

@InternalComposeApi
abstract void disposeUnusedMovableContent(@NonNull MovableContentState state)

Dispose the value state that is no longer needed.

getHasPendingChanges

abstract boolean getHasPendingChanges()

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.

insertMovableContent

@InternalComposeApi
abstract void insertMovableContent(
    @NonNull List<@NonNull Pair<@NonNull MovableContentStateReferenceMovableContentStateReference>> references
)

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

abstract void invalidateAll()

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.

isComposing

abstract boolean isComposing()

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

observesAnyOf

abstract boolean observesAnyOf(@NonNull Set<@NonNull Object> values)

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

abstract void prepareCompose(@NonNull Function0<Unit> block)

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

abstract boolean recompose()

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

abstract void recordModificationsOf(@NonNull Set<@NonNull Object> values)

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
@NonNull Set<@NonNull Object> values

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

recordReadOf

abstract void recordReadOf(@NonNull Object value)

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
@NonNull Object value

the instance from which a property was read

recordWriteOf

abstract void recordWriteOf(@NonNull Object value)

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

@InternalComposeApi
abstract void verifyConsistent()

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

Extension functions

CompositionKt.getRecomposeCoroutineContext

@ExperimentalComposeApi
default final @NonNull CoroutineContext CompositionKt.getRecomposeCoroutineContext(
    @NonNull ControlledComposition receiver
)

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.