Composer

open class Composer<N> : ComposerValidator
kotlin.Any
   ↳ androidx.compose.Composer

Implementation of a composer for mutable tree.

Summary

Public constructors

<init>(slotTable: SlotTable, applier: Applier<N>, recomposer: Recomposer)

Implementation of a composer for mutable tree.

Public methods

Unit

Discard a pending composition because an error was encountered during composition

Unit
apply(value: V, block: T.(V) -> Unit)

Schedule a change to be applied to a node's property.

Unit

Apply the changes to the tree that were collected during the last composition.

CompositionReference

Create or use a memoized CompositionReference instance at this position in the slot table.

Unit
call(key: Any, invalid: ComposerValidator.() -> Boolean, block: () -> Unit)

open Boolean
changed(value: T)

Determine if the current slot table value is equal to the given value, if true, the value is scheduled to be skipped during applyChanges and changes return false; otherwise applyChanges will update the slot table to value.

open Boolean
changed(value: Int)

Unit

Start collecting key source information.

Unit
createNode(factory: () -> T)

Schedule a node to be created and inserted at the current location.

Unit
emitNode(factory: () -> T)

Unit
emitNode(node: N)

Schedule the given node to be inserted.

Unit

Warning: This is expected to be executed by the compiler only and should not be called directly from source code.

Unit

End the current group.

Unit

Indicates the end of a "Movable Group" at the current execution position.

Unit

Called to end the node group.

Unit

Indicates the end of a "Replaceable Group" at the current execution position.

ScopeUpdateScope?

End a restart group.

Unit

End the composition.

Any
joinKey(left: Any?, right: Any?)

Create a composed key that can be used in calls to startGroup or startNode.

Any?

Return the next value in the slot table and advance the current location.

Boolean

Synchronously recompose all invalidated groups.

Unit

Skip a group.

Unit

Skip to the end of the group opened by startGroup.

Unit

Warning: This is expected to be executed by the compiler only and should not be called directly from source code.

Unit

Start a group with the given key.

Unit
startGroup(key: Int, dataKey: Any?)

Unit
startMovableGroup(key: Int, dataKey: Any?)

Inserts a "Movable Group" starting marker in the slot table at the current execution position.

Unit
startNode(key: Any)

Start emitting a node.

Unit

Inserts a "Replaceable Group" starting marker in the slot table at the current execution position.

Unit

Start a restart group.

Unit

Start the composition.

Unit
updateValue(value: Any?)

Schedule the current value in the slot table to be updated to value.

N

Return the instance of the node that was inserted at the given location.

Protected methods

Unit
composeRoot(block: () -> Unit)

Extension functions

From androidx.compose
T
Composer<N>.cache(valid: Boolean = true, block: () -> T)

Cache a value in the composition.

From androidx.ui.core
Modifier

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

Properties

Int

The number of changes that have been scheduled to be applied during applyChanges.

Int

Returns the hash of the compound key calculated as a combination of the keys of all the currently started groups via startGroup.

Boolean

Boolean

True if the composition is currently scheduling nodes to be inserted into the tree.

Recomposer

Manager for scheduling recompositions.

Boolean

True if the composition should be checking if the composable functions can be skipped.

SlotTable

Backing storage for the composition

Public constructors

<init>

Composer(
    slotTable: SlotTable,
    applier: Applier<N>,
    recomposer: Recomposer)

Implementation of a composer for mutable tree.

Public methods

abortRoot

fun abortRoot(): Unit

Discard a pending composition because an error was encountered during composition

apply

fun <V, T> apply(
    value: V,
    block: T.(V) -> Unit
): Unit

Schedule a change to be applied to a node's property. This change will be applied to the node that is the current node in the tree which was either created by createNode, emitted by emitNode or returned by useNode.

applyChanges

fun applyChanges(): Unit

Apply the changes to the tree that were collected during the last composition.

buildReference

fun buildReference(): CompositionReference

