Expands documentation for AmbientAware, adds support for AmbientDetails

compose-layout/api/current.api

@@ -9,11 +9,19 @@ package com.google.android.horologist.compose.ambient {
     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);
   }
 
-  public enum AmbientState {
-    method public static com.google.android.horologist.compose.ambient.AmbientState valueOf(String name) throws java.lang.IllegalArgumentException;
-    method public static com.google.android.horologist.compose.ambient.AmbientState[] values();
-    enum_constant public static final com.google.android.horologist.compose.ambient.AmbientState AMBIENT;
-    enum_constant public static final com.google.android.horologist.compose.ambient.AmbientState INTERACTIVE;
+  public sealed interface AmbientState {
+  }
+
+  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;
+  }
+
+  public static final class AmbientState.Interactive implements com.google.android.horologist.compose.ambient.AmbientState {
+    field public static final com.google.android.horologist.compose.ambient.AmbientState.Interactive INSTANCE;
   }
 
   public final class AmbientStateUpdate {

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

@@ -31,6 +31,12 @@ 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
  * 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.
  */
 @Composable
 fun AmbientAware(block: @Composable (AmbientStateUpdate) -> Unit) {
@@ -41,23 +47,24 @@ fun AmbientAware(block: @Composable (AmbientStateUpdate) -> Unit) {
     val observer = remember {
         val callback = object : AmbientLifecycleObserver.AmbientLifecycleCallback {
             override fun onEnterAmbient(ambientDetails: AmbientLifecycleObserver.AmbientDetails) {
-                ambientUpdate = AmbientStateUpdate(AmbientState.AMBIENT)
+                ambientUpdate = AmbientStateUpdate(AmbientState.Ambient(ambientDetails))
             }
 
             override fun onExitAmbient() {
-                ambientUpdate = AmbientStateUpdate(AmbientState.INTERACTIVE)
+                ambientUpdate = AmbientStateUpdate(AmbientState.Interactive)
             }
 
             override fun onUpdateAmbient() {
-                ambientUpdate = AmbientStateUpdate(AmbientState.AMBIENT)
+                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
+                AmbientState.Ambient(null)
             } else {
-                AmbientState.INTERACTIVE
+                AmbientState.Interactive
             }
             ambientUpdate = AmbientStateUpdate(initialAmbientState)
         }

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

@@ -75,15 +75,15 @@ fun AmbientAwareTime(
     }
 
     LaunchedEffect(stateUpdate) {
-        if (stateUpdate.ambientState == AmbientState.AMBIENT) {
-            isAmbient = true
-            currentTime = ZonedDateTime.now()
-        } else {
+        if (stateUpdate.ambientState == AmbientState.Interactive) {
             while (isActive) {
                 isAmbient = false
                 currentTime = ZonedDateTime.now()
                 delay(updatePeriodMillis - System.currentTimeMillis() % updatePeriodMillis)
             }
+        } else {
+            isAmbient = true
+            currentTime = ZonedDateTime.now()
         }
     }
 }

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

@@ -16,6 +16,8 @@
 
 package com.google.android.horologist.compose.ambient
 
+import androidx.wear.ambient.AmbientLifecycleObserver
+
 /**
  * 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
@@ -26,7 +28,9 @@ data class AmbientStateUpdate(
     val changeTimeMillis: Long = System.currentTimeMillis(),
 )
 
-enum class AmbientState {
-    AMBIENT,
-    INTERACTIVE,
+sealed interface AmbientState {
+    data class Ambient(val ambientDetails: AmbientLifecycleObserver.AmbientDetails? = null) :
+        AmbientState
+
+    object Interactive : AmbientState
 }