LiveData

LiveData

public LiveData()

Creates a LiveData with no value assigned to it.

LiveData

public LiveData(T value)

Creates a LiveData initialized with the given value.

getValue

public @Nullable T getValue()

Returns the current value. Note that calling this method on a background thread does not guarantee that the latest value set will be received.

hasActiveObservers

public boolean hasActiveObservers()

Returns true if this LiveData has active observers.

hasObservers

public boolean hasObservers()

Returns true if this LiveData has observers.

observe

@MainThread
public void observe(@NonNull LifecycleOwner owner, @NonNull Observer<Object> observer)

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 STARTED or RESUMED state (active).

If the owner moves to the 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 automatically.

LiveData keeps a strong reference to the observer and the owner as long as the given LifecycleOwner is not destroyed. When it is destroyed, LiveData removes references to the observer &the; owner.

If the given owner is already in DESTROYED state, LiveData ignores the call.

If the given owner, observer tuple is already in the list, the call is ignored. If the observer is already in the list with another owner, LiveData throws an IllegalArgumentException.

observeForever

@MainThread
public void observeForever(@NonNull Observer<Object> observer)

Adds the given observer to the observers list. This call is similar to observe with a LifecycleOwner, which is always active. This means that the given observer will receive all events and will never be automatically removed. You should manually call removeObserver to stop observing this LiveData. While LiveData has one of such observers, it will be considered as active.

If the observer was already added with an owner to this LiveData, LiveData throws an IllegalArgumentException.

removeObserver

@MainThread
public void removeObserver(@NonNull Observer<Object> observer)

Removes the given observer from the observers list.

removeObservers

@MainThread
public void removeObservers(@NonNull LifecycleOwner owner)

Removes all observers that are tied to the given LifecycleOwner.

FlowLiveDataConversions.asFlow

public final @NonNull Flow<@NonNull T> <T extends Object> FlowLiveDataConversions.asFlow(
    @NonNull LiveData<@NonNull T> receiver
)

Creates a Flow containing values dispatched by originating LiveData: at the start a flow collector receives the latest value held by LiveData and then observes LiveData updates.

When a collection of the returned flow starts the originating LiveData becomes active. Similarly, when a collection completes LiveData becomes inactive.

BackPressure: the returned flow is conflated. There is no mechanism to suspend an emission by LiveData due to a slow collector, so collector always gets the most recent value emitted.

LiveDataKt.observe

@MainThread
public final @NonNull Observer<@NonNull T> <T extends Object> LiveDataKt.observe(
    @NonNull LiveData<@NonNull T> receiver,
    @NonNull LifecycleOwner owner,
    @NonNull Function1<@NonNull T, Unit> onChanged
)

Adds the given onChanged lambda as an observer within the lifespan of the given owner and returns a reference to observer. The events are dispatched on the main thread. If LiveData already has data set, it will be delivered to the onChanged.

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 automatically.

LiveData keeps a strong reference to the observer and the owner as long as the given LifecycleOwner is not destroyed. When it is destroyed, LiveData removes references to the observer and the owner.

If the given owner is already in Lifecycle.State.DESTROYED state, LiveData ignores the call.

LiveDataReactiveSteamsKt.toPublisher

public final @NonNull Publisher<@NonNull T> <T extends Object> LiveDataReactiveSteamsKt.toPublisher(
    @NonNull LiveData<@NonNull T> receiver,
    @NonNull LifecycleOwner lifecycle
)

Adapts the given LiveData stream to a ReactiveStreams Publisher.

PagingLiveData.cachedIn

public final @NonNull LiveData<@NonNull PagingData<@NonNull T>> <T extends Object> PagingLiveData.cachedIn(
    @NonNull LiveData<@NonNull PagingData<@NonNull T>> receiver,
    @NonNull Lifecycle lifecycle
)

Operator which caches a LiveData of PagingData within the scope of a Lifecycle.

cachedIn multicasts pages loaded and transformed by a PagingData, allowing multiple observers on the same instance of PagingData to receive the same events, avoiding redundant work, but comes at the cost of buffering those pages in memory.

Calling cachedIn is required to allow calling androidx.paging.AsyncPagingDataAdapter on the same instance of PagingData emitted by Pager or any of its transformed derivatives, as reloading data from scratch on the same generation of PagingData is an unsupported operation.