Create or use a memoized CompositionReference instance at this position in the slot table.

call

inline fun call(
    key: Any,
    invalid: ComposerValidator.() -> Boolean,
    block: () -> Unit
): Unit

Deprecated.

changed

open fun <T> changed(value: T): Boolean

Determine if the current slot table value is equal to the given value, if true, the value is scheduled to be skipped during applyChanges and changes return false; otherwise applyChanges will update the slot table to value. In either case the composer's slot table is advanced.

Parameters
value: T the value to be compared.

changed

open fun changed(value: Int): Boolean

collectKeySourceInformation

fun collectKeySourceInformation(): Unit

Start collecting key source information. This enables enables the tool API to be able to determine the source location of where groups and nodes are created.

createNode

fun <T : N> createNode(factory: () -> T): Unit

Schedule a node to be created and inserted at the current location. This is only valid to call when the composer is inserting.

emitNode

fun <T : N> emitNode(factory: () -> T): Unit

emitNode

fun emitNode(node: N): Unit

Schedule the given node to be inserted. This is only valid to call when the composer is inserting.

endDefaults

fun endDefaults(): Unit

Warning: This is expected to be executed by the compiler only and should not be called directly from source code. Call this API at your own risk.

endGroup

fun endGroup(): Unit

End the current group.

endMovableGroup

fun endMovableGroup(): Unit

Indicates the end of a "Movable Group" at the current execution position. A Movable Group is a group which can be moved or reordered between its siblings and retain slot table state, in addition to being removed or inserted. These groups are only valid when they are inserted as direct children of Container Groups. Movable Groups are more expensive than other groups because when they are encountered with a mismatched key in the slot table, they must be held on to temporarily until the entire parent group finishes execution in case it moved to a later position in the group. Movable groups are only inserted by the compiler as a result of calls to key.

Warning: This is expected to be executed by the compiler only and should not be called directly from source code. Call this API at your own risk.

endNode

fun endNode(): Unit

Called to end the node group.

endReplaceableGroup

fun endReplaceableGroup(): Unit

Indicates the end of a "Replaceable Group" at the current execution position. A Replaceable Group is a group which cannot be moved between its siblings, but can be removed or inserted. These groups are inserted by the compiler around branches of conditional logic in Composable functions such as if expressions, when expressions, early returns, and null-coalescing operators.

Warning: This is expected to be executed by the compiler only and should not be called directly from source code. Call this API at your own risk.

endRestartGroup

fun endRestartGroup(): ScopeUpdateScope?

End a restart group. If the recompose scope was marked used during composition then a ScopeUpdateScope is returned that allows attaching a lambda that will produce the same composition as was produced by this group (including calling startRestartGroup and endRestartGroup).

endRoot

fun endRoot(): Unit

End the composition. This should be called, and only be called, to end the first group in the composition.

joinKey

fun joinKey(
    left: Any?,
    right: Any?
): Any

Create a composed key that can be used in calls to startGroup or startNode. This will use the key stored at the current location in the slot table to avoid allocating a new key.

nextSlot

fun nextSlot(): Any?

Return the next value in the slot table and advance the current location.

recompose

fun recompose(): Boolean

Synchronously recompose all invalidated groups. This collects the changes which must be applied by applyChanges to have an effect.

skipCurrentGroup

fun skipCurrentGroup(): Unit

Skip a group. Skips the group at the current location. This is only valid to call if the composition is not inserting.

skipToGroupEnd

fun skipToGroupEnd(): Unit

Skip to the end of the group opened by startGroup.

startDefaults

fun startDefaults(): Unit

Warning: This is expected to be executed by the compiler only and should not be called directly from source code. Call this API at your own risk.

startGroup

fun startGroup(key: Int): Unit

Start a group with the given key. During recomposition if the currently expected group does not match the given key a group the groups emitted in the same parent group are inspected to determine if one of them has this key and that group the first such group is moved (along with any nodes emitted by the group) to the current position and composition continues. If no group with this key is found, then the composition shifts into insert mode and new nodes are added at the current position.

