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

Composer

public sealed interface Composer


Composer is the interface that is targeted by the Compose Kotlin compiler plugin and used by code generation helpers. It is highly recommended that direct calls these be avoided as the runtime assumes that the calls are generated by the compiler and contain only a minimum amount of state validation.

Summary

Nested types

public static class Composer.Companion

Public methods

abstract void
@ComposeCompilerApi
<V extends Object, T extends Object> apply(
    @NonNull V value,
    @ExtensionFunctionType @NonNull Function2<@NonNull T, @NonNull V, Unit> block
)

A Compose compiler plugin API.

abstract @NonNull CompositionContext

A Compose internal function.

abstract boolean

A Compose compiler plugin API.

default boolean
@ComposeCompilerApi
changed(boolean value)

A Compose compiler plugin API.

default boolean

A Compose compiler plugin API.

default boolean

A Compose compiler plugin API.

default boolean

A Compose compiler plugin API.

default boolean

A Compose compiler plugin API.

default boolean

A Compose compiler plugin API.

default boolean

A Compose compiler plugin API.

default boolean

A Compose compiler plugin API.

default boolean

A Compose compiler plugin API.

abstract void

A tooling API function.

abstract @NonNull T

A Compose internal function.

abstract void
@ComposeCompilerApi
<T extends Object> createNode(@NonNull Function0<@NonNull T> factory)

A Compose compiler plugin API.

abstract void

A Compose compiler plugin API.

abstract void

A Compose compiler plugin API.

abstract void

Disable the collection of source information, that may introduce groups to store the source information, in order to be able to more accurately calculate the actual number of groups a composable function generates in a release build.

abstract void

A Compose compiler plugin API.

abstract void

A Compose compiler plugin API.

abstract void

A Compose compiler plugin API.

abstract void

A Compose compiler plugin API.

abstract void

A Compose internal function.

abstract void

A Compose compiler plugin API.

abstract ScopeUpdateScope

A Compose compiler plugin API.

abstract void

A Compose compiler plugin API.

abstract void

Compose compiler plugin API.

abstract @NonNull Applier<@NonNull ?>

A Compose compiler plugin API.

abstract @NonNull CoroutineContext

A Compose internal function.

abstract @NonNull ControlledComposition

The composition that is used to control this composer.

abstract @NonNull CompositionData

A tooling API function.

abstract int

A Compose internal property.

abstract @NonNull CompositionLocalMap

Returns the active set of CompositionLocals at the current position in the composition hierarchy.

abstract int

A Compose compiler plugin API.

abstract boolean

A Compose compiler plugin API.

abstract boolean

A Compose compiler plugin API.

abstract RecomposeScope

A Compose internal property.

abstract Object

A Compose compiler plugin API.

abstract boolean

A Compose compiler plugin API.

abstract void

A Compose internal API.

abstract void

A Compose internal API.

abstract @NonNull Object

A Compose compiler plugin API.

abstract void

A Compose internal function.

abstract void

A Compose compiler plugin API.

abstract Object

A Compose compiler plugin API.

abstract void

A Compose compiler plugin API.

abstract void

A Compose compiler plugin API.

abstract void
sourceInformation(@NonNull String sourceInformation)

A Compose compiler plugin API.

abstract void

A compose compiler plugin API.

abstract void
sourceInformationMarkerStart(int key, @NonNull String sourceInformation)

A compose compiler plugin API.

abstract void

A Compose compiler plugin API.

abstract void

A Compose compiler plugin API.

abstract void

A Compose compiler plugin API.

abstract void
@InternalComposeApi
startProviders(@NonNull ProvidedValue[] values)

A Compose internal function.

abstract void

A Compose compiler plugin API.

abstract @NonNull Composer

A Compose compiler plugin API.

abstract void

A Compose compiler plugin API.

abstract void

A Compose compiler plugin API.

abstract void

A Compose compiler plugin API.

abstract void

A Compose compiler plugin API.

Extension functions

default final @NonNull Modifier

Materialize any instance-specific composed modifiers for applying to a raw tree node.

default final @NonNull T
@ComposeCompilerApi
<T extends Object> ComposerKt.cache(
    @NonNull Composer receiver,
    boolean invalid,
    @DisallowComposableCalls @NonNull Function0<@NonNull T> block
)

