Compose Runtime

Fundamental building blocks of Compose's programming model and state management, and core runtime for the Compose Compiler Plugin to target.
Latest Update Current Stable Release Next Release Candidate Beta Release Alpha Release
June 16, 2021 - - 1.0.0-beta09 -

Structure

Compose is combination of 6 Maven Group Ids within androidx. Each Group contains a targeted subset of functionality, each with it's own set of release notes.

This table explains the groups and links to each set of release notes.

GroupDescription
compose.animationBuild animations in their Jetpack Compose applications to enrich the user experience.
compose.compilerTransform @Composable functions and enable optimizations with a Kotlin compiler plugin.
compose.foundationWrite Jetpack Compose applications with ready to use building blocks and extend foundation to build your own design system pieces.
compose.materialBuild Jetpack Compose UIs with ready to use Material Design Components. This is the higher level entry point of Compose, designed to provide components that match those described at www.material.io.
compose.runtimeFundamental building blocks of Compose's programming model and state management, and core runtime for the Compose Compiler Plugin to target.
compose.uiFundamental components of compose UI needed to interact with the device, including layout, drawing, and input.

Declaring dependencies

To add a dependency on Compose, you must add the Google Maven repository to your project. Read Google's Maven repository for more information.

Add the dependencies for the artifacts you need in the build.gradle file for your app or module:

Groovy

dependencies {
    implementation "androidx.compose.runtime:runtime:1.0.0-beta09"
    implementation "androidx.compose.runtime:runtime-livedata:1.0.0-beta09"
    implementation "androidx.compose.runtime:runtime-rxjava2:1.0.0-beta09"
}

