AmbientLifecycleObserverKt

Added in 1.3.0

public final class AmbientLifecycleObserverKt

Summary

Public methods
static final @NonNull AmbientLifecycleObserver

Create a new AmbientLifecycleObserver for use on a real device.
static final @NonNull AmbientLifecycleObserver

Create a new AmbientLifecycleObserver for use on a real device.

Public methods

AmbientLifecycleObserver

Added in 1.3.0
public static final @NonNull AmbientLifecycleObserver AmbientLifecycleObserver(
    @NonNull Activity activity,
    @NonNull AmbientLifecycleObserver.AmbientLifecycleCallback callbacks
)

Create a new AmbientLifecycleObserver for use on a real device.

Applications which wish to show layouts in ambient mode should attach the returned observer to their activities or fragments, passing in a set of callback to be notified about ambient state. In addition, the app needs to declare that it uses the android.Manifest.permission.WAKE_LOCK permission in its manifest.

The created AmbientLifecycleObserver can also be used to query whether the device is in ambient mode.

As an example of how to use this class, see the following example:

class MyActivity : ComponentActivity() {
    private val callbacks = object : AmbientLifecycleObserver.AmbientLifecycleCallback {
        // ...
    }

    private val ambientObserver = AmbientLifecycleObserver(this, callbacks)

    override fun onCreate(savedInstanceState: Bundle) {
        super.onCreate(savedInstanceState)
        lifecycle.addObserver(ambientObserver)
    }
}
Parameters
@NonNull Activity activity

The activity that this observer is being attached to.
@NonNull AmbientLifecycleObserver.AmbientLifecycleCallback callbacks

An instance of AmbientLifecycleObserver.AmbientLifecycleCallback, used to notify the observer about changes to the ambient state.

AmbientLifecycleObserver

Added in 1.3.0
public static final @NonNull AmbientLifecycleObserver AmbientLifecycleObserver(
    @NonNull Activity activity,
    @NonNull Executor callbackExecutor,
    @NonNull AmbientLifecycleObserver.AmbientLifecycleCallback callbacks
)

Create a new AmbientLifecycleObserver for use on a real device.

Applications which wish to show layouts in ambient mode should attach the returned observer to their activities or fragments, passing in a set of callback to be notified about ambient state. In addition, the app needs to declare that it uses the android.Manifest.permission.WAKE_LOCK permission in its manifest.

The created AmbientLifecycleObserver can also be used to query whether the device is in ambient mode.

As an example of how to use this class, see the following example:

class MyActivity : ComponentActivity() {
    private val callbacks = object : AmbientLifecycleObserver.AmbientLifecycleCallback {
        // ...
    }

    private val ambientObserver = AmbientLifecycleObserver(this, mainExecutor, callbacks)

    override fun onCreate(savedInstanceState: Bundle) {
        super.onCreate(savedInstanceState)
        lifecycle.addObserver(ambientObserver)
    }
}

If the observer is registered while the device is in ambient mode, the registered callback will immediately receive a call to AmbientLifecycleObserver.AmbientLifecycleCallback.onEnterAmbient. If the device is in active mode, the callbacks will be registered, and onEnterAmbient will be called when the device next enters ambient mode.

Parameters
@NonNull Activity activity

The activity that this observer is being attached to.
@NonNull Executor callbackExecutor

The executor to run the provided callbacks on.
@NonNull AmbientLifecycleObserver.AmbientLifecycleCallback callbacks

An instance of AmbientLifecycleObserver.AmbientLifecycleCallback, used to notify the observer about changes to the ambient state.