A Compose compiler plugin API.

Public methods

apply

@ComposeCompilerApi
abstract void <V extends Object, T extends Object> apply(
    @NonNull V value,
    @ExtensionFunctionType @NonNull Function2<@NonNull T, @NonNull V, Unit> block
)

A Compose compiler plugin API. DO NOT call directly.

Schedule block to called with value. This is intended to update the node generated by createNode to changes discovered by composition.

Parameters
@NonNull V value

the new value to be set into some property of the node.

@ExtensionFunctionType @NonNull Function2<@NonNull T, @NonNull V, Unit> block

the block that sets the some property of the node to value.

buildContext

@InternalComposeApi
abstract @NonNull CompositionContext buildContext()

A Compose internal function. DO NOT call directly.

Build a composition context that can be used to created a subcomposition. A composition reference is used to communicate information from this composition to the subcompositions such as the all the CompositionLocals provided at the point the reference is created.

changed

@ComposeCompilerApi
abstract boolean changed(Object value)

A Compose compiler plugin API. DO NOT call directly.

Check value is different than the value used in the previous composition. This is used, for example, to check parameter values to determine if they have changed.

Parameters
Object value

the value to check

Returns
boolean

true if the value if equals of the previous value returns false when passed value.

changed

@ComposeCompilerApi
default boolean changed(boolean value)

A Compose compiler plugin API. DO NOT call directly.

Check value is different than the value used in the previous composition. This is used, for example, to check parameter values to determine if they have changed.

This overload is provided to avoid boxing value to compare with a potentially boxed version of value in the composition state.

Parameters
boolean value

the value to check

Returns
boolean

true if the value if equals of the previous value returns false when passed value.

changed

@ComposeCompilerApi
default boolean changed(byte value)

A Compose compiler plugin API. DO NOT call directly.

Check value is different than the value used in the previous composition. This is used, for example, to check parameter values to determine if they have changed.

This overload is provided to avoid boxing value to compare with a potentially boxed version of value in the composition state.

Parameters
byte value

the value to check

Returns
boolean

true if the value if equals of the previous value returns false when passed value.

changed

@ComposeCompilerApi
default boolean changed(char value)

A Compose compiler plugin API. DO NOT call directly.

Check value is different than the value used in the previous composition. This is used, for example, to check parameter values to determine if they have changed.

This overload is provided to avoid boxing value to compare with a potentially boxed version of value in the composition state.

Parameters
char value

the value to check

Returns
boolean

true if the value if equals of the previous value returns false when passed value.

changed

@ComposeCompilerApi
default boolean changed(double value)

A Compose compiler plugin API. DO NOT call directly.

Check value is different than the value used in the previous composition. This is used, for example, to check parameter values to determine if they have changed.

This overload is provided to avoid boxing value to compare with a potentially boxed version of value in the composition state.

Parameters
double value

the value to check

Returns
boolean

true if the value if equals of the previous value returns false when passed value.

changed

@ComposeCompilerApi
default boolean changed(float value)

A Compose compiler plugin API. DO NOT call directly.

Check value is different than the value used in the previous composition. This is used, for example, to check parameter values to determine if they have changed.

This overload is provided to avoid boxing value to compare with a potentially boxed version of value in the composition state.

Parameters
float value

the value to check

Returns
boolean

true if the value if equals of the previous value returns false when passed value.

changed

@ComposeCompilerApi
default boolean changed(int value)

A Compose compiler plugin API. DO NOT call directly.

Check value is different than the value used in the previous composition. This is used, for example, to check parameter values to determine if they have changed.

This overload is provided to avoid boxing value to compare with a potentially boxed version of value in the composition state.

Parameters
int value

the value to check

Returns
boolean

true if the value if equals of the previous value returns false when passed value.

changed

@ComposeCompilerApi
default boolean changed(long value)

A Compose compiler plugin API. DO NOT call directly.

Check value is different than the value used in the previous composition. This is used, for example, to check parameter values to determine if they have changed.

This overload is provided to avoid boxing value to compare with a potentially boxed version of value in the composition state.

Parameters
long value

the value to check

Returns
boolean

true if the value if equals of the previous value returns false when passed value.

changed