Parameters
key: Int The key for the group

startGroup

fun startGroup(
    key: Int,
    dataKey: Any?
): Unit

startMovableGroup

fun startMovableGroup(
    key: Int,
    dataKey: Any?
): Unit

Inserts a "Movable Group" starting marker in the slot table at the current execution position. A Movable Group is a group which can be moved or reordered between its siblings and retain slot table state, in addition to being removed or inserted. Movable Groups are more expensive than other groups because when they are encountered with a mismatched key in the slot table, they must be held on to temporarily until the entire parent group finishes execution in case it moved to a later position in the group. Movable groups are only inserted by the compiler as a result of calls to key.

A call to startMovableGroup must be matched with a corresponding call to endMovableGroup.

Warning: This is expected to be executed by the compiler only and should not be called directly from source code. Call this API at your own risk.

Parameters
key: Int The source-location-based key for the group. Expected to be unique among its siblings.
dataKey: Any? Additional identifying information to compound with key. If there are multiple values, this is expected to be compounded together with joinKey. Whatever value is passed in here is expected to have a meaningful equals and hashCode implementation.

startNode

fun startNode(key: Any): Unit

Start emitting a node. It is required that one of emitNode or createNode is called after startNode. Similar to startGroup, if, during recomposition, the current node does not have the provided key a node with that key is scanned for and moved into the current position if found, if no such node is found the composition switches into insert mode and a the node is scheduled to be inserted at the current location.

Parameters
key: Any the key for the node.

startReplaceableGroup

fun startReplaceableGroup(key: Int): Unit

Inserts a "Replaceable Group" starting marker in the slot table at the current execution position. A Replaceable Group is a group which cannot be moved between its siblings, but can be removed or inserted. These groups are inserted by the compiler around branches of conditional logic in Composable functions such as if expressions, when expressions, early returns, and null-coalescing operators.

A call to startReplaceableGroup must be matched with a corresponding call to endReplaceableGroup.

Warning: This is expected to be executed by the compiler only and should not be called directly from source code. Call this API at your own risk.

Parameters
key: Int The source-location-based key for the group. Expected to be unique among its siblings.

startRestartGroup

fun startRestartGroup(key: Int): Unit

Start a restart group. A restart group creates a recompose scope and sets it as the current recompose scope of the composition. If the recompose scope is invalidated then this group will be recomposed. A recompose scope can be invalidated by calling the lambda returned by androidx.compose.invalidate.

startRoot

fun startRoot(): Unit

Start the composition. This should be called, and only be called, as the first group in the composition.

updateValue

fun updateValue(value: Any?): Unit

Schedule the current value in the slot table to be updated to value.

Parameters
value: Any? the value to schedule to be written to the slot table.

useNode

fun useNode(): N

Return the instance of the node that was inserted at the given location. This is only valid to call when the composition is not inserting. This must be called at the same location as emitNode or createNode as called even if the value is unused.

Protected methods

composeRoot

protected fun composeRoot(block: () -> Unit): Unit

Properties

changeCount

val changeCount: Int

The number of changes that have been scheduled to be applied during applyChanges.

Slot table movement (skipping groups and nodes) will be coalesced so this number is possibly less than the total changes detected.

currentCompoundKeyHash

var currentCompoundKeyHash: Int

Returns the hash of the compound key calculated as a combination of the keys of all the currently started groups via startGroup.

defaultsInvalid

val defaultsInvalid: Boolean

inserting

var inserting: Boolean

True if the composition is currently scheduling nodes to be inserted into the tree. During first composition this is always true. During recomposition this is true when new nodes are being scheduled to be added to the tree.

recomposer

val recomposer: Recomposer

Manager for scheduling recompositions.

skipping

val skipping: Boolean

True if the composition should be checking if the composable functions can be skipped.

slotTable

val slotTable: SlotTable

Backing storage for the composition