ControlledComposition

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

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

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

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.

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.

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

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.

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

@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.

@InternalComposeApi public fun disposeUnusedMovableContent(state: MovableContentState)

Dispose the value state that is no longer needed.

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 disposed.

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.

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.

public fun abandonChanges()

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

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.

@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.

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.

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