@ComposeCompilerApi
default boolean changed(short value)

A Compose compiler plugin API. DO NOT call directly.

Check value is different than the value used in the previous composition. This is used, for example, to check parameter values to determine if they have changed.

This overload is provided to avoid boxing value to compare with a potentially boxed version of value in the composition state.

Parameters
short value

the value to check

Returns
boolean

true if the value if equals of the previous value returns false when passed value.

changedInstance

@ComposeCompilerApi
default boolean changedInstance(Object value)

A Compose compiler plugin API. DO NOT call directly.

Check value is different than the value used in the previous composition using === instead of == equality. This is used, for example, to check parameter values to determine if they have changed for values that use value equality but, for correct behavior, the composer needs reference equality.

Parameters
Object value

the value to check

Returns
boolean

true if the value is === equal to the previous value and returns false when value is different.

collectParameterInformation

abstract void collectParameterInformation()

A tooling API function. DO NOT call directly.

Called by the inspector to inform the composer that it should collect additional information about call parameters. By default, only collect parameter information for scopes that are recordUsed has been called on. If collectParameterInformation is called it will attempt to collect all calls even if the runtime doesn't need them.

WARNING: calling this will result in a significant number of additional allocations that are typically avoided.

consume

@InternalComposeApi
abstract @NonNull T <T extends Object> consume(@NonNull CompositionLocal<@NonNull T> key)

A Compose internal function. DO NOT call directly.

Return the CompositionLocal value associated with key. This is the primitive function used to implement CompositionLocal.current.

Parameters
@NonNull CompositionLocal<@NonNull T> key

the CompositionLocal value to be retrieved.

createNode

@ComposeCompilerApi
abstract void <T extends Object> createNode(@NonNull Function0<@NonNull T> factory)

A Compose compiler plugin API. DO NOT call directly.

Report the factory that will be used to create the node that will be generated into the tree implied by the composition. This will only be called if inserting is is true.

Parameters
@NonNull Function0<@NonNull T> factory

a factory function that will generate a node that will eventually be supplied to applier though Applier.insertBottomUp and Applier.insertTopDown.

deactivateToEndGroup

@ComposeCompilerApi
abstract void deactivateToEndGroup(boolean changed)

A Compose compiler plugin API. DO NOT call directly.

Deactivates the content to the end of the group by treating content as if it was deleted and replaces all slot table entries for calls to cache to be Empty. This must be called as the first call for a group.

disableReusing

@ComposeCompilerApi
abstract void disableReusing()

A Compose compiler plugin API. DO NOT call directly.

Temporarily disable reusing if it is enabled.

disableSourceInformation

@TestOnly
abstract void disableSourceInformation()

Disable the collection of source information, that may introduce groups to store the source information, in order to be able to more accurately calculate the actual number of groups a composable function generates in a release build.

This function is only safe to call in a test and will produce incorrect composition results if called on a composer not under test.

enableReusing

@ComposeCompilerApi
abstract void enableReusing()

A Compose compiler plugin API. DO NOT call directly.

Reenable reusing if it was previously enabled before the last call to disableReusing.

endDefaults

@ComposeCompilerApi
abstract void endDefaults()

A Compose compiler plugin API. DO NOT call directly.

Called at the end of defaults group.

See also
startDefaults

endMovableGroup

@ComposeCompilerApi
abstract void endMovableGroup()

A Compose compiler plugin API. DO NOT call directly.

Called at the end of a movable group.

endNode

@ComposeCompilerApi
abstract void endNode()

A Compose compiler plugin API. DO NOT call directly.

Called at the end of a node group.

endProviders

@InternalComposeApi
abstract void endProviders()

A Compose internal function. DO NOT call directly.

End the provider group.

See also
startProviders

endReplaceableGroup

@ComposeCompilerApi
abstract void endReplaceableGroup()

A Compose compiler plugin API. DO NOT call directly.

Called at the end of a replacable group.

endRestartGroup

@ComposeCompilerApi
abstract ScopeUpdateScope endRestartGroup()

A Compose compiler plugin API. DO NOT call directly.

Called to end a restart group.

endReusableGroup

@ComposeCompilerApi
abstract void endReusableGroup()

A Compose compiler plugin API. DO NOT call directly.