android {
    buildFeatures {
        compose true
    }

    composeOptions {
        kotlinCompilerVersion "1.5.10"
        kotlinCompilerExtensionVersion "1.0.0-beta09"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

Kotlin

dependencies {
    implementation("androidx.compose.runtime:runtime:1.0.0-beta09")
    implementation("androidx.compose.runtime:runtime-livedata:1.0.0-beta09")
    implementation("androidx.compose.runtime:runtime-rxjava2:1.0.0-beta09")
}

android {
    buildFeatures {
        compose = true
    }

    composeOptions {
        kotlinCompilerVersion = "1.5.10"
        kotlinCompilerExtensionVersion = "1.0.0-beta09"
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }
}

For more information about dependencies, see Add build dependencies.

Feedback

Your feedback helps make Jetpack better. Let us know if you discover new issues or have ideas for improving this library. Please take a look at the existing issues in this library before you create a new one. You can add your vote to an existing issue by clicking the star button.

Create a new issue

See the Issue Tracker documentation for more information.

Version 1.0.0

Version 1.0.0-beta09

June 16, 2021

androidx.compose.runtime:runtime-*:1.0.0-beta09 is released. Version 1.0.0-beta09 contains these commits.

Added Profile Rules

This release adds profile rules to the following compose modules (I14ed6):

  • androidx.compose.animation
  • androidx.compose.animation-core
  • androidx.compose.foundation
  • androidx.compose.foundation-layout
  • androidx.compose.material
  • androidx.compose.material-ripple
  • androidx.compose.runtime
  • androidx.compose.ui
  • androidx.compose.ui.geometry
  • androidx.compose.ui.graphics
  • androidx.compose.ui.text
  • androidx.compose.ui.text
  • androidx.compose.ui.unit
  • androidx.compose.ui.util

What are profile rules?

  • Profile rules for a library are specified in a text file baseline-prof.txt located in the src/main or equivalent directory. The file specifies a rule per line, where a rule in this case is a pattern for matching to methods or classes in the library. The syntax for these rules is a superset of the human-readable ART profile format that is used when using adb shell profman --dump-classes-and-methods .... These rules take one of two forms to target either methods or classes.

  • A method rule will have the following pattern:

    <FLAGS><CLASS_DESCRIPTOR>-><METHOD_SIGNATURE>
    
  • And a class rule will have the following pattern:

    <CLASS_DESCRIPTOR>
    
  • Here <FLAGS> is one or more of the characters H, S, and P to indicate whether or not this method should be flagged as "Hot", "Startup", or "Post Startup".

  • The <CLASS_DESCRIPTOR> is the descriptor for the class that the targeted method belongs to. For example, the class androidx.compose.runtime.SlotTable would have a descriptor of Landroidx/compose/runtime/SlotTable;.

  • The <METHOD_SIGNATURE> is the signature of the method, and includes the name, parameter types, and return types of the method. For example, the method fun isPlaced(): Boolean on LayoutNode has the signature isPlaced()Z.

  • These patterns can have wildcards (**, *, and ?) in order to have a single rule encompass multiple methods or classes.

What do the rules do?

  • A method that has the flag H indicates that this method is a "hot" method, and should be compiled ahead of time.

  • A method that has the flag S indicates that it is a method which is called at startup, and should be compiled ahead of time to avoid the cost of compilation and interpreting the method at startup time.

  • A method that has the flag P indicates that it is a method which is called after startup.

  • A class that is present in this file indicates that it is used during startup and should be pre-allocated in the heap to avoid the cost of class loading.

How does this work?

  • Libraries can define these rules which will be packaged in AAR artifacts. When an APK is then built which includes these artifacts, these rules are merged together and the merged rules are used to build a compact binary ART profile that is specific to the APK. ART can then leverage this profile when the APK is installed on devices in order to ahead-of-time compile a specific subset of the application to improve the performance of the application, especially the first run. Note that this will have no effect on debuggable applications.

Version 1.0.0-beta08

June 2, 2021

androidx.compose.runtime:runtime-*:1.0.0-beta08 is released. Version 1.0.0-beta08 contains these commits.

API Changes

  • State<T> is now State<out T> (I69049)
  • ControlledComposition API change to enable recomposing changes in a recompose single pass. (Iaafd1, b/184173932)

Version 1.0.0-beta07

May 18, 2021

androidx.compose.runtime:runtime-*:1.0.0-beta07 is released. Version 1.0.0-beta07 contains these commits.

API Changes

  • Added new compose compiler APIs that allow the source information generated by the compiler to be removed during source minification. (Ia34e6)
  • Introduces ReusableContent which will attempt to reuse the nodes in its content instead of replacing them when the key is changed. When the key is changed the previous values in the slot table for the content is ignored except for the nodes that were generated and the values used to update the nodes.

    Introduces ReusableComposeNode that will reuse the node emitted instead of replacing it as is done for ComposeNode. (I1dd86)

  • @ComposeCompilerApi no longer @RequiresOptIn (Iab690)

Bug Fixes

  • LazyColumn/Row will now keep up to 2 previously visible items active (not disposed) even when they are scrolled out already. This allows the component to reuse the active subcompositions when we will need to compose a new item which improves the scrolling performance. (Ie5555)

Version 1.0.0-beta06

May 5, 2021

androidx.compose.runtime:runtime-*:1.0.0-beta06 is released. Version 1.0.0-beta06 contains these commits.

API Changes

  • @ComposeCompilerApi no longer @RequiresOptIn (Iab690)

Version 1.0.0-beta05

April 21, 2021

androidx.compose.runtime:runtime-*:1.0.0-beta05 is released. Version 1.0.0-beta05 contains these commits.

API Changes

  • Removed@InternalComposeApi for recording snapshot reads and writes (Id134d)

Bug Fixes

  • The AndroidManifest files from ui-test-manifest and ui-tooling-data are now compatible with Android 12 (I6f9de, b/184718994)

Version 1.0.0-beta04

April 7, 2021

androidx.compose.runtime:runtime-*:1.0.0-beta04 is released. Version 1.0.0-beta04 contains these commits.

Bug Fixes

  • Prior to this change, local composable functions were skippable based on their parameters. After this change, no local composable functions will skip. This change is done because it is common and expected for local functions to capture parameters from the parent and them skipping is a common source of bugs.

    To summarize, consider the example:

    @Composable fun Counter(count: Int, onCountChange: (Int) -> Unit) {
      @Composable fun ShowCount() { Text("Count: $count") }
      ShowCount()
      Button(onClick={ onCountChange(count + 1) }) {
        Text("Increment")
      }
    }
    

    Prior to this change, the ShowCount composable function would always skip, even after the count parameter was updated. This is no longer the case. (I5648a)

  • Fixed the issue when rememberSaveable() was restoring the old value when used with input params (I1b110, b/182403380)

Version 1.0.0-beta03

March 24, 2021

androidx.compose.runtime:runtime-*:1.0.0-beta03 is released. Version 1.0.0-beta03 contains these commits.

API Changes

  • DefaultMonotonicFrameClock is deprecated. Calling withFrameNanos or Recomposer.runRecomposeAndApplyChanges with no MonotonicFrameClock will now throw IllegalStateException. (I4eb0d)

Version 1.0.0-beta02

March 10, 2021

androidx.compose.runtime:runtime-*:1.0.0-beta02 is released. Version 1.0.0-beta02 contains these commits.

Bug Fixes

Version 1.0.0-beta01

February 24, 2021

androidx.compose.runtime:runtime-*:1.0.0-beta01 is released. Version 1.0.0-beta01 contains these commits.

This is the first release of Compose 1.0.0 Beta.

API Changes

  • Add Recomposer.runRecomposeConcurrentlyAndApplyChanges experimental API for recomposing invalidated compositions off the main frame loop. (I342d0)
  • Any composables marked with @ReadOnlyComposable are now compile-time validated to ensure that they only make calls to other @ReadOnlyComposables (I58961)
  • The defaultFactory for compositionLocalOf and staticCompositionLocalOf is now required instead of optional.

    This changes removes a potential type error for non-nullable types where no default factory was provided. Previously this would provide a null reference for a non-nullable type.

    For nullable types consider supplying { null } as the default factory.

    We do not recommend using locals with non-nullable types unless a sensible default can be provided. If no sensible default exists, the defaultFactory lambda should throw an exception. However throwing an exception means that consumers of the local will have an implicit dependency on it being provided that is not enforced by the type system. (Ifbd2a)

  • Deprecated symbols were removed from the compose runtime (I3252c)

  • Deprecated emptyContent() is removed. Use {} instead. (Idb33f, b/179432510)

  • Providers has been renamed to CompositionLocalProvider

    • The Composition constructor no longer accepts a key parameter, and has been deprecated.
    • currentCompositeKeyHash has been turned into a composable top level property instead of a composable top level function.
    • CompositionData and CompositionGroup have been moved to the androidx.compose.runtime.tooling namespace
    • ComposableLambda has been made an interface instead of a concrete class, and no longer has type parameters.
    • ComposableLambdaN has been made an interface instead of a concrete class, and no longer has type parameters.
    • The snapshotFlow function has been moved to the androidx.compose.runtime namespace
    • the merge method of SnapshotMutationPolicy is no longer experimental
    • The @TestOnly top level clearRoots function has been removed. It is no longer necessary.
    • keySourceInfoOf and resetSourceInfo functions have been removed. They are no longer necessary.
    • Composer.collectKeySourceInformation has been removed. It is no longer necessary.
    • isJoinedKey, joinedKeyLeft, and joinedKeyRight methods have been removed. They are no longer necessary.
    • Various top level APIs have been moved and reorganized into different files. Due to Kotlin’s file class semantics, this will break binary compatibility but not source compatibility, so should not be an issue for most users.
    • (I99b7d, b/177245490)
  • SnapshotStateObserver is not Experimental anymore (Id2e6a)

  • Deleted some previously deprecated APIs (Ice5da, b/178633932)

  • Made the following Material API changes:

    • Added contentPadding parameter to Top/BottomAppBar to allow customizing the default padding.
    • Reordered parameters in BackdropScaffold to follow API guidelines for required parameters being before optional parameters.
    • Moved icon parameter in BottomNavigationItem to be after selected and onClick.
    • Renamed alwaysShowLabels parameter in BottomNavigationItem to alwaysShowLabel.
    • Renamed bodyContent parameters in a few components to just content.
    • Reordered parameters in ButtonDefaults.buttonColors(). Please note that because the type of the parameters have not changed, this will not cause an error in your code - please ensure you are either using named parameters or update the ordering manually, otherwise your code will not work the same as previously.
    • Added secondaryVariant parameter to darkColors(). This color is typically the same as secondary in dark theme, but adding for consistency and further customization.
    • Removed ElevationDefaults and animateElevation() from the public API surface since they were not commonly used / useful.
    • Renamed onValueChangeEnd in Slider to onValueChangeFinished and made it nullable.
    • Renamed text parameter in Snackbar to content for consistency.
    • Added contentPadding parameter to DropdownMenuItem to allow customizing the default padding and made content be an extension on RowScope.
    • Renamed ModalDrawerLayout to ModalDrawer.
    • Renamed BottomDrawerLayout to BottomDrawer.
    • (I1cc66)

Version 1.0.0-alpha12

February 10, 2021

androidx.compose.runtime:runtime-*:1.0.0-alpha12 is released. Version 1.0.0-alpha12 contains these commits.

API Changes

  • Support for ViewGroups was removed from UiApplier. The Deprecated emitView composables were removed. (Ifb214)
  • CompositionReference renamed to CompositionContext (I53fcb)
  • ComponentActivity.setContent has moved to androidx.activity.compose.setContent in the androidx.activity:activity-compose module. (Icf416)
  • Snapshot API was updated to be more consistent with API guideline as well as hiding internal implementation classes from the public API. (Id9e32)
  • Renamed Ambients to match the Ambient -> CompositionLocal rename. Ambients used to be named AmbientFoo, now CompositionLocals are named LocalFoo. (I2d55d)
  • Renamed Ambient to CompositionLocal, and ambientOf / staticAmbientOf to compositionLocalOf / staticCompositionLocalOf respectively. This change helps to make the purpose of CompositionLocal more clear: a mechanism for providing / retrieving values local to a composition. CompositionLocal instances should be prefixed with Local, such as val LocalFoo = compositionLocalOf { Foo() }. (Ia55b6)
  • takeMutableSnapshot and takeSnapshot have moved to be companion methods of Snapshot. (I91f19)
  • @ComposableContract has been deprecated in favor of three more specific annotations.

    @ComposableContract(restartable = false) has become @NonRestartableComposable @ComposableContract(readonly = true) has become @ReadOnlyComposable @ComposableContract(preventCapture = true) has become @DisallowComposableCalls @ComposableContract(tracked = true) has been removed. (I60a9d)

  • emptyContent() and (@Composable () -> Unit).orEmpty() utilities have been deprecated as they no longer have any positive performance impact or value (I0484d)

  • snapshotFlow and withMutableSnapshot are no longer experimental (I6a45f)

  • Recomposers can now be closed. Closed recomposers will continue recomposition until composition child coroutines complete. Recomposer.shutDown renamed to cancel to contrast with close. (Ib6d76)

  • The compose:runtime-dispatch artifact is now deprecated. MonotonicFrameClock can now be found in compose:runtime and AndroidUiDispatcher can be found in compose:ui. (Ib5c36)

  • The API the Compose compiler plugin targets has been refactored to use an interface instead of a concrete class. The interface also no longer uses a type parameter.

    This is an internal change that should not effect source code compatibility but is a binary breaking change. (I3b922, b/169406779)

  • SnapshotMutableState was introduced (Icfd03)

  • DisposableEffectDisposable was renamed to DisposaleEffectResult (Ica7c6)

  • Removed Recomposer.current(). [Abstract]ComposeView now default to lazily created, window-scoped Recomposers driven by the ViewTreeLifecycleOwner for the window. Recomposition and withFrameNanos-based animation ticks are paused while the host Lifecycle is stopped. (I38e11)

  • Recomposer.runningRecomposers now offers a global StateFlow of read-only RecomposerInfo for observing ongoing composition state in the process. Prefer this API to Recomposer.current(), which is now deprecated. (If8ebe)

  • DisposableEffectDisposable was renamed to DisposaleEffectResult (I3ea68)

Version 1.0.0-alpha11

January 28, 2021

androidx.compose.runtime:runtime-*:1.0.0-alpha11 is released. Version 1.0.0-alpha11 contains these commits.

API Changes

  • onCommit, onDispose, and onActive have been deprecated in favor of SideEffect and DisposableEffect APIs (If760e)
  • The emit() API and all overloads have been deprecated and renamed to ComposeNode. The APIs are identical, just a different name in order to follow the naming conventions of Compose (I4137b)
  • invalidate and compositionReference() are now deprecated in favor of currentRecomposeScope and rememberCompositionReference respectively. (I583a8)
  • RememberObserver replaces CompositionLifecycleObserver and CompositionLifecycleObserver is now deprecated.

    RememberObserver is a replacement for CompositionLifecycleObserver with modified semantics and renamed methods. Changing to the new API can be done mechanically for objects that are only remembered once which is, and continues to be, the recommended practice. However, if a reference was remembered more than once in a composition onRemembered is called for each reference where onEnter is only called once. onEnter was called multiple time if the object was used in subcompositions, such as WithConstraints and Scaffold making the single onEnter call guarantee unreliable and it was removed for RememberObserver.

    RememberObserver adds onAbandoned which is called if the RememberObserver instance is returned from the callback passed to remember but was not remembered in the composition state and, therefore, will never have onRemembered called. This can occur if an exception terminates composition before completing or the composition is discarded because the state is was producing a composition for is no longer current or otherwise is no longer needed. If the instance of RememberObserver following the single reference recommendation above is tracking an external resource both onForgotten and onAbandoned each indicate that the resource is no longer needed. If the object is tracking work started or resources allocated in onRemembered, onAbandoned can be ignored as it will not be called if onRemembered is called. (I02c36)

  • Do not mark collectAsState() functions as inline (Ia73e4)

Bug Fixes

  • WithConstraints was reworked as BoxWithConstraints and moved to foundation.layout. (I9420b, b/173387208)
  • Leverage TestCoroutineDispatcher in testing (I532b6)

Version 1.0.0-alpha10

January 13, 2021

androidx.compose.runtime:runtime-*:1.0.0-alpha10 is released. Version 1.0.0-alpha10 contains these commits.

Breaking Change

  • Restructuring of the internal compiler API allows batching changes to the nodes generated as a result of composition into the "apply changes" phase of composition, after all @Composable functions have completed.

    This is a behavioral breaking change that might affect application code as nodes are no longer available from internal and experimental APIs until after changes have been applied. This can usually be worked around by surrounding code with such dependencies in a SideEffect composable to defer execution of the code until after the nodes have been created and initialized. (I018da)

API Changes

  • Added a way to track if the recomposer has applied changes. (I1b3e2)
  • Expand [Abstract]ComposeView APIs to allow recycling Compose-based views, disposing their composition to recreate again later. Add APIs for installing and discovering window-scoped Recomposers and CompositionReferences for creating child compositions.

    Add ViewCompositionStrategy for configuring the composition disposal strategy of [Abstract]ComposeViews; default behavior is dispose on window detach. (I860ab)

Bug Fixes

  • Recomposer now exposes a Flow of its current state, allowing monitoring its activity and the activity of associated effects. (Ifb2b9)
  • The native keyEvent can now be accessed through keyEvent.nativeKeyEvent (I87c57, b/173086397)

Version 1.0.0-alpha09

December 16, 2020

androidx.compose.runtime:runtime-*:1.0.0-alpha09 is released. Version 1.0.0-alpha09 contains these commits.

API Changes

  • Removed SlotTable, SlotReader and SlotWriter from the public API. These were marked as InternalComposeAPI previously. Now they are internal to the compose module.

    CompositionData and CompositionGroup were added as a replacement for the ui-tooling API to use to extract composition information. These are public but are not intended for use outside the ui-tooling API as they provide the raw information the ui-tooling API interprets (I31a9c)

  • The Applier class is no longer considered an (Id85b0)

  • The Applier interface has changed to simplify building trees bottom-up instead of top-down.

    The insert() method has been renamed to insertTopDown().

    A new method, insertBottomUp(), was added.

    An applier either inserts nodes into the tree it is editing using insertTopDown() or insertBottomUp() depending on which performs better.

    Some trees, such as LayoutNode and View, are much more efficient to build bottom-up than top-down. Prior to this change, a stack of inserts was required to implement bottom-up which needed to be copied to every applier which needed bottom-up construction for performance. With this change an Applier overrides insertBottomUp() to build a tree bottom-up and insertTopDown() to build the tree top-down. (Icbdc2)

  • Compose supports property getters that can make composable invocations. Support for this is not going away, but the syntax for declaring a property getter as being @Composable is changing.

    The now-deprecated syntax for doing this was by annotating the property itself:

        @Composable val someProperty: Int get() = ...
    

    The now-correct syntax for doing this is by annotating the getter of the property:

       val someProperty: Int @Composable get() = ...
    

    Both syntaxes will work for some time, but the former deprecated syntax will eventually become a compile error. (Id9197)

Bug Fixes

Version 1.0.0-alpha08

December 2, 2020

androidx.compose.runtime:runtime-*:1.0.0-alpha08 is released. Version 1.0.0-alpha08 contains these commits.

API Changes

  • Added lint check for composable lambda parameter naming and position, to check for consistency with Compose guidelines. Also migrated some APIs using children as the name for their trailing lambda to content, according to the lint check and guidance. (Iec48e)
  • Recomposer no longer accepts an EmbeddingContext; required scheduling dependencies are obtained from the effectCoroutineContext. FrameManager is deprecated; platform integrations should initialize their own global snapshot handling. (I02369)
  • RestorableStateHolder.withRestorableState function was renamed to RestorableStateProvider (I66640)

Bug Fixes

  • Deprecated Ambients named with Ambient as their suffix, and replaced them with new properties prefixed with Ambient, following other Ambients and Compose API guidelines. (I33440)
  • Remove old ui-test module and its stubs (I3a7cb)

Version 1.0.0-alpha07

November 11, 2020

androidx.compose.runtime:runtime-*:1.0.0-alpha07 is released. Version 1.0.0-alpha07 contains these commits.

New Features

API Changes

  • The @UnionType annotation has been deprecated (I57cde)
  • provideDefault was added as an alternative to provide for providing ambients, and it can be used to specify ambient values that will only be set when there is no ambient value already provided. (Id6635, b/171024925)
  • LaunchedTask was renamed to LaunchedEffect for consistency with the SideEffect and DisposableEffect APIs. LaunchedEffect with no subject params is not permitted in order to encourage best practices. (Ifd3d4)
  • Applier now has onBeginChanges/onEndChanges callbacks that are invoked when a Composer begins/is finished applying changes to the tree. These may be used for batching resource management if needed. (Icf476)
  • Recomposer now requires a CoroutineContext at construction (Ic4610)
  • Changes to the internal SlotTable implementation which should not affect the public API. (If9828)
  • Deprecated rxjava2 adapters which does not take the initial value were removed (Idb72f)

Bug Fixes

  • foundation.Text has been deprecated and replaced with material.Text. For a basic, unopinionated text API that does not consume values from a theme, see androidx.compose.foundation.BasicText. (If64cb)
  • BaseTextField has been deprecated. Use BasicTextField instead. (I896eb)
  • Several layout related symbols were moved from androidx.compose.ui to androidx.compose.layout.ui. (I0fa98, b/170475424)

External Contribution

  • Added runtime-rxjava3 module for compose. Similar to runtime-rxjava2 (I02cbf)

Version 1.0.0-alpha06

October 28, 2020

androidx.compose.runtime:runtime-*:1.0.0-alpha06 is released. Version 1.0.0-alpha06 contains these commits.

API Changes

  • Recomposer is now a CompositionReference and a valid composition parent. Explicit Recomposer is now required in fewer places. (I4036f)
  • Added DisposableEffect counterpart API to SideEffect, filling the role of onCommit-with-params but with a required onDispose.
    • Added rememberUpdatedState API to publish data from recomposition to ongoing or long-lived processes such as DisposableEffects or LaunchedTasks.
    • (Id50b9)
  • MutableVector now implements RandomAccess (I85d73, b/170461551)
  • Added SideEffect composable for applying side effects of composition to objects managed by the composition. SideEffect is intended to replace the onCommit composable. (Ia77c2)
  • New experimental api RestorableStateHolder. It allows to save the state defined with [savedInstanceState] and [rememberSavedInstanceState] for the subtree before disposing it to make it possible to compose it back next time with the restored state. (I66884, b/166586419)

Bug Fixes

  • Enable transitions in ComposeTestRule; remove option to enable the blinking cursor from ComposeTestRule. (If0de3)

Version 1.0.0-alpha05

October 14, 2020

androidx.compose.runtime:runtime-*:1.0.0-alpha05 is released. Version 1.0.0-alpha05 contains these commits.

API Changes

  • Experimental Modifier.pointerInput suspending input modifier (Ia77d2)
  • The scrolling performance of LazyColumn/Row is improved by doing less work in subcomposition on every scroll. The new hasInvalidations() method was added for Composition class. hasPendingChanges() method from Recomposer was renamed to hasInvalidations() (Ib2f32, b/168293643, b/167972292, b/165028371)
  • Add produceState API for launching coroutines from composition that update a single State<T> value over time (Id4a57)
  • launchInComposition renamed to LaunchedTask to match Compose API guidelines (I99a8e)
  • The order of place() calls in custom Layouts now defines the drawing order for the children (Ibc9f6)

Version 1.0.0-alpha04

October 1, 2020

androidx.compose.runtime:runtime-*:1.0.0-alpha04 is released. Version 1.0.0-alpha04 contains these commits.

API Changes

  • Added OwnerScope to allow collection of layout and drawing observation scopes once they are no longer valid. (Ic4cf8)
  • Added derivedStateOf API to create State objects based on a calculation which may read (and derive from) other State objects (If758b)
  • Added TestOnly API for SnapshotStateObserver (I6e2a9)

Bug Fixes

  • foundation.Box was deprecated. Please use foundation.layout.Box instead. (Ie5950, b/167680279)

Version 1.0.0-alpha03

September 16, 2020

androidx.compose.runtime:runtime-*:1.0.0-alpha03 is released. Version 1.0.0-alpha03 contains these commits.

API Changes

  • CompositionCoroutineScope no longer implements MonotonicFrameClock. Callers of withFrameNanos should import the top-level function explicitly. (Icb642, b/166778123)

Bug Fixes

  • Global testing functions such as onNode or waitForIdle are now deprecated, please migrate to their new counterparts that are defined on ComposeTestRule (I7f45a)
  • launchInComposition no longer launches coroutines undispatched (Ief6af, b/166486000)

Version 1.0.0-alpha02

September 2, 2020

androidx.compose.runtime:runtime-*:1.0.0-alpha02 is released. Version 1.0.0-alpha02 contains these commits.

API Changes

  • Add snapshotFlow and withMutableSnapshot APIs for consuming and producing Snapshot data changes. (I3e722)
  • The calling convention for composable functions has changed. This is a binary breaking change. All libraries must be recompiled to work with this version of the compose compiler plugin.

    This change does not create a source level breaking change as the only APIs that have changed are compiler APIs that have an explicit opt in. (I7afd2, b/158123185)

  • Removed scheduling methods from EmbeddingContext (I7b9be)

  • onPreCommit is deprecated; onCommit now has onPreCommit's behavior.

    onCommit and onActive now run in the same choreographer frame that the composition changes committed in rather than at the beginning of the next choreographer frame. (I70403)

Version 1.0.0-alpha01

August 26, 2020

androidx.compose.runtime:runtime-*:1.0.0-alpha01 is released. Version 1.0.0-alpha01 contains these commits.

Version 0.1.0-dev

Version 0.1.0-dev17

August 19, 2020

androidx.compose.runtime:runtime-*:0.1.0-dev17 is released. Version 0.1.0-dev17 contains these commits.

API Changes

  • Custom emits can now declare that one or more of its setters can be skipped and recomposed independently of the emit. (Ibbd13)
  • Removed deprecated FrameManager calls.

    Internal compose APIs have been changed to reduce the amount of overhead to track state objects such as mutableStateof() (I80ba6)

  • The state { ... } composable is now deprecated in favor of explicit calls to remember { mutableStateOf(...) } for clarity. This reduces the overall API surface and number of concepts for state management, and matches the by mutableStateOf() pattern for class property delegation. (Ia5727)

  • Flow.collectAsState now determines the default dispatcher from the composition itself rather than defaulting to Dispatchers.Main. (I9c1d9)

  • Crash when something which saves the state was used inside the for loop is fixed. Now having the same key in savedInstanceState() is allowed, api of UiSavedStateRegistry is now adjusted to this new requirement (I4ab76, b/160042650, b/156853976, b/159026663, b/154920561)

Bug Fixes

  • emitView was deprecated. Use AndroidView instead if possible for emitting Views inside Compose. Note that composing Views and ViewGroups directly will not be supported in the future unless these are leaves in the composition tree, case when this can be achieved using AndroidView. (I29b1e, b/163871221)

Version 0.1.0-dev16

August 5, 2020

androidx.compose.runtime:runtime-*:0.1.0-dev16 is released. Version 0.1.0-dev16 contains these commits.

API Changes

  • The default mutation policy of mutableStateOf(), ambientOf() and savedInstanceStateOf() has changed to be structuralEqualityPolicy() instead of referentialEqualityPolicy().

    The default for deciding if a new value assigned to a mutableStateOf() instance is considered a change now defaults to using == instead of using ===.

    See https://kotlinlang.org/docs/reference/equality.html

    ambientOf() and savedInstanceStateOf() use mutableStateOf() in their implementations so they were changed to be consistent with mutableStateOf().

    Using structural equality more closely matches developer expectations.

    For example,

    val state = mutableStateOf(1f)
    

    followed by,

    state.value = 1f
    

    will no longer be consider a change to state and uses of state during composition will no longer need to be recomposed.

    This is a breaking change but, in most cases (such when using classes that do not override equals()), this will not have a noticeable effect on an application.

    Classes that do override equals(), such as data classes, might see a performance degradation as their equals() methods are now, by default, called when assigned to a mutableStateOf().

    The previous behavior can be restored by adding the policy parameter policy = referentialEqualityPolicy() to calls to mutableStateOf(), ambientOf() and savedInstanceStateOf(). (Ic21a7)

  • Row and Column are now inline function significantly reducing the overhead of using them. (I75c10)

Bug Fixes

  • setViewContent was deprecated. setContent should be used instead. (I7e497, b/160335130)
  • Added MonotonicFrameAnimationClock that enables you to use a MonotonicFrameClock as an AnimationClockObservable to bridge the gap between the new coroutines based clocks and APIs that still use the old callback based clocks.

    The MonotonicFrameClock equivalent of ManualAnimationClock is now ManualFrameClock. (I111c7, b/161247083)

  • Modifier.stateDraggable was completely reworked and renamed to Modifier.swipeable. A new SwipeableState class was introduced, and DrawerState and BottomDrawerState were refactored to inherit from it. [Modal/Bottom]DrawerLayout no longer take an onStateChange parameter. (I72332, b/148023068)

  • Modifier.plus has been deprecated, use Modifier.then instead. 'Then' has a stronger signal of ordering, while also prohibits to type Modifier.padding().background() + anotherModifier, which breaks the chain and harder to read (Iedd58, b/161529964)

  • SubcomposeLayout is added. It is a low level primitive which allows to compose the children during the measuring if we want to use some values available only later during the measure for the subtree composition. For example WithConstraints is not implemented using SubcomposeLayout. (I25cc8)

  • Material FilledTextField was renamed to TextField and foundational TextField was renamed to BaseTextField to make simplest desired API easy to discover and use (Ia6242, b/155482676)

  • Modifier.drawBackground has been renamed to Modifier.background (I13677)

Version 0.1.0-dev15

July 22, 2020

androidx.compose.runtime:runtime-*:0.1.0-dev15 is released. Version 0.1.0-dev15 contains these commits.

Dependencies Update

  • To use the 0.1.0-dev15 version of Compose, you will need to update your dependencies according to the new code snippets shown above in Declaring dependencies.

API Changes

  • @Model annotation is now deprecated. Use state and mutableStateOf as alternatives. This deprecation decision was reached after much careful discussion.

    Justification

    Rationale includes but is not limited to:

    • Reduces API surface area and concepts we need to teach
    • More closely aligns with other comparable toolkits (Swift UI, React, Flutter)
    • Reversible decision. We can always bring @Model back later.
    • Removes corner-case usage and difficult to answer questions about configuring @Model as things we need to handle
    • @Model data classes, equals, hashcode, etc.
    • How do I have some properties “observed” and others not?
    • How do I specify structural vs. referential equality to be used in observation?
    • Reduces “magic” in the system. Would reduce the likelihood of someone assuming system was smarter than it is (ie, it knowing how to diff a list)
    • Makes the granularity of observation more intuitive.
    • Improves refactorability from variable -> property on class
    • Potentially opens up possibilities to do hand-crafted State-specific optimizations
    • More closely aligns with the rest of the ecosystem and reduces ambiguity towards immutable or us “embracing mutable state”

    Migration Notes

    Almost all existing usages of @Model are fairly trivially transformed in one of two ways. The example below has a @Model class with two properties just for the sake of example, and has it being used in a composable.

    @Model class Position(
     var x: Int,
     var y: Int
    )
    
    @Composable fun Example() {
     var p = remember { Position(0, 0) }
     PositionChanger(
       position=p,
       onXChange={ p.x = it }
       onYChange={ p.y = it }
     )
    }
    

    Alternative 1: Use State<OriginalClass> and create copies.

    This approach is made easier with Kotlin’s data classes. Essentially, make all previously var properties into val properties of a data class, and then use state instead of remember, and assign the state value to cloned copies of the original using the data class copy(...) convenience method.

    It’s important to note that this approach only works when the only mutations to that class were done in the same scope that the State instance is created. If the class is internally mutating itself outside of the scope of usage, and you are relying on the observation of that, then the next approach is the one you will want to use.

    data class Position(
     val x: Int,
     val y: Int
    )
    
    @Composable fun Example() {
     var p by state { Position(0, 0) }
     PositionChanger(
       position=p,
       onXChange={ p = p.copy(x=it) }
       onYChange={ p = p.copy(y=it) }
     )
    }
    

    Alternative 2: Use mutableStateOf and property delegates

    This approach is made easier with Kotlin’s property delegates and the mutableStateOf API which allows you to create MutableState instances outside of composition. Essentially, replace all var properties of the original class with var properties with mutableStateOf as their property delegate. This has the advantage that the usage of the class will not change at all, only the internal implementation of it. The behavior is not completely identical to the original example though, as each property is now observed/subscribed to individually, so the recompositions you see after this refactor could be more narrow (a good thing).

    class Position(x: Int, y: Int) {
     var x by mutableStateOf(x)
     var y by mutableStateOf(y)
    }
    
    // source of Example is identical to original
    @Composable fun Example() {
     var p = remember { Position(0, 0) }
     PositionChanger(
       position=p,
       onXChange={ p.x = it }
       onYChange={ p.y = it }
     )
    }
    

    (I409e8, b/152050010, b/146362815, b/146342522, b/143413369, b/135715219, b/143263925, b/139653744)

  • Changes the code generation strategy of Compose’s compiler. Prior to the change, the compose compiler would transform calls to composable functions. With this change, we now transform the body of a composable function and leave the callsite unaltered (mostly).

    This means that most of the logic communicating with the compose runtime happens at the start of the function body, instead of at the callsite.

    This should be a source-compatible change for all usage of compose. Most users of compose should not have to update any code as a result of this change.

    In order to support this work, the JVM signature of all composable functions has changed. A Composable function accepting a single parameter is transformed into a function accepting 3 parameters, the additional parameters are the Composer, a ‘key’ integer. a bitmask integer used to propagate metadata through calls.

    Compose now also transforms default arguments to a composable function. It does this without introducing an additional synthetic default overload of the function itself, so this change will result in fewer functions being defined.

    Known intentional behavioral changes resulting from this:

    1. Some calls will skip where they wouldn’t have previously
    2. Composable expressions in default argument expressions are now correctly subscribed to and handled

    This work included some optimizations: 1. The result of comparisons of parameters are propagated through the call graph to other composable functions. This will result in fewer comparisons at runtime, reduces the slot table size, as well as more skipping of composable functions that were previously not skipped 2. Paremeters which are determined to be “static” at compile time are no longer compared or stored in the runtime. This reduces the number of comparisons and reduces slot table size. 3. Control flow structure of the body of functions is used to minimize the number of groups that are generated. This reduces slot table size and results in less work for the runtime 4. Unused dispatch and receiver parameters to functions are not included in determining skippability of the function if they are not used inside of the body of the function.

    Most breaking changes were for APIs that the compiler targets directly, and typical use of compose will not be affected: 1. Composer::startExpr was removed 2. Composer::endExpr was removed 3. Composer::call was deprecated 4. The non-varargs overloads of key have been removed. Use the vararg version going forward. 5. The Pivotal annotation was deprecated. Use key as a replacement. 6. ScopeUpdateScope::updateScope was changed to expect a Function3 instead of Function1 7. restartableFunction and restartableFunctionN were updated to include additional compile time parameters (I60756, b/143464846)

  • Added sortWith and removeRange to MutableVector (Icccf7)

  • Added default method implementations for CompositionLifecycleObserver (I24289)

  • Applier now requires a clear() method for disposing compositions (Ibe697)

  • Added asMutableList() to MutableVector to allow it to be passed to public API without having to copy the entire list. (I298df)

  • Added rememberCoroutineScope() to obtain a managed CoroutineScope in composition for launching jobs in response to events. (I0e264)

  • MutableVector is a new collection that does not implement any of the standard Collection interface. This collection offers speed above other requirements and is intended to only be used in internal implementations. (I8ebd6)

  • Temporarily removed StableMutableList and StableMutableMap to avoid an issue in the version of Kotlin compose requires. These interfaces will be reintroduced once compose is updated to a version of Kotlin that doesn't have the issue.

    SnapshotStateList and SnapshotStateMap are now public but they will be deprecated once StableMutableList and StableMutableMap are restored. (Ia7769)

  • add top-level withFrameNanos function for animation timing (Ie34c5)

  • @Untracked annotation has been deprecated. Replace with @ComposableContract(tracked=false) (Id211e)

  • RestartableFunction and associated APIs have been renamed to ComposableLambda, etc. These APIs were targeted only by the compiler so this should not affect source level compatibility normally. The rename was done primarily to communicate what this class is better when it shows up in stack traces (I7eb25)

  • @Composable annotation is no longer valid on classes (Ia5f02)

  • Ambient<T> is now @Stable instead of @Immutable (I0b4bb)

  • Prior to this change, the compose compiler plugin would non-trivially intercept calls to constructors inside of a @Composable function if there was an (I5205a, b/158123804)

  • The Recompose composable is no longer a useful abstraction. Most recomposition should happen as a result of MutableState assignments. For anything beyond that, it is recommended that you use the invalidate function to trigger a recomposition of the current scope. (Ifc992)

  • Observe is no longer a useful abstraction. If you need to replicate it, its implementation can be replicated by just creating a composable function which executes a composable lambda parameter. For example, @Composable fun Observe(body: @Composable () -> Unit) = body() (I40d37)

  • @Direct was deprecated in favor of @ComposableContract(restartable=false) (If4708)

  • Added an adapter for the recently introduced StateFlow which allows as to pre-populate the initial value so the returned State is non-nullable (I61dd8, b/156233789)

  • Added an adapter for Flow. Example of the usage: val value by flow.collectAsState() (If2198, b/153375923)

  • [Mutable]State property delegate operators moved to extensions to support Kotlin 1.4 property delegate optimizations. Callers must add imports to continue using by state { ... } or by mutableStateOf(...). (I5312c)

  • androidx.compose.ViewComposer has been moved to androidx.ui.node.UiComposer androidx.compose.Emittable has been removed. It was redundant with ComponentNode. androidx.compose.ViewAdapters has been removed. They are no longer a supported use case. Compose.composeInto has been deprecated. Use setContent or setViewContent instead. Compose.disposeComposition has been deprecated. Use the dispose method on the Composition returned by setContent instead. androidx.compose.Compose.subcomposeInto has moved to androidx.ui.core.subcomposeInto ComponentNode#emitInsertAt has been renamed to ComponentNode#insertAt ComponentNode#emitRemoveAt has been renamed to ComponentNode#removeAt ComponentNode#emitMode has been renamed to ComponentNode#move (Idef00)

  • Updated the ComposeFlags.COMPOSER_PARAM flag to be true, which will change the code generation strategy for the compose plugin. At a high level, this causes @Composable functions to be generated with an additional synthetic parameter, which is passed through to subsequent @Composable calls in order for the runtime to properly manage execution. This is a significant binary breaking change, however, should preserve source-level compatibility in all sanctioned usage of compose. (I7971c)

  • Breaking changes to the ambients API. See log and Ambient<T> documentation for details (I4c7ee, b/143769776)

  • Added ui-livedata - new artifact with an adapter for LiveData. Example of the usage: val value by liveData.observeAsState() (Ie9e8c, b/150465596)

  • Rx adapters without explicit initial value are deprecated. Using null is not always the best default, for example when you have a List it is better to start with emptyList() or any other reasonable default (I00025, b/161348384)

  • Added ui-rxjava2 - new artifact with adapters for RxJava2. Example of the usage: val value by observable.subscribeAsState() (Ifab4b, b/153369097)

  • savedInstanceState() can now be used with nullable types (I6847f, b/153532190)

  • New listSaver() and mapSaver() to make it easier to write custom Saver objects (I8cf68, b/152331508)

  • New functions: savedInstanceState() and rememberSavedInstanceState(). They are similar to state() and remember() but have a saved instance state support build in (If1987, b/152025209)

Bug Fixes

  • runOnIdleCompose renamed to runOnIdle (I83607)
  • Made LayoutNode experimental API (I4f2e9)
  • androidx.ui.foundation.TextFieldValue and androidx.ui.input.EditorValue is deprecated. TextField, FilledTextField and CoreTextField composables that uses that type is also deprecated. Please use androidx.ui.input.TextFieldValue instead (I4066d, b/155211005)
  • Removed deprecated DrawBackground API in favor of drawBackground extension APIs on Modifier. Refactored color, brush and paint drawBackground implementations to reduce code paths as well as remove requirement for Modifier to be created as part of composition. (I0343a)
  • Updated higher level compose APIs that expose a Canvas to expose CanvasScope instead. This removes the need for consumers to maintain their own Paint objects. For consumers that still require access to a Canvas they can use the drawCanvas extension method which provides a callback to issue drawing commands with the underlying Canvas. (I80afd)
  • WithConstraints trailing lambda API has been changed. Now instead of two params it has a receiver scope which in addition to constraints and layoutDirection provides minWidth, maxWidth, minHeight and maxHeight properties in Dp (I91b9a, b/149979702)
  • Added symmetric padding modifier. (I39840)
  • Updated wrapContentWidth and wrapContentHeight to expect vertical or horizontal Alignment rather than any Alignment. The gravity modifier was updated to accept vertical or horizontal Alignment. Row, Column and Stack were updated to support custom continuous Alignments. (Ib0728)
  • ui-text module is renamed as ui-text-core (I57dec)
  • Improve DrawModifier API:
    • Made the receiver scope for draw() ContentDrawScope
    • Removed all parameters on draw()
    • DrawScope has same interface as former CanvasScope
    • ContentDrawScope has drawContent() method (Ibaced, b/152919067)
  • ColoredRect has been deprecated. Use Box(Modifier.preferredSize(width, height).drawBackground(color)) instead. (I499fa, b/152753731)
  • Replaced Modifier plus operator with factory extension functions (I225e4)
  • RowScope and ColumnScope members are now accessible outside Row and Column. (I3a641)
  • Renamed LayoutFlexible to LayoutWeight. Renamed tight parameter to fill. (If4738)
  • WithConstraints got LayoutDirection parameter (I6d6f7)
  • Renamed background to DrawBackground and make it to be memorized by default (Ia0bd3)
  • Replaced ButtonStyle with distinct functions and removed text (string) overload. See updated samples for usage information. (If63ab, b/146478620, b/146482131)
  • runOnIdleCompose and runOnUiThread are now global functions instead of methods on ComposeTestRule. (Icbe8f)

External Contribution

  • Remove unneeded API such as Looper and Handler from Compose Runtime porting layer (I6847d)
  • Deprecate Flow<T>.collectAsState() with no initial value. Use StateFlow<T> or pass an explicit initial value instead. (I63f98, b/157674865)