abstract class MuzeiArtProvider : ContentProvider, ProviderClient
Base class for a Muzei Live Wallpaper artwork provider. Art providers are a way for other apps to feed wallpapers (called artworks) to Muzei Live Wallpaper.
Subclasses must implement at least the onLoadRequested callback method, which is called whenever Muzei has displayed all available artwork from your provider. It is strongly recommended to load new artwork at this point and add it via addArtwork so that users can continue to move to the next artwork.
All artwork added via addArtwork is available to Muzei. Muzei controls how often the artwork changes and the order that it proceeds through the artwork. As a convenience, you can use setArtwork to remove all artwork and set just a single new Artwork. You can use ContentResolver.delete with contentUri to delete specific artwork based on criteria of your choosing.
Many operations are also available in ProviderContract.Artwork, allowing you to add, update, delete, and query for artwork from anywhere in your app.
Each provider must be added to your application's AndroidManifest.xml
file via a
<provider>
element.
The Muzei app discover available providers using Android's Intent mechanism. Ensure
that your provider
definition includes an <intent-filter>
with
an action of ACTION_MUZEI_ART_PROVIDER. It is strongly recommended to protect access
to your provider's data by adding the ACCESS_PERMISSION, which will
ensure that only your app and Muzei can access your data.
Lastly, there are a few <meta-data>
elements that you should add to your
provider definition:
settingsActivity
(optional): if present, should be the qualified
component name for a configuration activity in the provider's package that Muzei can offer
to the user for customizing the extension. This activity must be exported.setupActivity
(optional): if present, should be the qualified
component name for an initial setup activity that must be ran before the provider can be
activated. It will be started with android.app.Activity.startActivityForResult and must
return android.app.Activity.RESULT_OK for the provider to be activated. This activity
must be exported.Below is an example provider declaration in the manifest:
<provider android:name=".ExampleArtProvider"
android:authorities="com.example.artprovider"
android:label="@string/source_title"
android:description="@string/source_description"
android:permission="com.google.android.apps.muzei.api.ACCESS_PROVIDER">
<intent-filter>
<action android:name="com.google.android.apps.muzei.api.MuzeiArtProvider" />
</intent-filter>
<!-- A settings activity is optional -->
<meta-data android:name="settingsActivity"
android:value=".ExampleSettingsActivity" />
</provider>
If a settingsActivity
meta-data element is present, an activity with the given
component name should be defined and exported in the application's manifest as well. Muzei
will set the EXTRA_FROM_MUZEI extra to true in the launch intent for this
activity. An example is shown below:
<activity android:name=".ExampleSettingsActivity"
android:label="@string/title_settings"
android:exported="true" />
Finally, below is a simple example MuzeiArtProvider subclass that publishes a single, static artwork:
class ExampleArtProvider : MuzeiArtProvider() {
override fun onLoadRequested(initial: Boolean) {
if (initial) {
setArtwork(Artwork(
title = "Example image",
byline = "Unknown person, c. 1980",
persistentUri = Uri.parse("http://example.com/image.jpg"),
webUri = Uri.parse("http://example.com/imagedetails.html")))
}
}
}
As onLoadRequested can be called at any time (including when offline), it is
strongly recommended to use the callback of onLoadRequested to kick off
a load operation using WorkManager
, JobScheduler
, or a comparable API. These
other components can then use a ProviderClient and
ProviderClient.addArtwork to add Artwork to the MuzeiArtProvider.
Providers can also expose additional user-facing commands (such as 'Share artwork') by returning one or more RemoteActionCompat instances from getCommandActions.
Providers can provide a dynamic description of the current configuration (e.g.
'Popular photos tagged "landscape"'), by overriding getDescription. By default,
the android:description
element of the provider element in the manifest will be
used.
All artwork should support opening an Activity to view more details about the artwork. You can provider your own functionality by overriding getArtworkInfo.
If custom behavior is needed to retrieve the artwork's binary data (for example, authentication with a remote server), this behavior can be added to openFile. If you already have binary data available locally for your artwork, you can also write it directly via ContentResolver.openOutputStream.
It is strongly recommended to add a MuzeiArtDocumentsProvider to your manifest to make artwork from your MuzeiArtProvider available via the default file picker and Files app.
MuzeiArtProvider respects Log.isLoggable for debug logging, allowing you to
use adb shell setprop log.tag.MuzeiArtProvider VERBOSE
to enable logging of the
communications between Muzei and your MuzeiArtProvider.
<init> |
Base class for a Muzei Live Wallpaper artwork provider. Art providers are a way for other apps to feed wallpapers (called artworks) to Muzei Live Wallpaper. MuzeiArtProvider() |
contentUri |
Retrieve the content URI for the MuzeiArtProvider, allowing you to build custom queries, inserts, updates, and deletes using a ContentResolver. val contentUri: Uri |
lastAddedArtwork |
Retrieve the last added artwork from the MuzeiArtProvider. val lastAddedArtwork: Artwork? |
addArtwork |
Add a new piece of artwork to the MuzeiArtProvider. fun addArtwork(artwork: Artwork): Uri?
Add multiple artwork as a batch operation to the MuzeiArtProvider. fun addArtwork(artwork: Iterable<Artwork>): List<Uri> |
getArtworkInfo |
Callback when the user wishes to see more information about the given artwork. The default implementation constructs a PendingIntent to the web uri of the artwork. open fun getArtworkInfo(artwork: Artwork): PendingIntent? |
getCommandActions |
Retrieve the list of commands available for the given artwork. Each action should have an icon 24x24dp. Muzei respects the RemoteActionCompat.setShouldShowIcon to determine when to show the action as an icon (assuming there is enough space). Actions with a blank title will be ignored by Muzei. open fun getCommandActions(artwork: Artwork): List<RemoteActionCompat> |
getCommands |
Retrieve the list of commands available for the given artwork. open fun |
getDescription |
The longer description for the current state of this MuzeiArtProvider. For example,
'Popular photos tagged "landscape"'). The default implementation returns the
open fun getDescription(): String |
isArtworkValid |
Called every time an image is loaded (even if there is a cached
image available). This gives you an opportunity to circumvent the
typical loading process and remove previously cached artwork on
demand. The default implementation always returns open fun isArtworkValid(artwork: Artwork): Boolean |
onCommand |
Callback method indicating that the user has selected a command returned by getCommands. open fun |
onInvalidArtwork |
Called when Muzei failed to load the given artwork, usually due to an incompatibility in supported image format. The default behavior is to delete the artwork. open fun onInvalidArtwork(artwork: Artwork): Unit |
onLoadRequested |
Callback method when the user has viewed all of the available artwork. This should be used as a cue to load more artwork so that the user has a constant stream of new artwork. abstract fun onLoadRequested(initial: Boolean): Unit |
openArtworkInfo |
Callback when the user wishes to see more information about the given artwork. The default implementation opens the web uri of the artwork. open fun |
openFile |
Provide an InputStream to the binary data associated with artwork that has not yet been cached. The default implementation retrieves the image from the persistent URI and supports URI schemes in the following formats: open fun openFile(artwork: Artwork): InputStream |
setArtwork |
Set the MuzeiArtProvider to only show the given artwork, deleting any other artwork previously added. Only in the cases where the artwork is successfully inserted will the other artwork be removed. fun setArtwork(artwork: Artwork): Uri? fun setArtwork(artwork: Iterable<Artwork>): List<Uri> |
ACCESS_PERMISSION |
Permission that can be used with your MuzeiArtProvider to ensure that only your app and Muzei can read and write its data. const val ACCESS_PERMISSION: String |
ACTION_MUZEI_ART_PROVIDER |
The Intent action representing a Muzei art provider. This provider should
declare an const val ACTION_MUZEI_ART_PROVIDER: String |
EXTRA_FROM_MUZEI |
Boolean extra that will be set to true when Muzei starts provider settings and setup activities. const val EXTRA_FROM_MUZEI: String |
createChooseProviderIntent |
Deep link into Muzei's Sources screen, automatically scrolling to the com.google.android.apps.muzei.api.provider.MuzeiArtProvider associated with this ProviderClient. If Muzei is not yet activated, users will be asked to activate Muzei before continuing onto the Sources screen. fun ProviderClient.createChooseProviderIntent(): Intent |
isSelected |
Checks the MuzeiContract.Sources table provided by Muzei to determine whether the com.google.android.apps.muzei.api.provider.MuzeiArtProvider associated with this ProviderClient has been selected by the user. fun ProviderClient.isSelected(context: Context): Boolean |