Widgets with Glance: Displaying Images

From drawables, from bitmaps, from a url — from anywhere!

This the next in my series of blog posts all about widgets. Check out Widgets with Glance: Blending in and Widgets with Glance: Standing out for some Widget UI tricks and tips. And for advanced state handling see Widgets with Glance: Beyond String States.

If you are getting into widgets, pretty soon you are going to want to display images, whether that be a simple icon or a lovely graphic to brighten up your user’s home screen. Depending on where your image is stored (within your app as a drawable or from the internet) there are a few methods and some are more straightforward than others.

Let’s start simple with drawables…

Displaying drawables

Displaying a local icon or image is easy from an app drawable resource, all you need is to create an ImageProvider, pass in the drawable resource ID and then use it in a Image Glance composable:

In the above I have applied a ColorFilter to tint the image and a contentDescription for accessibility. Any sizing or padding can be set via the GlanceModifier as usual and contentScale will control how the image fits within the Image boundaries (more on this later).

Just a simple happy drawable displaying on a widget. The drawable is emoji by Maxim Kulikov from The Noun Project

Now, this is pretty simple, what if we want the widget to display a pretty photo? If it is stored as a drawable resource then this is exactly the same:

Looking pretty. Image from Lorem Picsum

Here I have expanded the image to fit the space and used ContentScale.Crop so it maintains the original aspect ratio and displays edge to edge in my widget.

Glance ContentScale options

Let’s go back to looking at ContentScale. As usual, with Jetpack Glance we have fewer options than we have with regular Jetpack Compose. The ContentScale options are:

• ContentScale.Crop — Scale uniformly (maintaining aspect ratio) so that both dimensions (width and height) will be equal to or larger than the corresponding dimension of the image composable.
• ContentScale.Fit — Scale uniformly (maintaining aspect ratio) so that both dimensions (width and height) will be equal to or less than the corresponding dimension of the image composable
• ContentScale.FillBounds — Scale horizontal and vertically non-uniformly to fill the image composable bounds.

Displaying an image from a url

Now, we get to what you are probably reading this article for. How to display an image from the internet in a widget. Unfortunately we can’t just directly use your favourite image loading library like Coil, Glide or Picasso as they don’t have Glance composables that we can put in Glance widget UI code (for various reasons). Instead, we need to load the image first into a bitmap, then use ImageProvider(bitmap) to load this in our Image Glance composable.

For this, we have two options depending on the use case:

1. Load the image as a bitmap using a background thread
2. Use a coroutine worker to download the image as a file

Image Bitmap with a background thread

This is the simplest option and is useful for widgets where the image is independent from the rest of the widget display (see below for when you wouldn’t want to use this option).

The first step is making use of Coil ImageRequest to download the image as a bitmap.

In the above I am explicitly disabling the image caching in the request, but you can alter this depending what your image is used for.

By placing this in a LaunchedEffect with a a context of Dispatches.IO we can run this code on the background thread and not lock up the UI thread.

Saving the result into a mutableState then enables the rest of the composable to respond once the image has been downloaded:

While the loadedBitmap state is null we can show a loading indicator and once it is ready, display the image using the Image Glance composable and a ImageProvider.

Now this works well:

The author information is fetched during the first “Loading”, the image is downloaded while the spinner is displayed.

Except in this case, it doesn’t make sense to show the image author before we actually show the image. Also, if an error occurs during loading we just have this circular progress indicator without any way of recovery.

We could fix this by adding more logic to the UI to set success & error states based on the image download but this is more brittle especially when we have data coming from different sources (in this case metadata from one endpoint and image from another — for the full example see my widget demo github repository).

So ideally we don’t want to use this method if showing the rest of the widget without the image makes no sense.

To load everything together and respond to the whole data state use a Coroutine Worker.

Image file with a Coroutine Worker

This method, while more complex, is useful if you are doing other background processing (such as fetching other data from a remote source) and want the image and the new data state to be available at the same time.

For this you can use string states using the standard PreferencesGlanceStateDefinition but I recommend using a CustomGlanceStateDefinition so that the different widget data states (e.g. success, loading & error) are more clearly defined. You can find more details on how to implement this and the Coroutine Worker itself in my previous blog post Widgets with Glance: Beyond String States.

To achieve this the first task is to download the image as a temporary file on the device that we can read later from the widget. We can do this using Coil and the image cache:

In this case we have enabled the Coil image cache — we want the image to be cached so we can fetch the file from the cache.

So here, the image file is downloaded into the cache using the url as the cache key so we can retrieve it later (the url is the key by default).

This method should be in your Coroutine Worker for the widget and called within the doWork method when you update the rest of the widget state.

Next, we need to access the Coil image cache. For this we need a FileProvider and specify which files we will be accessing:

Setting up this provider enables us to access the files in theimage_cache directory which is the default used by Coil.

Now, we can use this in the downloadImage method:

Permission handling for File Providers

If you are using a FileProvider you may encouter something like this error:

Permission Denial: opening provider com.your.package.ImageFileProvider from ProcessRecord{...} that is not exported from UID xxxxx

This will usually occur if you are displaying (or changing) an image in your widget a long time after your app was last open. What happens here is that the permission for the URI is lost when the MainActivity is lost (such as being naturally closed in the background). If you have recently installed or updated your app (such as debugging and deploying to your device) you are unlikely to see this as your activity is still open. (Thanks to this Stack Overflow post for the explanation).

To fix this we need to request the permission prior to accessing the image. This won’t show anything to the user as it is not a restricted or special permission. To do this, add the following to the downloadImage method:

Now, the image and data load at the same time!

The complete downloadImage method that returns the file url:

To see a full example, see my sample widget app:

GitHub - KatieBarnett/MotivateMe at blog/LoadingImagesInWidgets

For more widget blog posts, check out the others in my Widgets with glance series:
Widgets with Glance: Blending in, Widgets with Glance: Standing out and Widgets with Glance: Beyond String States