Called at the end of a reusable group.

endToMarker

@ComposeCompilerApi
abstract void endToMarker(int marker)

Compose compiler plugin API. DO NOT call directly.

Ends all the groups up to but not including the group that is the parent group when currentMarker was called to produce marker. All groups ended must have been started with either startReplaceableGroup or startMovableGroup. Ending other groups can cause the state of the composer to become inconsistent.

getApplier

abstract @NonNull Applier<@NonNull ?> getApplier()

A Compose compiler plugin API. DO NOT call directly.

Changes calculated and recorded during composition and are sent to applier which makes the physical changes to the node tree implied by a composition.

Composition has two discrete phases, 1) calculate and record changes and 2) making the changes via the applier. While a Composable functions is executing, none of the applier methods are called. The recorded changes are sent to the applier all at once after all Composable functions have completed.

getApplyCoroutineContext

@TestOnly
abstract @NonNull CoroutineContext getApplyCoroutineContext()

A Compose internal function. DO NOT call directly.

The coroutine context for the composition. This is used, for example, to implement LaunchedEffect. This context is managed by the Recomposer.

getComposition

@TestOnly
abstract @NonNull ControlledComposition getComposition()

The composition that is used to control this composer.

getCompositionData

abstract @NonNull CompositionData getCompositionData()

A tooling API function. DO NOT call directly.

The data stored for the composition. This is used by Compose tools, such as the preview and the inspector, to display or interpret the result of composition.

getCompoundKeyHash

abstract int getCompoundKeyHash()

A Compose internal property. DO NOT call directly. Use currentCompositeKeyHash instead.

This a hash value used to coordinate map externally stored state to the composition. For example, this is used by saved instance state to preserve state across activity lifetime boundaries.

This value is not likely to be unique but is not guaranteed unique. There are known cases, such as for loops without a key, where the runtime does not have enough information to make the compound key hash unique.

getCurrentCompositionLocalMap

abstract @NonNull CompositionLocalMap getCurrentCompositionLocalMap()

Returns the active set of CompositionLocals at the current position in the composition hierarchy. This is a lower level API that can be used to export and access CompositionLocal values outside of Composition.

This API does not track reads of CompositionLocals and does not automatically dispatch new values to previous readers when the value of a CompositionLocal changes. To use this API as intended, you must set up observation manually. This means:

Most applications shouldn't use this API directly, and should instead use CompositionLocal.current.

getCurrentMarker

abstract int getCurrentMarker()

A Compose compiler plugin API. DO NOT call directly.

Return a marker for the current group that can be used in a call to endToMarker.

getDefaultsInvalid

abstract boolean getDefaultsInvalid()

A Compose compiler plugin API. DO NOT call directly.

Reflects whether the default parameter block of a Composable function is valid. This is false if a State object read in the startDefaults group was modified since the last time the Composable function was run.

getInserting

abstract boolean getInserting()

A Compose compiler plugin API. DO NOT call directly.

Reflects that a new part of the composition is being created, that is, the composition will insert new nodes into the resulting tree.

getRecomposeScope

abstract RecomposeScope getRecomposeScope()

A Compose internal property. DO NOT call directly. Use currentRecomposeScope instead.

The invalidation current invalidation scope. An new invalidation scope is created whenever startRestartGroup is called. when this scope's RecomposeScope.invalidate is called then lambda supplied to endRestartGroup's ScopeUpdateScope will be scheduled to be run.

getRecomposeScopeIdentity

abstract Object getRecomposeScopeIdentity()

A Compose compiler plugin API. DO NOT call directly.

Return an object that can be used to uniquely identity of the current recomposition scope. This identity will be the same even if the recompose scope instance changes.

This is used internally by tooling track composable function invocations.

getSkipping

abstract boolean getSkipping()

A Compose compiler plugin API. DO NOT call directly.

Reflects whether the Composable function can skip. Even if a Composable function is called with the same parameters it might still need to run because, for example, a new value was provided for a CompositionLocal created by staticCompositionLocalOf.

insertMovableContent

@InternalComposeApi
abstract void insertMovableContent(
    @NonNull MovableContent<@NonNull ?> value,
    Object parameter
)

A Compose internal API. DO NOT call directly.

