Guide

##Setting Up

###Which loader should I use?

For widgets, you should use the WidgetImageLoader. This can be constructed from the method ImageLoader.buildWidgetImageLoader(Object key, Context context). The "key" parameter in this method is an object that uniquely identifies that widget.

For all other use cases, please use the ImageLoader. The ImageLoader can be constructed from one of its static "build" methods. Example: ImageLoader.buildImageLoaderForActivity(activity);

###Where should I use the ImageLoader?

Each Activity and Fragment that needs to load images should instantiate it's own ImageLoader. Make sure that images being loaded into a Fragment uses that Fragment's ImageLoader instance, and vice versa for Activities.

For widgets, the WidgetImageLoader can be used to queue up image requests from the network or retrieve downloaded images from the cache.

###For Activities

Construct your ImageLoader or SupportImageLoader in your Activity's onCreate(...) method.

Call the loader's destroy() method in your Activity's onDestroy() method.

public class YourActivity extends Activity {
	private ImageLoader mImageLoader;

	@Override
	public void onCreate(Bundle savedInstanceState) {
	
		...
	
		mImageLoader = ImageLoader.buildImageLoaderForActivity(this);
	}

	@Override
	public void onDestroy() {
	
		...
	
		mImageLoader.destroy();
	}
}

###For Fragments

Construct your ImageLoader or SupportImageLoader in your Fragment's onCreateView(...) method.

Call the loader's destroy() method in your Fragment's onDestroyView() method.

public class YourFragment extends Fragment {
	private ImageLoader mImageLoader;
	
	@Override
	public View onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) {
		
		...
		
		mImageLoader = ImageLoader.buildImageLoaderForFragment(this);
	}
	
	@Override
	public void onDestroyView() {
		
		...
		
		mImageLoader.destroy();
	}
}

##Loading Images

###Basic Call

Here's how it works. Take a reference to your ImageView and URL, and pass it into the loadImage(ImageView, String) method.

mImageLoader.loadImage(imageView, url);

The image library will handle almost everything for you, including network calls, disk caching, RAM caching, complications with ListViews, scaling for memory savings and releasing references to your Activities and Fragments when they're destroyed.

This method will load the image using the default AbstractImageLoader.Options object. See the Image Options section below for further details.

An alternative method for making this request can be performed using the ImageRequest object.

ImageRequest request = new ImageRequest(url);
request.setImageView(imageView);
mImageLoader.loadImage(request);

Additional parameters are available within the ImageRequest object.

###Image Options -- ImageLoader.Options

There are some calls in the ImageLoader that allow you to pass in an "Options" object. This object offers some advanced options when loading images.

####Default Options

Default options can be set by calling setDefaultOptions(Options). The image loader will reset your options object if you pass "null" into this method -- setDefaultOptions(null).

The loadImage(ImageView, String) method will load images using the loader's default Options. For any other method that accepts the Options object as a parameter, such as loadImage(ImageView, String, Options), passing in null will cause that method to use the default options.

####Options Example

ImageLoader.Options options = new ImageLoader.Options();

// Set options here
	
mImageLoader.loadImage(imageView, url, options);

// OR:

mImageLoader.loadImage(imageView, url, options, new ImageLoaderListener() { ... });

// OR:

imageRequest.setOptions(options);

####Available Options

overrideSampleSize - Force the ImageLoader to decode the image using this sample size.

heightBounds - Manually enter the minimum acceptable height of the returned bitmap. If the bitmap's height is higher than the value specified, the bitmap may be shrunk down in order to conserve memory, but it will be guaranteed that the bitmap is still higher than the value specified.

widthBounds - Manually enter the minimum acceptable width of the returned bitmap. If the bitmap's width is wider than the value specified, the bitmap may be shrunk down in order to conserve memory, but it will be guaranteed that the bitmap is still wider than the value specified.

autoDetectBounds - The ImageLoader will automatically detect whether to lower the size of the image returned based on the dimensions of the ImageView.

useScreenSizeAsBounds - The ImageLoader may use the screen size as bounds when detecting whether to shrink the size of the image decoded into memory.

placeholderImageResourceId - The ImageLoader will enter the image represented by this placeholder ID into the ImageView before getting the bitmap.

unsuccessfulLoadResourceId - If the bitmap fails to load, the ImageLoader will set this image resource in the ImageView.

scalingPreference - This enum allows you to customize the logic the decoding system will use when calculating by how much it should be scaling your images. Setting more agressive scaling preferences can result in large memory savings.

wipeOldImageOnPreload - When loadImage is called, the previous image in the ImageView will automatically be removed, and if set, replaced by the placeholder image specified by the placeholderImageResourceId listed above. Set this value to false to prevent the old image from being wiped out until the requested image is set.

preferedConfig - This value sets the pixel format of the decoded images.

###Using the ImageLoaderListener

If you don't want the ImageLoader to actually put your bitmap into your ImageView (for example, if you wanted to animate the bitmap when it loads), you can pass an ImageLoaderListener into the loadImage call, causing the Bitmap to be passed back to you.

WARNING: The image will not automatically be loaded into the ImageView if you pass in an ImageLoaderListener. You will have to call imageView.setImageBitmap(bitmap) when the onImageAvailable method is called.

mImageLoader.loadImage(imageView, url, null, new ImageLoaderListener() {
	public void onImageAvailable(ImageView imageView, Bitmap bitmap, ImageReturnedFrom imageReturnedFrom) {
		// You can animate your ImageView here!
		// Or, just do things that you need to do once the image is available.
	}
	
	public void onImageLoadError() {
		// In here, you can handle what happens if the bitmap fails to load.
	}
});

The value "ImageReturnedFrom" will tell you whether the image came straight from the memory cache, was decoded asynchronously off the disk, or had to be downloaded from the network. This information may help you to decide whether or not you wish to animate the image into to view.

##Optimizing Performance

###Controlling the Memory Cache

When dealing with apps that have either many or large images, you may encounter some performance issues with the app. Image take up huge amounts of memory, but lucky for you these Image Utilities give you a lot of flexibility over how memory is used.

####Setting the size of the Mem Cache

The ImageLoader gives you the ability to specify the amount of memory you would like the image cacher to utilize.

imageLoader.setMaximumMemCacheSize(long maxSizeInBytes)

Depending on your target devices, or the different kinds of phones you would like to support, you can configure different memcache sizes in order to maximize performance and optimize memory consumption. I recommend setting varying mem cache sizes depending on the SDK level of the phone the app is running on. Some Froyo or Gingerbread phones have extremely little memory to play with, and for those devices it may be beneficial to set the Image Utilities to use as little as 6MB of RAM for the memory cache. For other devices, especially when working with SDK level 12+, it is usually safe to set the memory cache size as high as 30MB. The higher the mem cache size, the better the performance, but the more memory it consumes.

####Clearing the Mem Cache

If you know that your app is about to use a ton of memory, it sometimes helps to force the image system to null its references to all decoded bitmaps. This will allow the garbage collector to free up any space taken up by dereferenced images. NOTE: This does not mean that all images will be garbage collected. Images will only be collected if all references to them are set to null.

imageLoader.clearMemCache();

##Precaching

The ImageLoader gives you the ability to precache images for better performance. Using precaching functionality, your app will have the ability to preemptively cache your images to either disk or memory, which at times can vastly improve the end user experience.