Refactor: AmbientAware API change

compose-layout/api/current.api

@@ -2,39 +2,52 @@
 package com.google.android.horologist.compose.ambient {
 
   public final class AmbientAwareKt {
-    method @androidx.compose.runtime.Composable public static void AmbientAware(optional boolean isAlwaysOnScreen, kotlin.jvm.functions.Function1<? super com.google.android.horologist.compose.ambient.AmbientStateUpdate,kotlin.Unit> block);
+    method @androidx.compose.runtime.Composable public static void AmbientAware(kotlin.jvm.functions.Function1<? super com.google.android.horologist.compose.ambient.AmbientState,kotlin.Unit> content);
+    method public static androidx.compose.runtime.ProvidableCompositionLocal<com.google.android.horologist.compose.ambient.AmbientState> getLocalAmbientState();
+    property public static final androidx.compose.runtime.ProvidableCompositionLocal<com.google.android.horologist.compose.ambient.AmbientState> LocalAmbientState;
   }
 
   public final class AmbientAwareTimeKt {
-    method @RequiresApi(android.os.Build.VERSION_CODES.O) @androidx.compose.runtime.Composable public static void AmbientAwareTime(com.google.android.horologist.compose.ambient.AmbientStateUpdate stateUpdate, optional long updatePeriodMillis, kotlin.jvm.functions.Function2<? super java.time.ZonedDateTime,? super java.lang.Boolean,kotlin.Unit> block);
+    method @RequiresApi(android.os.Build.VERSION_CODES.O) @androidx.compose.runtime.Composable public static void AmbientAwareTime(com.google.android.horologist.compose.ambient.AmbientState stateUpdate, optional long updatePeriodMillis, kotlin.jvm.functions.Function2<? super java.time.ZonedDateTime,? super java.lang.Boolean,kotlin.Unit> block);
   }
 
-  public sealed interface AmbientState {
+  @androidx.compose.runtime.Immutable public sealed interface AmbientState {
+    method public String getName();
+    method public default boolean isAmbient();
+    method public default boolean isInteractive();
+    property public default boolean isAmbient;
+    property public default boolean isInteractive;
+    property public abstract String name;
   }
 
   public static final class AmbientState.Ambient implements com.google.android.horologist.compose.ambient.AmbientState {
-    ctor public AmbientState.Ambient(optional androidx.wear.ambient.AmbientLifecycleObserver.AmbientDetails? ambientDetails);
-    method public androidx.wear.ambient.AmbientLifecycleObserver.AmbientDetails? component1();
-    method public com.google.android.horologist.compose.ambient.AmbientState.Ambient copy(androidx.wear.ambient.AmbientLifecycleObserver.AmbientDetails? ambientDetails);
-    method public androidx.wear.ambient.AmbientLifecycleObserver.AmbientDetails? getAmbientDetails();
-    property public final androidx.wear.ambient.AmbientLifecycleObserver.AmbientDetails? ambientDetails;
+    ctor public AmbientState.Ambient(optional boolean burnInProtectionRequired, optional boolean deviceHasLowBitAmbient, optional long updateTimeMillis);
+    method public boolean component1();
+    method public boolean component2();
+    method public long component3();
+    method public com.google.android.horologist.compose.ambient.AmbientState.Ambient copy(boolean burnInProtectionRequired, boolean deviceHasLowBitAmbient, long updateTimeMillis);
+    method public boolean getBurnInProtectionRequired();
+    method public boolean getDeviceHasLowBitAmbient();
+    method public String getName();
+    method public long getUpdateTimeMillis();
+    property public final boolean burnInProtectionRequired;
+    property public final boolean deviceHasLowBitAmbient;
+    property public String name;
+    property public final long updateTimeMillis;
+  }
+
+  public static final class AmbientState.Inactive implements com.google.android.horologist.compose.ambient.AmbientState {
+    method public String getName();
+    property public String name;
+    field public static final com.google.android.horologist.compose.ambient.AmbientState.Inactive INSTANCE;
   }
 
   public static final class AmbientState.Interactive implements com.google.android.horologist.compose.ambient.AmbientState {
+    method public String getName();
+    property public String name;
     field public static final com.google.android.horologist.compose.ambient.AmbientState.Interactive INSTANCE;
   }
 
-  public final class AmbientStateUpdate {
-    ctor public AmbientStateUpdate(com.google.android.horologist.compose.ambient.AmbientState ambientState, optional long changeTimeMillis);
-    method public com.google.android.horologist.compose.ambient.AmbientState component1();
-    method public long component2();
-    method public com.google.android.horologist.compose.ambient.AmbientStateUpdate copy(com.google.android.horologist.compose.ambient.AmbientState ambientState, long changeTimeMillis);
-    method public com.google.android.horologist.compose.ambient.AmbientState getAmbientState();
-    method public long getChangeTimeMillis();
-    property public final com.google.android.horologist.compose.ambient.AmbientState ambientState;
-    property public final long changeTimeMillis;
-  }
-
 }
 
 package com.google.android.horologist.compose.layout {

compose-layout/src/main/java/com/google/android/horologist/compose/ambient/AmbientAware.kt

@@ -20,87 +20,94 @@ import android.app.Activity
 import android.content.Context
 import android.content.ContextWrapper
 import androidx.compose.runtime.Composable
-import androidx.compose.runtime.DisposableEffect
-import androidx.compose.runtime.getValue
+import androidx.compose.runtime.CompositionLocalProvider
+import androidx.compose.runtime.SideEffect
+import androidx.compose.runtime.compositionLocalOf
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
-import androidx.compose.runtime.setValue
 import androidx.compose.ui.platform.LocalContext
 import androidx.lifecycle.compose.LocalLifecycleOwner
 import androidx.wear.ambient.AmbientLifecycleObserver
 
 /**
  * Composable for general handling of changes and updates to ambient status. A new
- * [AmbientStateUpdate] is generated with any change of ambient state, as well as with any periodic
+ * [AmbientAwareState] is generated with any change of ambient state, as well as with any periodic
  * update generated whilst the screen is in ambient mode.
  *
  * This composable changes the behavior of the activity, enabling Always-On. See:
  *
  *     https://developer.android.com/training/wearables/views/always-on).
  *
- * It should therefore be used high up in the tree of composables.
+ * It should be used within each individual screen inside nav routes.
  *
- * @param isAlwaysOnScreen If supplied, this indicates whether always-on should be enabled. This can
- * be used to ensure that some screens display an ambient-mode version, whereas others do not, for
- * example, a workout screen vs a end-of-workout summary screen.
- * @param block Lambda that will be used for building the UI, which is passed the current ambient
+ * @param content Lambda that will be used for building the UI, which is passed the current ambient
  * state.
  */
 @Composable
 fun AmbientAware(
-    isAlwaysOnScreen: Boolean = true,
-    block: @Composable (AmbientStateUpdate) -> Unit,
+    content: @Composable (AmbientState) -> Unit,
 ) {
-    var ambientUpdate by remember(isAlwaysOnScreen) {
-        mutableStateOf(if (isAlwaysOnScreen) null else AmbientStateUpdate(AmbientState.Interactive))
-    }
-
-    val activity = LocalContext.current.findActivityOrNull()
     // Using AmbientAware correctly relies on there being an Activity context. If there isn't, then
     // gracefully allow the composition of [block], but no ambient-mode functionality is enabled.
-    if (activity != null && isAlwaysOnScreen) {
-        val lifecycle = LocalLifecycleOwner.current.lifecycle
-        val observer = remember {
-            val callback = object : AmbientLifecycleObserver.AmbientLifecycleCallback {
-                override fun onEnterAmbient(ambientDetails: AmbientLifecycleObserver.AmbientDetails) {
-                    ambientUpdate = AmbientStateUpdate(AmbientState.Ambient(ambientDetails))
-                }
+    val activity = LocalContext.current.findActivityOrNull()
+    val lifecycle = LocalLifecycleOwner.current.lifecycle
 
-                override fun onExitAmbient() {
-                    ambientUpdate = AmbientStateUpdate(AmbientState.Interactive)
-                }
+    var ambientState = remember {
+        mutableStateOf<AmbientState>(AmbientState.Inactive)
+    }
 
-                override fun onUpdateAmbient() {
-                    val lastAmbientDetails =
-                        (ambientUpdate?.ambientState as? AmbientState.Ambient)?.ambientDetails
-                    ambientUpdate = AmbientStateUpdate(AmbientState.Ambient(lastAmbientDetails))
-                }
-            }
-            AmbientLifecycleObserver(activity, callback).also {
-                // Necessary to populate the initial value
-                val initialAmbientState = if (it.isAmbient) {
-                    AmbientState.Ambient(null)
-                } else {
-                    AmbientState.Interactive
-                }
-                ambientUpdate = AmbientStateUpdate(initialAmbientState)
-            }
-        }
+    val observer = remember {
+        if (activity != null) {
+            println("Creating observer")
+            AmbientLifecycleObserver(
+                activity,
+                object : AmbientLifecycleObserver.AmbientLifecycleCallback {
+                    override fun onEnterAmbient(ambientDetails: AmbientLifecycleObserver.AmbientDetails) {
+                        println("onEnterAmbient")
+                        ambientState.value = AmbientState.Ambient(
+                            burnInProtectionRequired = ambientDetails.burnInProtectionRequired,
+                            deviceHasLowBitAmbient = ambientDetails.deviceHasLowBitAmbient,
+                        )
+                    }
+
+                    override fun onExitAmbient() {
+                        println("onExitAmbient")
+                        ambientState.value = AmbientState.Interactive
+                    }
 
-        DisposableEffect(Unit) {
-            lifecycle.addObserver(observer)
+                    override fun onUpdateAmbient() {
+                        println("onUpdateAmbient")
+                        val lastAmbientDetails =
+                            (ambientState.value as? AmbientState.Ambient)
+                        ambientState.value = AmbientState.Ambient(
+                            burnInProtectionRequired = lastAmbientDetails?.burnInProtectionRequired == true,
+                            deviceHasLowBitAmbient = lastAmbientDetails?.deviceHasLowBitAmbient == true,
+                        )
+                    }
+                },
+            ).also { observer ->
+                ambientState.value =
+                    if (observer.isAmbient) AmbientState.Ambient() else AmbientState.Interactive
 
-            onDispose {
-                lifecycle.removeObserver(observer)
+                println("addObserver")
+                lifecycle.addObserver(observer)
             }
+        } else {
+            null
         }
     }
 
-    ambientUpdate?.let {
-        block(it)
+    val value = ambientState.value
+    SideEffect {
+        println("Side Effect $value")
+    }
+    CompositionLocalProvider(LocalAmbientState provides value) {
+        content(value)
     }
 }
 
+val LocalAmbientState = compositionLocalOf<AmbientState> { AmbientState.Inactive }
+
 private fun Context.findActivityOrNull(): Activity? {
     var context = this
     while (context is ContextWrapper) {

compose-layout/src/main/java/com/google/android/horologist/compose/ambient/AmbientAwareTime.kt

@@ -61,7 +61,7 @@ import java.time.ZonedDateTime
 @RequiresApi(Build.VERSION_CODES.O)
 @Composable
 fun AmbientAwareTime(
-    stateUpdate: AmbientStateUpdate,
+    stateUpdate: AmbientState,
     updatePeriodMillis: Long = 1000,
     block: @Composable (dateTime: ZonedDateTime, isAmbient: Boolean) -> Unit,
 ) {
@@ -75,7 +75,7 @@ fun AmbientAwareTime(
     }
 
     LaunchedEffect(stateUpdate) {
-        if (stateUpdate.ambientState == AmbientState.Interactive) {
+        if (stateUpdate.isInteractive) {
             while (isActive) {
                 isAmbient = false
                 currentTime = ZonedDateTime.now()

compose-layout/src/main/java/com/google/android/horologist/compose/ambient/AmbientStateUpdate.kt → compose-layout/src/main/java/com/google/android/horologist/compose/ambient/AmbientState.kt

@@ -16,21 +16,40 @@
 
 package com.google.android.horologist.compose.ambient
 
-import androidx.wear.ambient.AmbientLifecycleObserver
+import androidx.compose.runtime.Immutable
 
 /**
  * Represent Ambient as updates, with the state and time of change. This is necessary to ensure that
  * when the system provides a (typically) 1min-frequency callback to onUpdateAmbient, the developer
  * may wish to update composables, but the state hasn't changed.
  */
-data class AmbientStateUpdate(
-    val ambientState: AmbientState,
-    val changeTimeMillis: Long = System.currentTimeMillis(),
-)
-
+@Immutable
 sealed interface AmbientState {
-    data class Ambient(val ambientDetails: AmbientLifecycleObserver.AmbientDetails? = null) :
-        AmbientState
+    val name: String
+
+    data class Ambient(
+        val burnInProtectionRequired: Boolean = false,
+        val deviceHasLowBitAmbient: Boolean = false,
+        val updateTimeMillis: Long = System.currentTimeMillis(),
+    ) :
+        AmbientState {
+            override val name: String
+                get() = "Ambient"
+        }
+
+    data object Interactive : AmbientState {
+        override val name: String
+            get() = "Interactive"
+    }
+
+    data object Inactive : AmbientState {
+        override val name: String
+            get() = "Inactive"
+    }
+
+    val isInteractive: Boolean
+        get() = !isAmbient
 
-    object Interactive : AmbientState
+    val isAmbient: Boolean
+        get() = this is Ambient
 }

sample/src/main/AndroidManifest.xml

@@ -106,6 +106,17 @@
             </intent-filter>
         </activity>
 
+        <activity
+            android:name="com.google.android.horologist.ambient.AmbientAwareActivity"
+            android:exported="true"
+            android:label="Ambient"
+            android:taskAffinity=".ambient">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+
         <service
             android:name=".tiles.ExampleTileService"
             android:description="@string/tile_description"