Loader

open class Loader<D : Any!>
kotlin.Any
   ↳ androidx.loader.content.Loader

Static library support version of the framework's android.content.Loader. Used to write apps that run on platforms prior to Android 3.0. When running on Android 3.0 or above, this implementation is still used; it does not try to switch to the framework's implementation. See the framework SDK documentation for a class overview.

Summary

Nested classes

An implementation of a ContentObserver that takes care of connecting it to the Loader to have the loader re-load its data when the observer is told it has changed.

abstract

Interface that is implemented to discover when a Loader has been canceled before it finished loading its data.

abstract

Interface that is implemented to discover when a Loader has finished loading its data.

Public constructors
<init>(context: Context)

Stores away the application context associated with context.

Public methods
open Unit

Informs the registered OnLoadCanceledListener that the load has been canceled.

open Boolean

Attempt to cancel the current load task.

open Unit

Commit that you have actually fully processed a content change that was returned by #takeContentChanged.

open Int

open Unit
deliverResult(data: D?)

Sends the result of the load to the registered listener.

open Boolean

Return whether this loader has been abandoned.

open Unit

This function will normally be called for you automatically by LoaderManager when restarting a Loader.

open Unit

Report that you have abandoned the processing of a content change that was returned by #takeContentChanged() and would like to rollback to the state where there is again a pending content change.

open String
dataToString(data: D?)

For debugging, converts an instance of the Loader's data class to a string that can be printed.

open Unit

Force an asynchronous load.

Unit

This function will normally be called for you automatically by LoaderManager when the associated fragment/activity is being started.

open Unit

Unregisters a listener that was previously added with #registerOnLoadCanceledListener.

open Unit

This function will normally be called for you automatically by LoaderManager when destroying a Loader.

open Boolean

Return whether this load has been started.

open Unit

Registers a class that will receive callbacks when a load is complete.

open Boolean

Return whether this load has been reset.

open Unit

Remove a listener that was previously added with #registerListener.

open String

open Context

open Boolean

Take the current flag indicating whether the loader's content had changed while it was stopped.

open Unit
dump(prefix: String!, fd: FileDescriptor!, writer: PrintWriter!, args: Array<String!>!)

Print the Loader's state into the given stream.

open Unit

Called when ForceLoadContentObserver detects a change.

open Unit

This function will normally be called for you automatically by LoaderManager when the associated fragment/activity is being stopped.

open Unit

Registers a listener that will receive callbacks when a load is canceled.

Protected methods
open Unit

Subclasses must implement this to take care of loading their data, as per #startLoading().

open Unit

Subclasses must implement this to take care of resetting their loader, as per #reset().

open Boolean

Subclasses must implement this to take care of requests to #cancelLoad().

open Unit

Subclasses implement this to take care of being abandoned.

open Unit

Subclasses must implement this to take care of requests to #forceLoad().

open Unit

Subclasses must implement this to take care of stopping their loader, as per #stopLoading().

Public constructors

<init>

Loader(context: Context)

Stores away the application context associated with context. Since Loaders can be used across multiple activities it's dangerous to store the context directly; always use #getContext() to retrieve the Loader's Context, don't use the constructor argument directly. The Context returned by #getContext is safe to use across Activity instances.

Parameters
context Context: used to retrieve the application context.

Public methods

deliverCancellation

open fun deliverCancellation(): Unit

Informs the registered OnLoadCanceledListener that the load has been canceled. Should only be called by subclasses. Must be called from the process's main thread.

cancelLoad

open fun cancelLoad(): Boolean

Attempt to cancel the current load task. Must be called on the main thread of the process.

Cancellation is not an immediate operation, since the load is performed in a background thread. If there is currently a load in progress, this method requests that the load be canceled, and notes this is the case; once the background thread has completed its work its remaining state will be cleared. If another load request comes in during this time, it will be held until the canceled load is complete.