Request movable content be inserted at the current location. This will schedule with the root composition parent a call to insertMovableContent with the correct MovableContentState if one was released in another part of composition.

insertMovableContentReferences

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

A Compose internal API. DO NOT call directly.

Perform a late composition that adds to the current late apply that will insert the given references to MovableContent into the composition. If a MovableContent is paired then this is a request to move a released MovableContent from a different location or from a different composition. If it is not paired (i.e. the second MovableContentStateReference is null) then new state for the MovableContent is inserted into the composition.

joinKey

@ComposeCompilerApi
abstract @NonNull Object joinKey(Object left, Object right)

A Compose compiler plugin API. DO NOT call directly.

Produce an object that will compare equal an iff left and right compare equal to some left and right of a previous call to joinKey. This is used by key to handle multiple parameters. Since the previous composition stored left and right in a "join key" object this call is used to return the previous value without an allocation instead of blindly creating a new value that will be immediately discarded.

Parameters
Object left

the first part of a a joined key.

Object right

the second part of a joined key.

Returns
@NonNull Object

an object that will compare equal to a value previously returned by joinKey iff left and right compare equal to the left and right passed to the previous call.

recordSideEffect

@InternalComposeApi
abstract void recordSideEffect(@NonNull Function0<Unit> effect)

A Compose internal function. DO NOT call directly.

Record a function to call when changes to the corresponding tree are applied to the applier. This is used to implement SideEffect.

Parameters
@NonNull Function0<Unit> effect

a lambda to invoke after the changes calculated up to this point have been applied.

recordUsed

@InternalComposeApi
abstract void recordUsed(@NonNull RecomposeScope scope)

A Compose compiler plugin API. DO NOT call directly.

Mark scope as used. endReplaceableGroup will return null unless recordUsed is called on the corresponding scope. This is called implicitly when State objects are read during composition is called when currentRecomposeScope is called in the Composable function.

rememberedValue

@ComposeCompilerApi
abstract Object rememberedValue()

A Compose compiler plugin API. DO NOT call directly.

Remember a value into the composition state. This is a primitive method used to implement remember.

Returns
Object

Composer.Empty when inserting is true or the value passed to updateRememberedValue from the previous composition.

See also
cache

skipCurrentGroup

@ComposeCompilerApi
abstract void skipCurrentGroup()

A Compose compiler plugin API. DO NOT call directly.

Skips the current group. This called by the compiler to indicate that the current group can be skipped, for example, this is generated to skip the startDefaults group the default group is was not invalidated.

skipToGroupEnd

@ComposeCompilerApi
abstract void skipToGroupEnd()

A Compose compiler plugin API. DO NOT call directly.

Skips the composer to the end of the current group. This generated by the compiler to when the body of a Composable function can be skipped typically because the parameters to the function are equal to the values passed to it in the previous composition.

sourceInformation

abstract void sourceInformation(@NonNull String sourceInformation)

A Compose compiler plugin API. DO NOT call directly.

Record the source information string for a group. This must be immediately called after the start of a group.

Parameters
@NonNull String sourceInformation

An string value to that provides the compose tools enough information to calculate the source location of calls to composable functions.

sourceInformationMarkerEnd

abstract void sourceInformationMarkerEnd()

A compose compiler plugin API. DO NOT call directly.

Record the end of the marked source information range.

sourceInformationMarkerStart

abstract void sourceInformationMarkerStart(int key, @NonNull String sourceInformation)

A compose compiler plugin API. DO NOT call directly.

Record a source information marker. This marker can be used in place of a group that would have contained the information but was elided as the compiler plugin determined the group was not necessary such as when a function is marked with ReadOnlyComposable.

Parameters
int key

A compiler generated key based on the source location of the call.

@NonNull String sourceInformation

An string value to that provides the compose tools enough information to calculate the source location of calls to composable functions.

startDefaults

@ComposeCompilerApi
abstract void startDefaults()

A Compose compiler plugin API. DO NOT call directly.

Called to start the group that calculates the default parameters of a Composable function.

This method is called near the beginning of a Composable function with default parameters and surrounds the remembered values or Composable calls necessary to produce the default parameters. For example, for model: Model = remember { DefaultModel() } the call to remember is called inside a startDefaults group.

