androidx.lifecycle.compose
Interfaces
LifecyclePauseOrDisposeEffectResult |
Interface used for |
Cmn
|
LifecycleStopOrDisposeEffectResult |
Interface used for |
Cmn
|
Classes
LifecycleResumePauseEffectScope |
Receiver scope for |
Cmn
|
LifecycleStartStopEffectScope |
Receiver scope for |
Cmn
|
Top-level functions summary
Unit |
@ComposableSchedule an effect to run when the |
Cmn
|
Unit |
@ComposableThis function is deprecated. LifecycleResumeEffect must provide one or more 'key' parameters that define the identity of the LifecycleResumeEffect and determine when its previous effect coroutine should be cancelled and a new effect launched for the new key. |
Cmn
|
Unit |
@ComposableSchedule a pair of effects to run when the |
Cmn
|
Unit |
@ComposableSchedule a pair of effects to run when the |
Cmn
|
Unit |
@ComposableSchedule a pair of effects to run when the |
Cmn
|
Unit |
@ComposableSchedule a pair of effects to run when the |
Cmn
|
Unit |
@ComposableThis function is deprecated. LifecycleStartEffect must provide one or more 'key' parameters that define the identity of the LifecycleStartEffect and determine when its previous effect coroutine should be cancelled and a new effect launched for the new key. |
Cmn
|
Unit |
@ComposableSchedule a pair of effects to run when the |
Cmn
|
Unit |
@ComposableSchedule a pair of effects to run when the |
Cmn
|
Unit |
@ComposableSchedule a pair of effects to run when the |
Cmn
|
Unit |
@ComposableSchedule a pair of effects to run when the |
Cmn
|
() -> Unit |
@ComposableReturns a new decorated function that will invoke the given |
Cmn
|
() -> Unit |
@ComposableReturns a new decorated function that will invoke the given |
Cmn
|
Extension functions summary
State<T> |
@ComposableCollects values from this |
Cmn
|
State<T> |
@ComposableCollects values from this |
Cmn
|
State<T> |
@ComposableCollects values from this |
Cmn
|
State<T> |
@ComposableCollects values from this |
Cmn
|
State<Lifecycle.State> |
Collects values from the |
Cmn
|
Top-level properties summary
ProvidableCompositionLocal<LifecycleOwner> |
The CompositionLocal containing the current |
Cmn
android
|
Top-level functions
LifecycleEventEffect
@Composable
fun LifecycleEventEffect(
event: Lifecycle.Event,
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
onEvent: () -> Unit
): Unit
Schedule an effect to run when the Lifecycle receives a specific Lifecycle.Event.
Using a LifecycleEventObserver to listen for when LifecycleEventEffect enters the composition, onEvent will be launched when receiving the specified event.
This function should not be used to listen for Lifecycle.Event.ON_DESTROY because Compose stops recomposing after receiving a Lifecycle.Event.ON_STOP and will never be aware of an ON_DESTROY to launch onEvent.
This function should also not be used to launch tasks in response to callback events by way of storing callback data as a Lifecycle.State in a MutableState. Instead, see currentStateAsState to obtain a State that may be used to launch jobs in response to state changes.
import androidx.compose.runtime.Composable
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.compose.LifecycleEventEffect
@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
LifecycleEventEffect(Lifecycle.Event.ON_RESUME) { dataAnalytics.trackScreenView("screen1") }
// ...
}
| Parameters | |
|---|---|
event: Lifecycle.Event |
The |
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current |
The lifecycle owner to attach an observer |
onEvent: () -> Unit |
The effect to be launched when we receive an |
| Throws | |
|---|---|
kotlin.IllegalArgumentException |
if attempting to listen for |
LifecycleResumeEffect
@Composable
funLifecycleResumeEffect(
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
effects: LifecycleResumePauseEffectScope.() -> LifecyclePauseOrDisposeEffectResult
): Unit
It is an error to call LifecycleStartEffect without at least one key parameter.
This deprecated-error function shadows the varargs overload so that the varargs version is not used without key parameters.
| See also | |
|---|---|
LifecycleResumeEffect |
LifecycleResumeEffect
@Composable
fun LifecycleResumeEffect(
key1: Any?,
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
effects: LifecycleResumePauseEffectScope.() -> LifecyclePauseOrDisposeEffectResult
): Unit
Schedule a pair of effects to run when the Lifecycle receives either a Lifecycle.Event.ON_RESUME or Lifecycle.Event.ON_PAUSE (or any new unique value of key1). The ON_RESUME effect will be the body of the effects block and the ON_PAUSE effect will be within the (onPauseOrDispose clause)LifecycleResumePauseEffectScope.onPauseOrDispose:
LifecycleResumeEffect(lifecycleOwner) {
// add ON_RESUME effect here
onPauseOrDispose {
// add clean up for work kicked off in the ON_RESUME effect here
}
}
import androidx.compose.runtime.Composable
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.compose.LifecycleResumeEffect
@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
LifecycleResumeEffect(dataAnalytics) {
val timeTracker = dataAnalytics.startTimeTracking()
onPauseOrDispose { timeTracker.stopTimeTracking() }
}
// ...
}
A LifecycleResumeEffect must include an onPauseOrDispose clause as the final statement in its effects block. If your operation does not require an effect for both Lifecycle.Event.ON_RESUME and Lifecycle.Event.ON_PAUSE, a LifecycleEventEffect should be used instead.
A LifecycleResumeEffect's key is a value that defines the identity of the effect. If a key changes, the LifecycleResumeEffect must dispose its current effects and reset by calling effects again. Examples of keys include:
-
Observable objects that the effect subscribes to
-
Unique request parameters to an operation that must cancel and retry if those parameters change
This function uses a LifecycleEventObserver to listen for when LifecycleResumeEffect enters the composition and the effects will be launched when receiving a Lifecycle.Event.ON_RESUME or Lifecycle.Event.ON_PAUSE event, respectively. If the LifecycleResumeEffect leaves the composition prior to receiving an Lifecycle.Event.ON_PAUSE event, onPauseOrDispose will be called to clean up the work that was kicked off in the ON_RESUME effect.
This function should not be used to launch tasks in response to callback events by way of storing callback data as a Lifecycle.State in a MutableState. Instead, see currentStateAsState to obtain a State that may be used to launch jobs in response to state changes.
| Parameters | |
|---|---|
key1: Any? |
The unique value to trigger recomposition upon change |
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current |
The lifecycle owner to attach an observer |
effects: LifecycleResumePauseEffectScope.() -> LifecyclePauseOrDisposeEffectResult |
The effects to be launched when we receive the respective event callbacks |
LifecycleResumeEffect
@Composable
fun LifecycleResumeEffect(
vararg keys: Any?,
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
effects: LifecycleResumePauseEffectScope.() -> LifecyclePauseOrDisposeEffectResult
): Unit
Schedule a pair of effects to run when the Lifecycle receives either a Lifecycle.Event.ON_RESUME or Lifecycle.Event.ON_PAUSE (or any new unique value of keys). The ON_RESUME effect will be the body of the effects block and the ON_PAUSE effect will be within the (onPauseOrDispose clause)LifecycleResumePauseEffectScope.onPauseOrDispose:
LifecycleResumeEffect(lifecycleOwner) {
// add ON_RESUME effect here
onPauseOrDispose {
// add clean up for work kicked off in the ON_RESUME effect here
}
}
import androidx.compose.runtime.Composable
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.compose.LifecycleResumeEffect
@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
LifecycleResumeEffect(dataAnalytics) {
val timeTracker = dataAnalytics.startTimeTracking()
onPauseOrDispose { timeTracker.stopTimeTracking() }
}
// ...
}
A LifecycleResumeEffect must include an onPauseOrDispose clause as the final statement in its effects block. If your operation does not require an effect for both Lifecycle.Event.ON_RESUME and Lifecycle.Event.ON_PAUSE, a LifecycleEventEffect should be used instead.
A LifecycleResumeEffect's key is a value that defines the identity of the effect. If a key changes, the LifecycleResumeEffect must dispose its current effects and reset by calling effects again. Examples of keys include:
-
Observable objects that the effect subscribes to
-
Unique request parameters to an operation that must cancel and retry if those parameters change
This function uses a LifecycleEventObserver to listen for when LifecycleResumeEffect enters the composition and the effects will be launched when receiving a Lifecycle.Event.ON_RESUME or Lifecycle.Event.ON_PAUSE event, respectively. If the LifecycleResumeEffect leaves the composition prior to receiving an Lifecycle.Event.ON_PAUSE event, onPauseOrDispose will be called to clean up the work that was kicked off in the ON_RESUME effect.
This function should not be used to launch tasks in response to callback events by way of storing callback data as a Lifecycle.State in a MutableState. Instead, see currentStateAsState to obtain a State that may be used to launch jobs in response to state changes.
| Parameters | |
|---|---|
vararg keys: Any? |
The unique values to trigger recomposition upon changes |
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current |
The lifecycle owner to attach an observer |
effects: LifecycleResumePauseEffectScope.() -> LifecyclePauseOrDisposeEffectResult |
The effects to be launched when we receive the respective event callbacks |
LifecycleResumeEffect
@Composable
fun LifecycleResumeEffect(
key1: Any?,
key2: Any?,
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
effects: LifecycleResumePauseEffectScope.() -> LifecyclePauseOrDisposeEffectResult
): Unit
Schedule a pair of effects to run when the Lifecycle receives either a Lifecycle.Event.ON_RESUME or Lifecycle.Event.ON_PAUSE (or any new unique value of key1 or key2). The ON_RESUME effect will be the body of the effects block and the ON_PAUSE effect will be within the (onPauseOrDispose clause)LifecycleResumePauseEffectScope.onPauseOrDispose:
LifecycleResumeEffect(lifecycleOwner) {
// add ON_RESUME effect here
onPauseOrDispose {
// add clean up for work kicked off in the ON_RESUME effect here
}
}
import androidx.compose.runtime.Composable
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.compose.LifecycleResumeEffect
@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
LifecycleResumeEffect(dataAnalytics) {
val timeTracker = dataAnalytics.startTimeTracking()
onPauseOrDispose { timeTracker.stopTimeTracking() }
}
// ...
}
A LifecycleResumeEffect must include an onPauseOrDispose clause as the final statement in its effects block. If your operation does not require an effect for both Lifecycle.Event.ON_RESUME and Lifecycle.Event.ON_PAUSE, a LifecycleEventEffect should be used instead.
A LifecycleResumeEffect's key is a value that defines the identity of the effect. If a key changes, the LifecycleResumeEffect must dispose its current effects and reset by calling effects again. Examples of keys include:
-
Observable objects that the effect subscribes to
-
Unique request parameters to an operation that must cancel and retry if those parameters change
This function uses a LifecycleEventObserver to listen for when LifecycleResumeEffect enters the composition and the effects will be launched when receiving a Lifecycle.Event.ON_RESUME or Lifecycle.Event.ON_PAUSE event, respectively. If the LifecycleResumeEffect leaves the composition prior to receiving an Lifecycle.Event.ON_PAUSE event, onPauseOrDispose will be called to clean up the work that was kicked off in the ON_RESUME effect.
This function should not be used to launch tasks in response to callback events by way of storing callback data as a Lifecycle.State in a MutableState. Instead, see currentStateAsState to obtain a State that may be used to launch jobs in response to state changes.
| Parameters | |
|---|---|
key1: Any? |
A unique value to trigger recomposition upon change |
key2: Any? |
A unique value to trigger recomposition upon change |
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current |
The lifecycle owner to attach an observer |
effects: LifecycleResumePauseEffectScope.() -> LifecyclePauseOrDisposeEffectResult |
The effects to be launched when we receive the respective event callbacks |
LifecycleResumeEffect
@Composable
fun LifecycleResumeEffect(
key1: Any?,
key2: Any?,
key3: Any?,
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
effects: LifecycleResumePauseEffectScope.() -> LifecyclePauseOrDisposeEffectResult
): Unit
Schedule a pair of effects to run when the Lifecycle receives either a Lifecycle.Event.ON_RESUME or Lifecycle.Event.ON_PAUSE (or any new unique value of key1 or key2 or key3). The ON_RESUME effect will be the body of the effects block and the ON_PAUSE effect will be within the (onPauseOrDispose clause)LifecycleResumePauseEffectScope.onPauseOrDispose:
LifecycleResumeEffect(lifecycleOwner) {
// add ON_RESUME effect here
onPauseOrDispose {
// add clean up for work kicked off in the ON_RESUME effect here
}
}
import androidx.compose.runtime.Composable
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.compose.LifecycleResumeEffect
@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
LifecycleResumeEffect(dataAnalytics) {
val timeTracker = dataAnalytics.startTimeTracking()
onPauseOrDispose { timeTracker.stopTimeTracking() }
}
// ...
}
A LifecycleResumeEffect must include an onPauseOrDispose clause as the final statement in its effects block. If your operation does not require an effect for both Lifecycle.Event.ON_RESUME and Lifecycle.Event.ON_PAUSE, a LifecycleEventEffect should be used instead.
A LifecycleResumeEffect's key is a value that defines the identity of the effect. If a key changes, the LifecycleResumeEffect must dispose its current effects and reset by calling effects again. Examples of keys include:
-
Observable objects that the effect subscribes to
-
Unique request parameters to an operation that must cancel and retry if those parameters change
This function uses a LifecycleEventObserver to listen for when LifecycleResumeEffect enters the composition and the effects will be launched when receiving a Lifecycle.Event.ON_RESUME or Lifecycle.Event.ON_PAUSE event, respectively. If the LifecycleResumeEffect leaves the composition prior to receiving an Lifecycle.Event.ON_PAUSE event, onPauseOrDispose will be called to clean up the work that was kicked off in the ON_RESUME effect.
This function should not be used to launch tasks in response to callback events by way of storing callback data as a Lifecycle.State in a MutableState. Instead, see currentStateAsState to obtain a State that may be used to launch jobs in response to state changes.
| Parameters | |
|---|---|
key1: Any? |
A unique value to trigger recomposition upon change |
key2: Any? |
A unique value to trigger recomposition upon change |
key3: Any? |
A unique value to trigger recomposition upon change |
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current |
The lifecycle owner to attach an observer |
effects: LifecycleResumePauseEffectScope.() -> LifecyclePauseOrDisposeEffectResult |
The effects to be launched when we receive the respective event callbacks |
LifecycleStartEffect
@Composable
funLifecycleStartEffect(
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
effects: LifecycleStartStopEffectScope.() -> LifecycleStopOrDisposeEffectResult
): Unit
It is an error to call LifecycleStartEffect without at least one key parameter.
This deprecated-error function shadows the varargs overload so that the varargs version is not used without key parameters.
| See also | |
|---|---|
LifecycleStartEffect |
LifecycleStartEffect
@Composable
fun LifecycleStartEffect(
key1: Any?,
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
effects: LifecycleStartStopEffectScope.() -> LifecycleStopOrDisposeEffectResult
): Unit
Schedule a pair of effects to run when the Lifecycle receives either a Lifecycle.Event.ON_START or Lifecycle.Event.ON_STOP (or any new unique value of key1). The ON_START effect will be the body of the effects block and the ON_STOP effect will be within the (onStopOrDispose clause)LifecycleStartStopEffectScope.onStopOrDispose:
LifecycleStartEffect(lifecycleOwner) {
// add ON_START effect here
onStopOrDispose {
// add clean up for work kicked off in the ON_START effect here
}
}
import androidx.compose.runtime.Composable
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.compose.LifecycleStartEffect
@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
LifecycleStartEffect(dataAnalytics) {
val timeTracker = dataAnalytics.startTimeTracking()
onStopOrDispose { timeTracker.stopTimeTracking() }
}
// ...
}
A LifecycleStartEffect must include an onStopOrDispose clause as the final statement in its effects block. If your operation does not require an effect for both Lifecycle.Event.ON_START and Lifecycle.Event.ON_STOP, a LifecycleEventEffect should be used instead.
A LifecycleStartEffect's key is a value that defines the identity of the effect. If the key changes, the LifecycleStartEffect must dispose its current effects and reset by calling effects again. Examples of keys include:
-
Observable objects that the effect subscribes to
-
Unique request parameters to an operation that must cancel and retry if those parameters change
This function uses a LifecycleEventObserver to listen for when LifecycleStartEffect enters the composition and the effects will be launched when receiving a Lifecycle.Event.ON_START or Lifecycle.Event.ON_STOP event, respectively. If the LifecycleStartEffect leaves the composition prior to receiving an Lifecycle.Event.ON_STOP event, onStopOrDispose will be called to clean up the work that was kicked off in the ON_START effect.
This function should not be used to launch tasks in response to callback events by way of storing callback data as a Lifecycle.State in a MutableState. Instead, see currentStateAsState to obtain a State that may be used to launch jobs in response to state changes.
| Parameters | |
|---|---|
key1: Any? |
The unique value to trigger recomposition upon change |
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current |
The lifecycle owner to attach an observer |
effects: LifecycleStartStopEffectScope.() -> LifecycleStopOrDisposeEffectResult |
The effects to be launched when we receive the respective event callbacks |
LifecycleStartEffect
@Composable
fun LifecycleStartEffect(
vararg keys: Any?,
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
effects: LifecycleStartStopEffectScope.() -> LifecycleStopOrDisposeEffectResult
): Unit
Schedule a pair of effects to run when the Lifecycle receives either a Lifecycle.Event.ON_START or Lifecycle.Event.ON_STOP (or any new unique value of keys). The ON_START effect will be the body of the effects block and the ON_STOP effect will be within the (onStopOrDispose clause)LifecycleStartStopEffectScope.onStopOrDispose:
LifecycleStartEffect(lifecycleOwner) {
// add ON_START effect here
onStopOrDispose {
// add clean up for work kicked off in the ON_START effect here
}
}
import androidx.compose.runtime.Composable
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.compose.LifecycleStartEffect
@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
LifecycleStartEffect(dataAnalytics) {
val timeTracker = dataAnalytics.startTimeTracking()
onStopOrDispose { timeTracker.stopTimeTracking() }
}
// ...
}
A LifecycleStartEffect must include an onStopOrDispose clause as the final statement in its effects block. If your operation does not require an effect for both Lifecycle.Event.ON_START and Lifecycle.Event.ON_STOP, a LifecycleEventEffect should be used instead.
A LifecycleStartEffect's key is a value that defines the identity of the effect. If a key changes, the LifecycleStartEffect must dispose its current effects and reset by calling effects again. Examples of keys include:
-
Observable objects that the effect subscribes to
-
Unique request parameters to an operation that must cancel and retry if those parameters change
This function uses a LifecycleEventObserver to listen for when LifecycleStartEffect enters the composition and the effects will be launched when receiving a Lifecycle.Event.ON_START or Lifecycle.Event.ON_STOP event, respectively. If the LifecycleStartEffect leaves the composition prior to receiving an Lifecycle.Event.ON_STOP event, onStopOrDispose will be called to clean up the work that was kicked off in the ON_START effect.
This function should not be used to launch tasks in response to callback events by way of storing callback data as a Lifecycle.State in a MutableState. Instead, see currentStateAsState to obtain a State that may be used to launch jobs in response to state changes.
| Parameters | |
|---|---|
vararg keys: Any? |
The unique values to trigger recomposition upon changes |
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current |
The lifecycle owner to attach an observer |
effects: LifecycleStartStopEffectScope.() -> LifecycleStopOrDisposeEffectResult |
The effects to be launched when we receive the respective event callbacks |
LifecycleStartEffect
@Composable
fun LifecycleStartEffect(
key1: Any?,
key2: Any?,
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
effects: LifecycleStartStopEffectScope.() -> LifecycleStopOrDisposeEffectResult
): Unit
Schedule a pair of effects to run when the Lifecycle receives either a Lifecycle.Event.ON_START or Lifecycle.Event.ON_STOP (or any new unique value of key1 or key2). The ON_START effect will be the body of the effects block and the ON_STOP effect will be within the (onStopOrDispose clause)LifecycleStartStopEffectScope.onStopOrDispose:
LifecycleStartEffect(lifecycleOwner) {
// add ON_START effect here
onStopOrDispose {
// add clean up for work kicked off in the ON_START effect here
}
}
import androidx.compose.runtime.Composable
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.compose.LifecycleStartEffect
@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
LifecycleStartEffect(dataAnalytics) {
val timeTracker = dataAnalytics.startTimeTracking()
onStopOrDispose { timeTracker.stopTimeTracking() }
}
// ...
}
A LifecycleStartEffect must include an onStopOrDispose clause as the final statement in its effects block. If your operation does not require an effect for both Lifecycle.Event.ON_START and Lifecycle.Event.ON_STOP, a LifecycleEventEffect should be used instead.
A LifecycleStartEffect's key is a value that defines the identity of the effect. If a key changes, the LifecycleStartEffect must dispose its current effects and reset by calling effects again. Examples of keys include:
-
Observable objects that the effect subscribes to
-
Unique request parameters to an operation that must cancel and retry if those parameters change
This function uses a LifecycleEventObserver to listen for when LifecycleStartEffect enters the composition and the effects will be launched when receiving a Lifecycle.Event.ON_START or Lifecycle.Event.ON_STOP event, respectively. If the LifecycleStartEffect leaves the composition prior to receiving an Lifecycle.Event.ON_STOP event, onStopOrDispose will be called to clean up the work that was kicked off in the ON_START effect.
This function should not be used to launch tasks in response to callback events by way of storing callback data as a Lifecycle.State in a MutableState. Instead, see currentStateAsState to obtain a State that may be used to launch jobs in response to state changes.
| Parameters | |
|---|---|
key1: Any? |
A unique value to trigger recomposition upon change |
key2: Any? |
A unique value to trigger recomposition upon change |
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current |
The lifecycle owner to attach an observer |
effects: LifecycleStartStopEffectScope.() -> LifecycleStopOrDisposeEffectResult |
The effects to be launched when we receive the respective event callbacks |
LifecycleStartEffect
@Composable
fun LifecycleStartEffect(
key1: Any?,
key2: Any?,
key3: Any?,
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
effects: LifecycleStartStopEffectScope.() -> LifecycleStopOrDisposeEffectResult
): Unit
Schedule a pair of effects to run when the Lifecycle receives either a Lifecycle.Event.ON_START or Lifecycle.Event.ON_STOP (or any new unique value of key1 or key2 or key3). The ON_START effect will be the body of the effects block and the ON_STOP effect will be within the (onStopOrDispose clause)LifecycleStartStopEffectScope.onStopOrDispose:
LifecycleStartEffect(lifecycleOwner) {
// add ON_START effect here
onStopOrDispose {
// add clean up for work kicked off in the ON_START effect here
}
}
import androidx.compose.runtime.Composable
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.compose.LifecycleStartEffect
@Composable
fun Analytics(dataAnalytics: DataAnalytics) {
LifecycleStartEffect(dataAnalytics) {
val timeTracker = dataAnalytics.startTimeTracking()
onStopOrDispose { timeTracker.stopTimeTracking() }
}
// ...
}
A LifecycleStartEffect must include an onStopOrDispose clause as the final statement in its effects block. If your operation does not require an effect for both Lifecycle.Event.ON_START and Lifecycle.Event.ON_STOP, a LifecycleEventEffect should be used instead.
A LifecycleStartEffect's key is a value that defines the identity of the effect. If a key changes, the LifecycleStartEffect must dispose its current effects and reset by calling effects again. Examples of keys include:
-
Observable objects that the effect subscribes to
-
Unique request parameters to an operation that must cancel and retry if those parameters change
This function uses a LifecycleEventObserver to listen for when LifecycleStartEffect enters the composition and the effects will be launched when receiving a Lifecycle.Event.ON_START or Lifecycle.Event.ON_STOP event, respectively. If the LifecycleStartEffect leaves the composition prior to receiving an Lifecycle.Event.ON_STOP event, onStopOrDispose will be called to clean up the work that was kicked off in the ON_START effect.
This function should not be used to launch tasks in response to callback events by way of storing callback data as a Lifecycle.State in a MutableState. Instead, see currentStateAsState to obtain a State that may be used to launch jobs in response to state changes.
| Parameters | |
|---|---|
key1: Any? |
The unique value to trigger recomposition upon change |
key2: Any? |
The unique value to trigger recomposition upon change |
key3: Any? |
The unique value to trigger recomposition upon change |
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current |
The lifecycle owner to attach an observer |
effects: LifecycleStartStopEffectScope.() -> LifecycleStopOrDisposeEffectResult |
The effects to be launched when we receive the respective event callbacks |
dropUnlessResumed
@Composable
fun dropUnlessResumed(
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
block: () -> Unit
): () -> Unit
Returns a new decorated function that will invoke the given block if the lifecycleOwner's lifecycle state is at least State.RESUMED. Otherwise, block is not invoked.
For Navigation users, it's recommended to safeguard navigate methods when using them while a composable is in transition as a result of navigation.
import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.lifecycle.compose.dropUnlessResumed
Button(
onClick =
dropUnlessResumed {
// Run on clicks only when the lifecycle is at least RESUMED.
// Example: navController.navigate("next_screen")
},
) {
Text(text = "Navigate to next screen")
}
| Parameters | |
|---|---|
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current |
The |
block: () -> Unit |
The callback to be executed when the observed lifecycle state is at least |
| Returns | |
|---|---|
() -> Unit |
A decorated function that invoke |
dropUnlessStarted
@Composable
fun dropUnlessStarted(
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
block: () -> Unit
): () -> Unit
Returns a new decorated function that will invoke the given block if the lifecycleOwner's lifecycle state is at least State.STARTED. Otherwise, block is not invoked.
import androidx.compose.material.Button
import androidx.compose.material.Text
import androidx.lifecycle.compose.dropUnlessStarted
Button(
onClick =
dropUnlessStarted {
// Run on clicks only when the lifecycle is at least STARTED.
// Example: navController.navigate("next_screen")
},
) {
Text(text = "Navigate to next screen")
}
| Parameters | |
|---|---|
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current |
The |
block: () -> Unit |
The callback to be executed when the observed lifecycle state is at least |
| Returns | |
|---|---|
() -> Unit |
A decorated function that invoke |
Extension functions
collectAsStateWithLifecycle
@Composable
fun <T : Any?> StateFlow<T>.collectAsStateWithLifecycle(
lifecycle: Lifecycle,
minActiveState: Lifecycle.State = Lifecycle.State.STARTED,
context: CoroutineContext = EmptyCoroutineContext
): State<T>
Collects values from this StateFlow and represents its latest value via State in a lifecycle-aware manner.
The StateFlow.value is used as an initial value. Every time there would be new value posted into the StateFlow the returned State will be updated causing recomposition of every State.value usage whenever the lifecycle is at least minActiveState.
This StateFlow is collected every time lifecycle reaches the minActiveState Lifecycle state. The collection stops when lifecycle falls below minActiveState.
import androidx.compose.material.Text
import androidx.compose.runtime.remember
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.compose.collectAsStateWithLifecycle
class ExampleState {
private val _uiState = MutableStateFlow("")
val uiState: StateFlow<String> = _uiState.asStateFlow()
}
val state = remember { ExampleState() }
val uiState by state.uiState.collectAsStateWithLifecycle()
Text(text = uiState)
Warning: Lifecycle.State.INITIALIZED is not allowed in this API. Passing it as a parameter will throw an IllegalArgumentException.
| Parameters | |
|---|---|
lifecycle: Lifecycle |
|
minActiveState: Lifecycle.State = Lifecycle.State.STARTED |
|
context: CoroutineContext = EmptyCoroutineContext |
|
collectAsStateWithLifecycle
@Composable
fun <T : Any?> StateFlow<T>.collectAsStateWithLifecycle(
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
minActiveState: Lifecycle.State = Lifecycle.State.STARTED,
context: CoroutineContext = EmptyCoroutineContext
): State<T>
Collects values from this StateFlow and represents its latest value via State in a lifecycle-aware manner.
The StateFlow.value is used as an initial value. Every time there would be new value posted into the StateFlow the returned State will be updated causing recomposition of every State.value usage whenever the lifecycleOwner's lifecycle is at least minActiveState.
This StateFlow is collected every time the lifecycleOwner's lifecycle reaches the minActiveState Lifecycle state. The collection stops when the lifecycleOwner's lifecycle falls below minActiveState.
import androidx.compose.material.Text
import androidx.compose.runtime.remember
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.compose.collectAsStateWithLifecycle
class ExampleState {
private val _uiState = MutableStateFlow("")
val uiState: StateFlow<String> = _uiState.asStateFlow()
}
val state = remember { ExampleState() }
val uiState by state.uiState.collectAsStateWithLifecycle()
Text(text = uiState)
Warning: Lifecycle.State.INITIALIZED is not allowed in this API. Passing it as a parameter will throw an IllegalArgumentException.
| Parameters | |
|---|---|
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current |
|
minActiveState: Lifecycle.State = Lifecycle.State.STARTED |
|
context: CoroutineContext = EmptyCoroutineContext |
|
collectAsStateWithLifecycle
@Composable
fun <T : Any?> Flow<T>.collectAsStateWithLifecycle(
initialValue: T,
lifecycle: Lifecycle,
minActiveState: Lifecycle.State = Lifecycle.State.STARTED,
context: CoroutineContext = EmptyCoroutineContext
): State<T>
Collects values from this Flow and represents its latest value via State in a lifecycle-aware manner.
Every time there would be new value posted into the Flow the returned State will be updated causing recomposition of every State.value usage whenever the lifecycle is at least minActiveState.
This Flow is collected every time lifecycle reaches the minActiveState Lifecycle state. The collection stops when lifecycle falls below minActiveState.
import androidx.compose.material.Text
import androidx.compose.runtime.remember
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.compose.collectAsStateWithLifecycle
class ExampleState {
val counter = flow {
var count = 0
while (true) {
emit(count++)
delay(1000)
}
}
}
val state = remember { ExampleState() }
val count by state.counter.collectAsStateWithLifecycle(initialValue = 0)
Text(text = "$count")
Warning: Lifecycle.State.INITIALIZED is not allowed in this API. Passing it as a parameter will throw an IllegalArgumentException.
| Parameters | |
|---|---|
initialValue: T |
The initial value given to the returned |
lifecycle: Lifecycle |
|
minActiveState: Lifecycle.State = Lifecycle.State.STARTED |
|
context: CoroutineContext = EmptyCoroutineContext |
|
collectAsStateWithLifecycle
@Composable
fun <T : Any?> Flow<T>.collectAsStateWithLifecycle(
initialValue: T,
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current,
minActiveState: Lifecycle.State = Lifecycle.State.STARTED,
context: CoroutineContext = EmptyCoroutineContext
): State<T>
Collects values from this Flow and represents its latest value via State in a lifecycle-aware manner.
Every time there would be new value posted into the Flow the returned State will be updated causing recomposition of every State.value usage whenever the lifecycleOwner's lifecycle is at least minActiveState.
This Flow is collected every time the lifecycleOwner's lifecycle reaches the minActiveState Lifecycle state. The collection stops when the lifecycleOwner's lifecycle falls below minActiveState.
import androidx.compose.material.Text
import androidx.compose.runtime.remember
import androidx.lifecycle.Lifecycle
import androidx.lifecycle.compose.collectAsStateWithLifecycle
class ExampleState {
val counter = flow {
var count = 0
while (true) {
emit(count++)
delay(1000)
}
}
}
val state = remember { ExampleState() }
val count by state.counter.collectAsStateWithLifecycle(initialValue = 0)
Text(text = "$count")
Warning: Lifecycle.State.INITIALIZED is not allowed in this API. Passing it as a parameter will throw an IllegalArgumentException.
| Parameters | |
|---|---|
initialValue: T |
The initial value given to the returned |
lifecycleOwner: LifecycleOwner = LocalLifecycleOwner.current |
|
minActiveState: Lifecycle.State = Lifecycle.State.STARTED |
|
context: CoroutineContext = EmptyCoroutineContext |
|
currentStateAsState
@Composable
fun Lifecycle.currentStateAsState(): State<Lifecycle.State>
Collects values from the Lifecycle.currentStateFlow and represents its latest value via State. The StateFlow.value is used as an initial value. Every time there would be new value posted into the StateFlow the returned State will be updated causing recomposition of every State.value usage.
Top-level properties
LocalLifecycleOwner
val LocalLifecycleOwner: ProvidableCompositionLocal<LifecycleOwner>
The CompositionLocal containing the current LifecycleOwner.