Return
Boolean: Returns false if the task could not be canceled, typically because it has already completed normally, or because #startLoading() hasn't been called; returns true otherwise. When true is returned, the task is still running and the OnLoadCanceledListener will be called when the task completes.

commitContentChanged

open fun commitContentChanged(): Unit

Commit that you have actually fully processed a content change that was returned by #takeContentChanged. This is for use with #rollbackContentChanged() to handle situations where a load is cancelled. Call this when you have completely processed a load without it being cancelled.

getId

open fun getId(): Int
Return
Int: the ID of this loader

deliverResult

open fun deliverResult(data: D?): Unit

Sends the result of the load to the registered listener. Should only be called by subclasses. Must be called from the process's main thread.

Parameters
data D?: the result of the load

isAbandoned

open fun isAbandoned(): Boolean

Return whether this loader has been abandoned. In this state, the loader must not report any new data, and must keep its last reported data valid until it is finally reset.

abandon

open fun abandon(): Unit

This function will normally be called for you automatically by LoaderManager when restarting a Loader. When using a Loader with LoaderManager, you must not call this method yourself, or you will conflict with its management of the Loader. Tell the Loader that it is being abandoned. This is called prior to #reset to have it retain its current data but not report any new data.

Must be called from the process's main thread.

rollbackContentChanged

open fun rollbackContentChanged(): Unit

Report that you have abandoned the processing of a content change that was returned by #takeContentChanged() and would like to rollback to the state where there is again a pending content change. This is to handle the case where a data load due to a content change has been canceled before its data was delivered back to the loader.

dataToString

open fun dataToString(data: D?): String

For debugging, converts an instance of the Loader's data class to a string that can be printed. Must handle a null data.

forceLoad

open fun forceLoad(): Unit

Force an asynchronous load. Unlike #startLoading() this will ignore a previously loaded data set and load a new one. This simply calls through to the implementation's #onForceLoad(). You generally should only call this when the loader is started -- that is, #isStarted() returns true.

Must be called from the process's main thread.

startLoading

fun startLoading(): Unit

This function will normally be called for you automatically by LoaderManager when the associated fragment/activity is being started. When using a Loader with LoaderManager, you must not call this method yourself, or you will conflict with its management of the Loader. Starts an asynchronous load of the Loader's data. When the result is ready the callbacks will be called on the process's main thread. If a previous load has been completed and is still valid the result may be passed to the callbacks immediately. The loader will monitor the source of the data set and may deliver future callbacks if the source changes. Calling #stopLoading will stop the delivery of callbacks.

This updates the Loader's internal state so that #isStarted() and #isReset() will return the correct values, and then calls the implementation's #onStartLoading().

Must be called from the process's main thread.

unregisterOnLoadCanceledListener

open fun unregisterOnLoadCanceledListener(listener: Loader.OnLoadCanceledListener<D>): Unit

Unregisters a listener that was previously added with #registerOnLoadCanceledListener. Must be called from the process's main thread.

Parameters
listener Loader.OnLoadCanceledListener<D>: The listener to unregister.

reset

open fun reset(): Unit

This function will normally be called for you automatically by LoaderManager when destroying a Loader. When using a Loader with LoaderManager, you must not call this method yourself, or you will conflict with its management of the Loader. Resets the state of the Loader. The Loader should at this point free all of its resources, since it may never be called again; however, its #startLoading() may later be called at which point it must be able to start running again.

This updates the Loader's internal state so that #isStarted() and #isReset() will return the correct values, and then calls the implementation's #onReset().

Must be called from the process's main thread.

isStarted

open fun isStarted(): Boolean

Return whether this load has been started. That is, its #startLoading() has been called and no calls to #stopLoading() or #reset() have yet been made.

registerListener

open fun registerListener(id: Int, listener: Loader.OnLoadCompleteListener<D>): Unit

Registers a class that will receive callbacks when a load is complete. The callback will be called on the process's main thread so it's safe to pass the results to widgets.

Must be called from the process's main thread.

isReset

open fun isReset(): Boolean