PagingLiveData.cachedIn

public final @NonNull LiveData<@NonNull PagingData<@NonNull T>> <T extends Object> PagingLiveData.cachedIn(
    @NonNull LiveData<@NonNull PagingData<@NonNull T>> receiver,
    @NonNull ViewModel viewModel
)

Operator which caches a LiveData of PagingData within the scope of a ViewModel.

cachedIn multicasts pages loaded and transformed by a PagingData, allowing multiple observers on the same instance of PagingData to receive the same events, avoiding redundant work, but comes at the cost of buffering those pages in memory.

Calling cachedIn is required to allow calling androidx.paging.AsyncPagingDataAdapter on the same instance of PagingData emitted by Pager or any of its transformed derivatives, as reloading data from scratch on the same generation of PagingData is an unsupported operation.

PagingLiveData.cachedIn

public final @NonNull LiveData<@NonNull PagingData<@NonNull T>> <T extends Object> PagingLiveData.cachedIn(
    @NonNull LiveData<@NonNull PagingData<@NonNull T>> receiver,
    @NonNull CoroutineScope scope
)

Operator which caches a LiveData of PagingData within a CoroutineScope.

cachedIn multicasts pages loaded and transformed by a PagingData, allowing multiple observers on the same instance of PagingData to receive the same events, avoiding redundant work, but comes at the cost of buffering those pages in memory.

Calling cachedIn is required to allow calling androidx.paging.AsyncPagingDataAdapter on the same instance of PagingData emitted by Pager or any of its transformed derivatives, as reloading data from scratch on the same generation of PagingData is an unsupported operation.

TransformationsKt.distinctUntilChanged

public final @NonNull LiveData<@NonNull X> <X extends Object> TransformationsKt.distinctUntilChanged(
    @NonNull LiveData<@NonNull X> receiver
)

Creates a new LiveData object does not emit a value until the source this LiveData value has been changed. The value is considered changed if equals() yields false.

TransformationsKt.map

public final @NonNull LiveData<@NonNull Y> <X extends Object, Y extends Object> TransformationsKt.map(
    @NonNull LiveData<@NonNull X> receiver,
    @NonNull Function1<@NonNull X, @NonNull Y> transform
)

Returns a LiveData mapped from this LiveData by applying transform to each value set on this LiveData.

This method is analogous to io.reactivex.Observable.map.

transform will be executed on the main thread.

Here is an example mapping a simple User struct in a LiveData to a LiveData containing their full name as a String.

val userLD : LiveData<User> = ...;
val userFullNameLD: LiveData<String> = userLD.map { user -> user.firstName + user.lastName }

TransformationsKt.switchMap

public final @NonNull LiveData<@NonNull Y> <X extends Object, Y extends Object> TransformationsKt.switchMap(
    @NonNull LiveData<@NonNull X> receiver,
    @NonNull Function1<@NonNull X, LiveData<@NonNull Y>> transform
)

Returns a LiveData mapped from the input thisLiveData by applying transform to each value set on this.

The returned `LiveData` delegates to the most recent `LiveData` created by [transform] with the most recent value set to `this`, without changing the reference. In this way [transform] can change the 'backing' `LiveData` transparently to any observer registered to the `LiveData` returned by `switchMap()`.

Note that when the backing LiveData is switched, no further values from the older LiveData will be set to the output LiveData. In this way, the method is analogous to io.reactivex.Observable.switchMap.

transform will be executed on the main thread.

Here is an example class that holds a typed-in name of a user String (such as from an EditText) in a MutableLiveData and returns a LiveData containing a List of User objects for users that have that name. It populates that LiveData by requerying a repository-pattern object each time the typed name changes.

This `ViewModel` would permit the observing UI to update "live" as the user ID text changes.

class UserViewModel: AndroidViewModel {
    val nameQueryLiveData : MutableLiveData<String> = ...

    fun usersWithNameLiveData(): LiveData<List<String>> = nameQueryLiveData.switchMap {
        name -> myDataSource.usersWithNameLiveData(name)
    }

    fun setNameQuery(val name: String) {
        this.nameQueryLiveData.value = name;
    }
}