# ControlledComposition

Artifact: [androidx.compose.runtime:runtime](https://developer.android.com/jetpack/androidx/releases/compose-runtime) [View Source](https://cs.android.com/search?q=file:androidx/compose/runtime/Composition.kt+class:androidx.compose.runtime.ControlledComposition) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.0.0) Common/AllAndroid/JVMNative/C/iOSJavaScript
- Cmn

  ```
  sealed interface ControlledComposition : Composition
  ```

*** ** * ** ***

A controlled composition is a `https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composition` that can be directly controlled by the caller.

This is the interface used by the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/Recomposer` to control how and when a composition is invalidated and subsequently recomposed.

Normally a composition is controlled by the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/Recomposer` but it is often more efficient for tests to take direct control over a composition by calling `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition` instead of `https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composition`.

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition` |   |

## Summary

| ### Public functions |
|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#abandonChanges()()` Abandon current changes and reset composition state. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#applyChanges()()` Apply the changes calculated during `https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composition#setContent(kotlin.Function0)` or `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#recompose()`. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#applyLateChanges()()` Apply change that must occur after the main bulk of changes have been applied. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#changesApplied()()` Call when all changes, including late changes, have been applied. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#composeContent(kotlin.Function0)(content: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)` Called by the parent composition in response to calling `https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composition#setContent(kotlin.Function0)`. | Cmn |
| `R` | `<R : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html?> https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#delegateInvalidations(androidx.compose.runtime.ControlledComposition,kotlin.Int,kotlin.Function0)( to: https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition?, groupIndex: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, block: () -> R )` Temporarily delegate all invalidations sent to this composition to the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#delegateInvalidations(androidx.compose.runtime.ControlledComposition,kotlin.Int,kotlin.Function0)` composition. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/InternalComposeApi https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#disposeUnusedMovableContent(androidx.compose.runtime.MovableContentState)(state: https://developer.android.com/reference/kotlin/androidx/compose/runtime/MovableContentState)` Dispose the value state that is no longer needed. | Cmn |
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ShouldPauseCallback?` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#getAndSetShouldPauseCallback(androidx.compose.runtime.ShouldPauseCallback)(shouldPause: https://developer.android.com/reference/kotlin/androidx/compose/runtime/ShouldPauseCallback?)` Sets the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#getAndSetShouldPauseCallback(androidx.compose.runtime.ShouldPauseCallback)` callback allowing a composition to be pausable if it is not `null`. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/InternalComposeApi https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#insertMovableContent(kotlin.collections.List)( references: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-pair/index.html<https://developer.android.com/reference/kotlin/androidx/compose/runtime/MovableContentStateReference, https://developer.android.com/reference/kotlin/androidx/compose/runtime/MovableContentStateReference?>> )` Insert the given list of movable content with their paired state in potentially a different composition. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#invalidateAll()()` Invalidate all invalidation scopes. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#observesAnyOf(kotlin.collections.Set)(values: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-set/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html>)` Returns true if any of the object instances in `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#observesAnyOf(kotlin.collections.Set)` is observed by this composition. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#prepareCompose(kotlin.Function0)(block: () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)` Execute `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#prepareCompose(kotlin.Function0)` with `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#isComposing()` set temporarily to `true`. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#recompose()()` Recompose the composition to calculate any changes necessary to the composition state and the tree maintained by the applier. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#recordModificationsOf(kotlin.collections.Set)(values: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-set/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html>)` Record the values that were modified after the last call to `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#recompose()` or from the initial call to `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#composeContent(kotlin.Function0)`. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#recordReadOf(kotlin.Any)(value: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html)` Record that `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#recordReadOf(kotlin.Any)` has been read. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#recordWriteOf(kotlin.Any)(value: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html)` Record that `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#recordWriteOf(kotlin.Any)` has been modified. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `@https://developer.android.com/reference/kotlin/androidx/compose/runtime/InternalComposeApi https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#verifyConsistent()()` Throws an exception if the internal state of the composer has been corrupted and is no longer consistent. | Cmn |

| ### Public properties |
|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#hasPendingChanges()` True after `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#composeContent(kotlin.Function0)` or `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#recompose()` has been called and `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#applyChanges()` is expected as the next call. | Cmn |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#isComposing()` True if the composition is actively compositing such as when actively in a call to `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#composeContent(kotlin.Function0)` or `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#recompose()`. | Cmn |

| ### Inherited functions |
|---|
| From [androidx.compose.runtime.Composition](https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composition) |---|---|---| | `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composition#dispose()()` Clear the hierarchy that was created from the composition and release resources allocated for composition. | Cmn | | `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composition#setContent(kotlin.Function0)(content: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)` Update the composition with the content described by the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composition#setContent(kotlin.Function0)` composable. | Cmn | |

| ### Inherited properties |
|---|
| From [androidx.compose.runtime.Composition](https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composition) |---|---|---| | `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composition#hasInvalidations()` Returns true if any pending invalidations have been scheduled. | Cmn | | `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composition#isDisposed()` True if `https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composition#dispose()` has been called. | Cmn | |

## Public functions

### abandonChanges

Cmn Added in [1.7.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#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](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.0.0)

```
fun applyChanges(): Unit
```

Apply the changes calculated during `https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composition#setContent(kotlin.Function0)` or `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#recompose()`. If an exception is thrown by `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#applyChanges()` the composition is irreparably damaged and should be `https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composition#dispose()`d.

### applyLateChanges

Cmn Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#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 `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#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 `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#applyChanges()` and all inserts are performed in `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#applyLateChanges()`.

### changesApplied

Cmn Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#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](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.0.0)

```
fun composeContent(content: @Composable () -> Unit): Unit
```

Called by the parent composition in response to calling `https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composition#setContent(kotlin.Function0)`. 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 `https://developer.android.com/reference/kotlin/androidx/compose/runtime/Recomposer`, either use `https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composition#setContent(kotlin.Function0)` or `https://developer.android.com/reference/kotlin/androidx/compose/runtime/Recomposer#composeInitial(androidx.compose.runtime.ControlledComposition,kotlin.Function0)` instead.

| Parameters |
|---|---|
| `content: @https://developer.android.com/reference/kotlin/androidx/compose/runtime/Composable () -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | A composable function that describes the tree. |

### delegateInvalidations

Cmn Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.2.0)

```
fun <R : Any?> delegateInvalidations(
    to: ControlledComposition?,
    groupIndex: Int,
    block: () -> R
): R
```

Temporarily delegate all invalidations sent to this composition to the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#delegateInvalidations(androidx.compose.runtime.ControlledComposition,kotlin.Int,kotlin.Function0)` composition. This is used when movable content moves between compositions. The recompose scopes are not redirected until after the move occurs during `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#applyChanges()` and `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#applyLateChanges()`. This is used to compose as if the scopes have already been changed.

### disposeUnusedMovableContent

Cmn Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#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](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.8.0)

```
fun getAndSetShouldPauseCallback(shouldPause: ShouldPauseCallback?): ShouldPauseCallback?
```

Sets the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#getAndSetShouldPauseCallback(androidx.compose.runtime.ShouldPauseCallback)` callback allowing a composition to be pausable if it is not `null`. Setting the callback to `null` disables pausing.

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ShouldPauseCallback?` | the previous value of the callback which will be restored once the callback is no longer needed. |

| See also |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/runtime/PausableComposition` |   |

### insertMovableContent

Cmn Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#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](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.0.0)

```
fun invalidateAll(): Unit
```

Invalidate all invalidation scopes. This is called, for example, by `https://developer.android.com/reference/kotlin/androidx/compose/runtime/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 `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#observesAnyOf(kotlin.collections.Set)` 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](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.0.0)

```
fun prepareCompose(block: () -> Unit): Unit
```

Execute `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#prepareCompose(kotlin.Function0)` with `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#isComposing()` set temporarily to `true`. This allows treating invalidations reported during `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#prepareCompose(kotlin.Function0)` 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](https://developer.android.com/jetpack/androidx/releases/compose-runtime#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 `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#applyChanges()` is called.

| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | returns `true` if any changes are pending and `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#applyChanges()` should be called. |

### recordModificationsOf

Cmn

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

Record the values that were modified after the last call to `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#recompose()` or from the initial call to `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#composeContent(kotlin.Function0)`. This should be called before `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#recompose()` is called to record which parts of the composition need to be recomposed.

| Parameters |
|---|---|
| `values: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-set/index.html<https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html>` | the set of values that have changed since the last composition. |

### recordReadOf

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.0.0)

```
fun recordReadOf(value: Any): Unit
```

Record that `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#recordReadOf(kotlin.Any)` has been read. This is used primarily by the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/Recomposer` to inform the composer when the a `https://developer.android.com/reference/kotlin/androidx/compose/runtime/MutableState` instance has been read implying it should be observed for changes.

| Parameters |
|---|---|
| `value: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html` | the instance from which a property was read |

### recordWriteOf

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.0.0)

```
fun recordWriteOf(value: Any): Unit
```

Record that `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#recordWriteOf(kotlin.Any)` has been modified. This is used primarily by the `https://developer.android.com/reference/kotlin/androidx/compose/runtime/Recomposer` to inform the composer when the a `https://developer.android.com/reference/kotlin/androidx/compose/runtime/MutableState` instance been change by a composable function.

### verifyConsistent

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#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](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.0.0)

```
val hasPendingChanges: Boolean
```

True after `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#composeContent(kotlin.Function0)` or `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#recompose()` has been called and `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#applyChanges()` is expected as the next call. An exception will be throw in `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#composeContent(kotlin.Function0)` or `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#recompose()` is called while there are pending from the previous composition pending to be applied.

### isComposing

Cmn Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/compose-runtime#1.0.0)

```
val isComposing: Boolean
```

True if the composition is actively compositing such as when actively in a call to `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#composeContent(kotlin.Function0)` or `https://developer.android.com/reference/kotlin/androidx/compose/runtime/ControlledComposition#recompose()`.