Return whether this load has been reset. That is, either the loader has not yet been started for the first time, or its #reset() has been called.

unregisterListener

open fun unregisterListener(listener: Loader.OnLoadCompleteListener<D>): Unit

Remove a listener that was previously added with #registerListener. Must be called from the process's main thread.

toString

open fun toString(): String

getContext

open fun getContext(): Context
Return
Context: an application context retrieved from the Context passed to the constructor.

takeContentChanged

open fun takeContentChanged(): Boolean

Take the current flag indicating whether the loader's content had changed while it was stopped. If it had, true is returned and the flag is cleared.

dump

open fun dump(prefix: String!, fd: FileDescriptor!, writer: PrintWriter!, args: Array<String!>!): Unit

Print the Loader's state into the given stream.

Parameters
prefix String!: Text to print at the front of each line.
fd String!: The raw file descriptor that the dump is being sent to.
writer String!: A PrintWriter to which the dump is to be set.
args String!: Additional arguments to the dump request.

onContentChanged

open fun onContentChanged(): Unit

Called when ForceLoadContentObserver detects a change. The default implementation checks to see if the loader is currently started; if so, it simply calls #forceLoad(); otherwise, it sets a flag so that #takeContentChanged() returns true.

Must be called from the process's main thread.

stopLoading

open fun stopLoading(): Unit

This function will normally be called for you automatically by LoaderManager when the associated fragment/activity is being stopped. When using a Loader with LoaderManager, you must not call this method yourself, or you will conflict with its management of the Loader.

Stops delivery of updates until the next time #startLoading() is called. Implementations should not invalidate their data at this point -- clients are still free to use the last data the loader reported. They will, however, typically stop reporting new data if the data changes; they can still monitor for changes, but must not report them to the client until and if #startLoading() is later called.

This updates the Loader's internal state so that #isStarted() will return the correct value, and then calls the implementation's #onStopLoading().

Must be called from the process's main thread.

registerOnLoadCanceledListener

open fun registerOnLoadCanceledListener(listener: Loader.OnLoadCanceledListener<D>): Unit

Registers a listener that will receive callbacks when a load is canceled. The callback will be called on the process's main thread so it's safe to pass the results to widgets. Must be called from the process's main thread.

Parameters
listener Loader.OnLoadCanceledListener<D>: The listener to register.

Protected methods

onStartLoading

protected open fun onStartLoading(): Unit

Subclasses must implement this to take care of loading their data, as per #startLoading(). This is not called by clients directly, but as a result of a call to #startLoading(). This will always be called from the process's main thread.

onReset

protected open fun onReset(): Unit

Subclasses must implement this to take care of resetting their loader, as per #reset(). This is not called by clients directly, but as a result of a call to #reset(). This will always be called from the process's main thread.

onCancelLoad

protected open fun onCancelLoad(): Boolean

Subclasses must implement this to take care of requests to #cancelLoad(). This will always be called from the process's main thread.

Return
Boolean: Returns false if the task could not be canceled, typically because it has already completed normally, or because #startLoading() hasn't been called; returns true otherwise. When true is returned, the task is still running and the OnLoadCanceledListener will be called when the task completes.

onAbandon

protected open fun onAbandon(): Unit

Subclasses implement this to take care of being abandoned. This is an optional intermediate state prior to #onReset() -- it means that the client is no longer interested in any new data from the loader, so the loader must not report any further updates. However, the loader must keep its last reported data valid until the final #onReset() happens. You can retrieve the current abandoned state with #isAbandoned. This will always be called from the process's main thread.

onForceLoad

protected open fun onForceLoad(): Unit

Subclasses must implement this to take care of requests to #forceLoad(). This will always be called from the process's main thread.

onStopLoading

protected open fun onStopLoading(): Unit

Subclasses must implement this to take care of stopping their loader, as per #stopLoading(). This is not called by clients directly, but as a result of a call to #stopLoading(). This will always be called from the process's main thread.