Using the Universal Image Loader Library to handle your images

  • Written by  Clive

King of the Universe: The Universal Image Loader Library and you

Universal Image Loader Library list icon

So what is the Universal Image Loader Library?

The Universal Image Loader or UIL is a Library that you can include in your apps to take care of your images.

The Universal Image Loader Library:

  • Asynchronously downloads and loads your images for you
  • Caches the images in memory and on disk for you
  • Displays the images for you
  • Uses multithreading
  • You can configure it to suite your needs
  • You can set options for each image display
  • It's Free and Open Source

Our tutorial app

Our tutorial application displays a list of thumbnail images with some text.

Essentially this is the same app as the one in our tutorial Using Bitmaps efficiently where we used the Picasso Library to handle the images. Here we use the Universal Image Loader library to load the images from the drawable folder.

Selecting an item displays a larger version of the image together with some extra text in a fragment.

Universal Image Loader Library screenshot 1

We use the UIL Library to load and cache our images. Thumbnails are cached and displayed in a ListView. They’re reloaded from the cache when the Activity is rebuilt after changing the screen orientation

Universal Image Loader Library screenshot 2

Selecting an item displays a larger version of the image as well as some extra text. Changing orientation, instantaneously reloads the image from the cache

The Application class

We implement an Application object, MyListApplication by extending the Application class. This enables us to set up the default configuration for the Universal Image Loader as a Singleton. We can then access it from anywhere in our app.

Setting the default configuration

We set up the image loader’s default configuration in MyListApplication using this code:

Universal Image Loader Library configuration

We configure the image loader in our Application class Object, MyListApplication

Note the following:

  • These are only some of the options that we can set here. There are many more that enable you to fine-tune the image loader. See the UIL documentation for more. You can also modify the settings for displaying the images  when you use the loader in your activities
  • threadPriority – sets the priority for the worker threads that will handle the downloading and processing of the images. NORM_PRIORITY is the default priority set for the main thread (with a value of 5). We’re setting the worker thread’s priority to 3 ensuring that the main thread will always take priority and never be blocked. See Processes and Threads
  • denyCacheImageMultipleSizesInMemory – you can cache different sizes of the same image. If you set this option to true, then the latest cached image will overwrite the previous one
  • diskCacheFileNameGenerator – generates a random name for the disk cache file
  • tasksProcessingOrder – sets up the queue for processing tasks for loading and displaying images. The default is FIFO (first-in-first-out), we’re setting it to last-in-first-out (LIFO)
  • init – initialises the ImageLoader instance with our configuration. If you want to re-initialise the loader with a new configuration then you must first call destroy() to destroy this instance

The Main Activity

The main activity does all the work. It uses the image loader to get the images, resize and cache them and then display them in a list.

We can set the options for displaying the images here. Here’s the code:

Setting the options

Universal Image Loader Library display options

You can set the options for how you want your images displayed. Check the documentation for more options

Note the following:

  • showImageOnLoading – a placeholder image to display while the images are downloading
  • showImageForEmptyUri – the image to show if the uri is empty or null
  • showImageOnFail – the image to show if there is an error in decoding/loading the image
  • cacheInMemory - whether to load the image in the memory cache
  • cacheOnDisk - whether to cache the image on disk

The view holder

We create a ViewHolder class which contains two fields:

  • a text view which will display some text for each list item
  • an image view that will display the thumbnail image for each list item

Universal Image Loader Library viewHolder

Our ViewHolder class contains a TextView and an ImageView which we use to display the text and image for each list item

Populating the ArrayList of people

We have a Person class which has four fields:

  • Name
  • Image resource ID
  • A phrase
  • Phone number

We use the populatePersonList() method to load a number of items into an Array List, people.

The custom adapter

We create a custom ArrayAdapter of type Person which we use to populate and display the list of items.

Getting the view for each list item

The getView() method gets and returns the view with the data for the item identified by the position parameter. Here’s the first part of code:

Universal Image Loader Library getView

We first check if there is an existing view that we can use. If there isn’t one then we create a view for the item

Note the following:

  • itemView – this is the view that will display each list item (both text and image)
  • convertView – we check if there is an existing view that we can use, if not then we create a new view
  • inflate – we create a new view by inflating the layout resource file
  • currentPersonViewHolder – we create a new ViewHolder object and reference the text and image fields to the text and image views in the layout file
  • setTag – we mark this view so that we can use it later
  • else – a previous view exists, so we can use it. We’re able to identify it by the tag

Here’s the second part of the getView() code:

Universal Image Loader Library getView

This is where we display the image and text

Note the following:

  • setText – we set the ViewHolder’s text view to display the name of the person identified by position
  • setMaxWidth and setMaxHeight – we set these sizes for the thumbnails. The loader uses these values to decode the images to the required sizes so as to save on memory
  • displayImage – we display the thumbnail image for the item identified by position. We include three parameters:
    • the image uri – we’re using a drawable but you can also load images from the internet, SD card, content provider, and the assets folder
    • the image view that will display the image
    • our display options

Selecting items from the list

We use the selectedItemCallback() method to handle the item selections.

Essentially we use the selected item’s position to get its values. We then put these values into an intent and use the intent to start a new activity.

The new activity displays the selected item’s image and text details in a fragment.

The DetailsFragment activity

The details fragment activity is started when an item in the list is selected. Details of that item are included in the intent that starts the DetailsFragment activity.

In the DetailsFragment activity, we get the details out of the intent and pass them on as construction arguments for the fragment that we create.

We display the selected item’s details in the fragment.

The DetailsFragment fragment

The details fragment displays a larger version of the selected item’s image as well as some text information.

We get all the details for the selected item from the construction arguments that were passed on when we created the fragment.

Here’s part of the code:

Universal Image Loader Library fragment

We display the text details and image in the fragment

Note the following:

  • imageView – we get the image view from the layout
  • setMaxHeight and setMaxWidth – we set the dimensions for the required image. This is used by the loader to calculate the image resizing. You can also set this in the layout file
  • imageLoader – we get an instance of the ImageLoader
  • displayImage – we display the image in the image view
  • txtPhrase – we get the text view for the phrase and set it to display the appropriate text
  • txtPhone – we get the text view for the phone and set it to display the appropriate text

Including the Universal Image Loader Library in your app

In Android Studio

  1. Download the jar file
  2. Place it in the libs folder (in your apps folder)

Universal Image Loader Library jar

Place the jar file in the libs folder

  1. Sync project with Gradle files

Universal Image Loader Library jar sync Gradle

Sync the project with Gradle files

You can download the jar and read more about the Universal Image Loader here. There is also a great sample project that you can explore to find out more about how to use the Universal Image Loader Library.

I hope that you have found this tutorial helpful.

If you need more info on ArrayAdapters and lists, have a look at our Android ListView tutorial and the article on Adapters, Android Adapters: what are Adapters?

You can download the project files here Download icon

Are you using Eclipse or another IDE? Here's how you can use this project's Android Studio files.