LiveData
abstract class LiveData<T : Any!>
kotlin.Any | |
↳ | androidx.lifecycle.LiveData |
LiveData is a data holder class that can be observed within a given lifecycle. This means that an Observer
can be added in a pair with a LifecycleOwner
, and this observer will be notified about modifications of the wrapped data only if the paired LifecycleOwner is in active state. LifecycleOwner is considered as active, if its state is Lifecycle.State#STARTED
or Lifecycle.State#RESUMED
. An observer added via observeForever(Observer)
is considered as always active and thus will be always notified about modifications. For those observers, you should manually call removeObserver(Observer)
.
An observer added with a Lifecycle will be automatically removed if the corresponding Lifecycle moves to Lifecycle.State#DESTROYED
state. This is especially useful for activities and fragments where they can safely observe LiveData and not worry about leaks: they will be instantly unsubscribed when they are destroyed.
In addition, LiveData has LiveData#onActive()
and LiveData#onInactive()
methods to get notified when number of active Observer
s change between 0 and 1. This allows LiveData to release any heavy resources when it does not have any Observers that are actively observing.
This class is designed to hold individual data fields of ViewModel
, but can also be used for sharing data between different modules in your application in a decoupled fashion.
Summary
Public constructors | |
---|---|
<init>(value: T) Creates a LiveData initialized with the given |
|
<init>() Creates a LiveData with no value assigned to it. |
Public methods | |
---|---|
open T? |
getValue() Returns the current value. |
open Boolean |
Returns true if this LiveData has active observers. |
open Boolean |
Returns true if this LiveData has observers. |
open Unit |
observe(@NonNull owner: LifecycleOwner, @NonNull observer: Observer<in T>) Adds the given observer to the observers list within the lifespan of the given owner. |
open Unit |
observeForever(@NonNull observer: Observer<in T>) Adds the given observer to the observers list. |
open Unit |
removeObserver(@NonNull observer: Observer<in T>) Removes the given observer from the observers list. |
open Unit |
removeObservers(@NonNull owner: LifecycleOwner) Removes all observers that are tied to the given |
Protected methods | |
---|---|
open Unit |
onActive() Called when the number of active observers change from 0 to 1. |
open Unit |
Called when the number of active observers change from 1 to 0. |
open Unit |
postValue(value: T) Posts a task to a main thread to set the given value. |
open Unit |
setValue(value: T) Sets the value. |
Extension functions | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
From androidx.lifecycle
|
||||||||||||
From androidx.paging
|
||||||||||||
From androidx.compose.runtime.livedata
|
Public constructors
<init>
LiveData(value: T)
Creates a LiveData initialized with the given value
.
Parameters | |
---|---|
value |
T: initial value |
<init>
LiveData()
Creates a LiveData with no value assigned to it.
Public methods
getValue
@Nullable open fun getValue(): T?
Returns the current value. Note that calling this method on a background thread does not guarantee that the latest value set will be received.
Return | |
---|---|
T? |
the current value |
hasActiveObservers
open fun hasActiveObservers(): Boolean
Returns true if this LiveData has active observers.
Return | |
---|---|
Boolean |
true if this LiveData has active observers |
hasObservers
open fun hasObservers(): Boolean
Returns true if this LiveData has observers.
Return | |
---|---|
Boolean |
true if this LiveData has observers |
observe
@MainThread open fun observe(
@NonNull owner: LifecycleOwner,
@NonNull observer: Observer<in T>
): Unit
Adds the given observer to the observers list within the lifespan of the given owner. The events are dispatched on the main thread. If LiveData already has data set, it will be delivered to the observer.
The observer will only receive events if the owner is in Lifecycle.State#STARTED
or Lifecycle.State#RESUMED
state (active).
If the owner moves to the Lifecycle.State#DESTROYED
state, the observer will automatically be removed.
When data changes while the owner
is not active, it will not receive any updates. If it becomes active again, it will receive the last available data automatical