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.
Functions
@ComposeCompilerApi public fun startReplaceableGroup(key: Int)
A Compose compiler plugin API. DO NOT call directly.
Start a replaceable group. A replaceable 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 replaceable groups.
Warning: Versions of the compiler that generate calls to this function also contain subtle
bug that does not generate a group around a loop containing code that just creates composable
lambdas (AnimatedContent from androidx.compose.animation, for example) which makes replacing
the group unsafe and the this must treat this like a movable group. startReplaceGroup was
added that will replace the group as described above and is only called by versions of the
compiler that correctly generate code around loops that create lambdas. This method is kept
to maintain compatibility with code generated by older versions of the compose compiler
plugin.
Parameters
| key | A compiler generated key based on the source location of the call. |
@ComposeCompilerApi public fun endReplaceableGroup()
A Compose compiler plugin API. DO NOT call directly.
Called at the end of a replaceable group.
@ComposeCompilerApi public fun startReplaceGroup(key: Int)
A Compose compiler plugin API. DO NOT call directly.
Start a replace group. A replace group is a group that cannot be moved during must only
either be inserted, removed, or replaced. For example, the group created by most control flow
constructs such as an if statement are replaceable groups.
Note: This method replaces startReplaceableGroup which is only generated by older versions
of the compose compiler plugin that predate the addition of this method. The runtime is now
required to replace the group if a different group is detected instead of treating it like a
movable group.
Parameters
| key | A compiler generated key based on the source location of the call. |
@ComposeCompilerApi public fun endReplaceGroup()
A Compose compiler plugin API. DO NOT call directly.
Called at the end of a replace group.
@ComposeCompilerApi public fun startMovableGroup(key: Int, dataKey: Any?)
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
| key | a compiler generated key based on the source location of the call. |
| dataKey | an additional object that is used as a second part of the key. This key produced from the keys parameter supplied to the key pseudo compiler function. |
@ComposeCompilerApi public fun endMovableGroup()
A Compose compiler plugin API. DO NOT call directly.
Called at the end of a movable group.
@ComposeCompilerApi public fun 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.
@ComposeCompilerApi public fun endDefaults()
A Compose compiler plugin API. DO NOT call directly.
Called at the end of defaults group.
@ComposeCompilerApi public fun startRestartGroup(key: Int): Composer
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
| key | A compiler generated key based on the source location of the call. |
Returns
| the instance of the composer to use for the rest of the function. |
@ComposeCompilerApi public fun endRestartGroup(): ScopeUpdateScope?
A Compose compiler plugin API. DO NOT call directly.
Called to end a restart group.
@InternalComposeApi public fun insertMovableContent(value: MovableContent<*>, parameter: Any?)
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.
@InternalComposeApi
public fun insertMovableContentReferences(
references: List<Pair<MovableContentStateReference, MovableContentStateReference?>>
)
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.
public fun sourceInformation(sourceInformation: String)
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
| sourceInformation | An string value to that provides the compose tools enough information to calculate the source location of calls to composable functions. |
public fun sourceInformationMarkerStart(key: Int, sourceInformation: String)
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
| key | A compiler generated key based on the source location of the call. |
| sourceInformation | An string value to that provides the compose tools enough information to calculate the source location of calls to composable functions. |
public fun sourceInformationMarkerEnd()
A compose compiler plugin API. DO NOT call directly.
Record the end of the marked source information range.
@ComposeCompilerApi public fun 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.
@ComposeCompilerApi public fun deactivateToEndGroup(changed: Boolean)
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.
@ComposeCompilerApi public fun 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.
@ComposeCompilerApi public fun 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.
@ComposeCompilerApi public fun 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.
@ComposeCompilerApi public fun <T> createNode(factory: () -> T)
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
| factory | a factory function that will generate a node that will eventually be supplied to applier though Applier.insertBottomUp and Applier.insertTopDown. |
@ComposeCompilerApi public fun 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.
@ComposeCompilerApi public fun endNode()
A Compose compiler plugin API. DO NOT call directly.
Called at the end of a node group.
@ComposeCompilerApi public fun startReusableGroup(key: Int, dataKey: Any?)
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
| key | An compiler generated key based on the source location of the call. |
| 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. |
@ComposeCompilerApi public fun endReusableGroup()
A Compose compiler plugin API. DO NOT call directly.
Called at the end of a reusable group.
@ComposeCompilerApi public fun disableReusing()
A Compose compiler plugin API. DO NOT call directly.
Temporarily disable reusing if it is enabled.
@ComposeCompilerApi public fun enableReusing()
A Compose compiler plugin API. DO NOT call directly.
Reenable reusing if it was previously enabled before the last call to disableReusing.
@ComposeCompilerApi public fun endToMarker(marker: Int)
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.
@ComposeCompilerApi public fun <V, T> apply(value: V, block: T.(V) -> Unit)
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
| value | the new value to be set into some property of the node. |
| block | the block that sets the some property of the node to value. |
@ComposeCompilerApi public fun joinKey(left: Any?, right: Any?): Any
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
| left | the first part of a a joined key. |
| right | the second part of a joined key. |
Returns
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. |
@ComposeCompilerApi public fun rememberedValue(): Any?
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
Composer.Empty when inserting is true or the value passed to updateRememberedValue from the previous composition. |
@ComposeCompilerApi public fun updateRememberedValue(value: Any?)
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.
@ComposeCompilerApi public fun changed(value: Any?): Boolean
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
| value | the value to check |
Returns
true if the value if equals of the previous value returns false when passed value. |
@ComposeCompilerApi public fun changed(value: Boolean): Boolean
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
| value | the value to check |
Returns
true if the value if equals of the previous value returns false when passed value. |
@ComposeCompilerApi public fun changed(value: Char): Boolean
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
| value | the value to check |
Returns
true if the value if equals of the previous value returns false when passed value. |
@ComposeCompilerApi public fun changed(value: Byte): Boolean
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
| value | the value to check |
Returns
true if the value if equals of the previous value returns false when passed value. |
@ComposeCompilerApi public fun changed(value: Short): Boolean
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
| value | the value to check |
Returns
true if the value if equals of the previous value returns false when passed value. |
@ComposeCompilerApi public fun changed(value: Int): Boolean
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
| value | the value to check |
Returns
true if the value if equals of the previous value returns false when passed value. |
@ComposeCompilerApi public fun changed(value: Float): Boolean
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
| value | the value to check |
Returns
true if the value if equals of the previous value returns false when passed value. |
@ComposeCompilerApi public fun changed(value: Long): Boolean
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
| value | the value to check |
Returns
true if the value if equals of the previous value returns false when passed value. |
@ComposeCompilerApi public fun changed(value: Double): Boolean
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
| value | the value to check |
Returns
true if the value if equals of the previous value returns false when passed value. |
@ComposeCompilerApi public fun changedInstance(value: Any?): Boolean
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
| value | the value to check |
Returns
true if the value is === equal to the previous value and returns false when value is different. |
@InternalComposeApi public fun recordUsed(scope: RecomposeScope)
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.
@InternalComposeApi public fun shouldExecute(parametersChanged: Boolean, flags: Int): Boolean
A Compose compiler plugin API. DO NOT call directly.
Generated by the compile to determine if the composable function should be executed. It may not execute if parameter has not changed and the nothing else is forcing the function to execute (such as its scope was invalidated or a static composition local it was changed) or the composition is pausable and the composition is pausing.
Parameters
| parametersChanged | true if the parameters to the composable function have changed. This is also true if the composition is inserting or if content is being reused. |
| flags | The $changed parameter that contains the forced recompose bit to allow the composer to disambiguate when the parameters changed due the execution being forced or if the parameters actually changed. This is only ambiguous in a PausableComposition and is necessary to determine if the function can be paused. The bits, other than 0, are reserved for future use (which would required the bit 31, which is unused in $changed values, to be set to indicate that the flags carry additional information). Passing the $changed flags directly, instead of masking the 0 bit, is more efficient as it allows less code to be generated per call to shouldExecute which is every called in every restartable function, as well as allowing for the API to be extended without a breaking changed. |
@InternalComposeApi public fun recordSideEffect(effect: () -> Unit)
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
| effect | a lambda to invoke after the changes calculated up to this point have been applied. |
@InternalComposeApi public fun <T> consume(key: CompositionLocal<T>): T
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
| key | the CompositionLocal value to be retrieved. |
@InternalComposeApi public fun startProviders(values: Array<out ProvidedValue<*>>)
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
| values | an array of value to provider key pairs. |
@InternalComposeApi public fun endProviders()
A Compose internal function. DO NOT call directly.
End the provider group.
@InternalComposeApi public fun startProvider(value: ProvidedValue<*>)
A Compose internal function. DO NOT call directly.
Provide the given value for the associated CompositionLocal key. This is the primitive
function used to implement CompositionLocalProvider.
Parameters
| value | a value to provider key pairs. |
@InternalComposeApi public fun endProvider()
A Compose internal function. DO NOT call directly.
End the provider group.
public fun 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.
@InternalComposeApi public fun buildContext(): CompositionContext
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.
@TestOnly public fun 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.