startMovableGroup

@ComposeCompilerApi
abstract void startMovableGroup(int key, Object dataKey)

A Compose compiler plugin API. DO NOT call directly.

Start a movable group. A movable group is one that can be moved based on the value of dataKey which is typically supplied by the key pseudo compiler function.

A movable group implements the semantics of key which allows the state and nodes generated by a loop to move with the composition implied by the key passed to key.

Parameters
int key

A compiler generated key based on the source location of the call.

startNode

@ComposeCompilerApi
abstract void startNode()

A Compose compiler plugin API. DO NOT call directly.

Start a group that tracks a the code that will create or update a node that is generated as part of the tree implied by the composition.

startProviders

@InternalComposeApi
abstract void startProviders(@NonNull ProvidedValue[] values)

A Compose internal function. DO NOT call directly.

Provide the given values for the associated CompositionLocal keys. This is the primitive function used to implement CompositionLocalProvider.

Parameters
@NonNull ProvidedValue[] values

an array of value to provider key pairs.

startReplaceableGroup

@ComposeCompilerApi
abstract void startReplaceableGroup(int key)

A Compose compiler plugin API. DO NOT call directly.

Start a replacable group. A replacable group is a group that cannot be moved during execution and can only either inserted, removed, or replaced. For example, the group created by most control flow constructs such as an if statement are replacable groups.

Parameters
int key

A compiler generated key based on the source location of the call.

startRestartGroup

@ComposeCompilerApi
abstract @NonNull Composer startRestartGroup(int key)

A Compose compiler plugin API. DO NOT call directly.

Called to record a group for a Composable function and starts a group that can be recomposed on demand based on the lambda passed to updateScope when endRestartGroup is called

Parameters
int key

A compiler generated key based on the source location of the call.

Returns
@NonNull Composer

the instance of the composer to use for the rest of the function.

startReusableGroup

@ComposeCompilerApi
abstract void startReusableGroup(int key, Object dataKey)

A Compose compiler plugin API. DO NOT call directly.

Start a reuse group. Unlike a movable group, in a reuse group if the dataKey changes the composition shifts into a reusing state cause the composer to act like it is inserting (e.g. cache acts as if all values are invalid, changed always returns true, etc.) even though it is recomposing until it encounters a reusable node. If the node is reusable it temporarily shifts into recomposition for the node and then shifts back to reusing for the children. If a non-reusable node is generated the composer shifts to inserting for the node and all of its children.

Parameters
int key

An compiler generated key based on the source location of the call.

Object dataKey

A key provided by the ReusableContent composable function that is used to determine if the composition shifts into a reusing state for this group.

startReusableNode

@ComposeCompilerApi
abstract void startReusableNode()

A Compose compiler plugin API. DO NOT call directly.

Start a group that tracks a the code that will create or update a node that is generated as part of the tree implied by the composition. A reusable node can be reused in a reusable group even if the group key is changed.

updateRememberedValue

@ComposeCompilerApi
abstract void updateRememberedValue(Object value)

A Compose compiler plugin API. DO NOT call directly.

Update the remembered value correspond to the previous call to rememberedValue. The value will be returned by rememberedValue for the next composition.

useNode

@ComposeCompilerApi
abstract void useNode()

A Compose compiler plugin API. DO NOT call directly.

Report that the node is still being used. This will be called in the same location as the corresponding createNode when inserting is false.

Extension functions

ComposedModifierKt.materialize

@<Error class: unknown class>
default final @NonNull Modifier ComposedModifierKt.materialize(
    @NonNull Composer receiver,
    @NonNull Modifier modifier
)

Materialize any instance-specific composed modifiers for applying to a raw tree node. Call right before setting the returned modifier on an emitted node. You almost certainly do not need to call this function directly.

ComposerKt.cache

@ComposeCompilerApi
default final @NonNull T <T extends Object> ComposerKt.cache(
    @NonNull Composer receiver,
    boolean invalid,
    @DisallowComposableCalls @NonNull Function0<@NonNull T> block
)

A Compose compiler plugin API. DO NOT call directly.

Cache, that is remember, a value in the composition data of a composition. This is used to implement remember and used by the compiler plugin to generate more efficient calls to remember when it determines these optimizations are safe.