---
title: "ControlledComposition"
description: "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]."
type: "interface"
---

<div class='type'>Interface</div>


<a id='references'></a>

<div class='sourceset sourceset-common'>Common</div>



```kotlin
public sealed interface ControlledComposition : 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`.


## Functions

```kotlin
public fun composeContent(content: @Composable () -> 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 | A composable function that describes the tree. |



```kotlin
public fun recordModificationsOf(values: Set<Any>)
```


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 | the set of values that have changed since the last composition. |



```kotlin
public 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.


```kotlin
public fun prepareCompose(block: () -> 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.


```kotlin
public fun recordReadOf(value: Any)
```


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 | the instance from which a property was read |



```kotlin
public fun recordWriteOf(value: Any)
```


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.


```kotlin
public 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

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



```kotlin
@InternalComposeApi
    public fun insertMovableContent(
        references: List<Pair<MovableContentStateReference, MovableContentStateReference?>>
    )
```


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.


```kotlin
@InternalComposeApi public fun disposeUnusedMovableContent(state: MovableContentState)
```


Dispose the value state that is no longer needed.


```kotlin
public fun applyChanges()
```


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


```kotlin
public fun 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`.


```kotlin
public fun 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.


```kotlin
public fun abandonChanges()
```


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


```kotlin
public fun 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.


```kotlin
@InternalComposeApi public fun 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.


```kotlin
public fun <R> 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.


```kotlin
public 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

| | |
| --- | --- |
|  | the previous value of the callback which will be restored once the callback is no longer needed. |