<commit_before>﻿# Universal Image Loader for Android

This project aims to provide a reusable instrument for asynchronous image loading, caching and displaying. It is originally based on [<NAME>'s project](https://github.com/thest1/LazyList) and has been vastly refactored and improved since then.

**Download:** [JAR library](https://github.com/nostra13/Android-Universal-Image-Loader/downloads); [sources](https://github.com/nostra13/Android-Universal-Image-Loader/downloads) (you can attach it to project as _source attachment_ so you can see Java docs)

![Screenshot](https://github.com/nostra13/Android-Universal-Image-Loader/raw/master/UniversalImageLoader.png)

## Features
 * Multithread image loading
 * Possibility of wide tuning ImageLoader's configuration (thread pool size, HTTP options, memory and disc cache, display image options, and others)
 * Possibility of image caching in memory and/or on device's file sysytem (or SD card)
 * Possibility to "listen" loading process
 * Possibility to customize every display image call with separated options
 * Widget support

## Documentation
 * Universal Image Loader. Part 1 - Introduction [[RU](http://nostra13android.blogspot.com/2012/03/4-universal-image-loader-part-1.html) | [EN](http://www.intexsoft.com/blog/item/68-universal-image-loader-part-1.html)]
 * Universal Image Loader. Part 2 - Configuration [[RU](http://nostra13android.blogspot.com/2012/03/5-universal-image-loader-part-2.html) | [EN](http://www.intexsoft.com/blog/item/72-universal-image-loader-part-2.html)]
 * Universal Image Loader. Part 3 - Usage [[RU](http://nostra13android.blogspot.com/2012/03/6-universal-image-loader-part-3-usage.html) | [EN](http://www.intexsoft.com/blog/item/74-universal-image-loader-part-3.html)]

### [Changelog](https://github.com/nostra13/Android-Universal-Image-Loader/commits/master)
 
## Usage

### Simple

``` java
ImageView imageView = ...
String imageUrl = "http://site.com/image.png"; // or "file:///mnt/sdcard/images/image.jpg"

// Get singletone instance of ImageLoader
ImageLoader imageLoader = ImageLoader.getInstance();
// Initialize ImageLoader with configuration. Do it once.
imageLoader.init(ImageLoaderConfiguration.createDefault(context));
// Load and display image asynchronously
imageLoader.displayImage(imageUrl, imageView);
```

### Most detailed
``` java
ImageView imageView = ...
String imageUrl = "http://site.com/image.png"; // or "file:///mnt/sdcard/images/image.jpg"
ProgressBar spinner = ...
File cacheDir = StorageUtils.getOwnCacheDirectory(getApplicationContext(), "UniversalImageLoader/Cache");

// Get singletone instance of ImageLoader
ImageLoader imageLoader = ImageLoader.getInstance();
// Create configuration for ImageLoader (all options are optional, use only those you really want to customize)
ImageLoaderConfiguration config = new ImageLoaderConfiguration.Builder(getApplicationContext())
			.memoryCacheExtraOptions(480, 800) // max width, max height
			.discCacheExtraOptions(480, 800, CompressFormat.JPEG, 75) // Can slow ImageLoader, use it carefully (Better don't use it)
			.threadPoolSize(3)
			.threadPriority(Thread.NORM_PRIORITY - 1)
			.denyCacheImageMultipleSizesInMemory()
			.offOutOfMemoryHandling()
			.memoryCache(new UsingFreqLimitedMemoryCache(2 * 1024 * 1024)) // You can pass your own memory cache implementation
			.discCache(new UnlimitedDiscCache(cacheDir)) // You can pass your own disc cache implementation
			.discCacheFileNameGenerator(new HashCodeFileNameGenerator())
			.imageDownloader(new URLConnectionImageDownloader(5 * 1000, 20 * 1000)) // connectTimeout (5 s), readTimeout (20 s)
			.defaultDisplayImageOptions(DisplayImageOptions.createSimple())
			.enableLogging()
			.build();
// Initialize ImageLoader with created configuration. Do it once.
imageLoader.init(config);

// Creates display image options for custom display task (all options are optional)
DisplayImageOptions options = new DisplayImageOptions.Builder()
                                       .showStubImage(R.drawable.stub_image)
									   .showImageForEmptyUri(R.drawable.image_for_empty_url)
                                       .cacheInMemory()
                                       .cacheOnDisc()
									   .imageScaleType(ImageScaleType.POWER_OF_2)
                                       .build();
// Load and display image
imageLoader.displayImage(imageUrl, imageView, options, new ImageLoadingListener() {
    @Override
    public void onLoadingStarted() {
       spinner.show();
    }
	@Override
	public void onLoadingFailed(FailReason failReason) {
		spinner.hide();
	}
    @Override
    public void onLoadingComplete(Bitmap loadedImage) {
        spinner.hide();
    }
	@Override
    public void onLoadingCancelled() {
        // Do nothing
    }
});
```

## Useful info
1. How UIL define Bitmap size needed for exact ImageView? Search defined parameters top-down:
 * Get ```android:layout_width``` or ```android:layout_height``` parameters
 * Get ```android:maxWidth``` and ```android:maxHeight``` parameters
 * Get maximum size parameters from configuration (```memoryCacheExtraOptions(int, int)``` option)

 Set ```android:layout_width```|```android:layout_height``` or ```android:maxWidth```|```android:maxHeight``` parameters for ImageView if you know approximate maximum size of it. It will help correctly compute Bitmap size needed for this view and **save memory**.

2. If you often got **OutOfMemoryError** in your app using Universal Image Loader then try set WeakMemoryCache into configuration:
``` java
ImageLoaderConfiguration config = new ImageLoaderConfiguration.Builder(getApplicationContext())
			...
			.memoryCache(new WeakMemoryCache())
			...
			.build();
```

3. For memory cache configuration (ImageLoaderConfiguration.Builder.memoryCache(...)) you can use already prepared implementations:
 * UsingFreqLimitedMemoryCache (The least frequently used bitmap is deleted when cache size limit is exceeded) - Used by default
 * LRULimitedMemoryCache (Least recently used bitmap is deleted when cache size limit is exceeded)
 * FIFOLimitedMemoryCache (FIFO rule is used for deletion when cache size limit is exceeded)
 * LargestLimitedMemoryCache (The largest bitmap is deleted when cache size limit is exceeded)
 * LimitedAgeMemoryCache (Decorator. Cached object is deleted when its age exceeds defined value)
 * WeakMemoryCache (Memory cache with only weak references to bitmaps)

4. For disc cache configuration (ImageLoaderConfiguration.Builder.discCache(...)) you can use already prepared implementations:
 * UnlimitedDiscCache (The fastest cache, doesn't limit cache size) - Used by default
 * TotalSizeLimitedDiscCache (Cache limited by total cache size. If cache size exceeds specified limit then file with the most oldest last usage date will be deleted)
 * FileCountLimitedDiscCache (Cache limited by file count. If file count in cache directory exceeds specified limit then file with the most oldest last usage date will be deleted. Use it if your cached files are of about the same size.)
 * LimitedAgeDiscCache (Size-unlimited cache with limited files' lifetime. If age of cached file exceeds defined limit then it will be deleted from cache.)
 
 **NOTE:** UnlimitedDiscCache is 30%-faster than other limited disc cache implementations.

## Applications using Universal Image Loader
* [MediaHouse, UPnP/DLNA Browser](https://play.google.com/store/apps/details?id=com.dbapp.android.mediahouse)
* [Деловой Киров](https://play.google.com/store/apps/details?id=ru.normakirov.dknorma)
* [Бизнес-завтрак](https://play.google.com/store/apps/details?id=ru.normakirov.businesslunch)
* [Menu55](http://www.free-lance.ru/users/max475imus/viewproj.php?prjid=3152141)
* [SpokenPic](http://spokenpic.com)
* [Kumir](https://play.google.com/store/apps/details?id=ru.premiakumir.android)
* [EUKO 2012](https://play.google.com/store/apps/details?id=de.netlands.emsapp)
* [TuuSo Image Search](https://play.google.com/store/apps/details?id=com.tuuso)
* [Газета Стройка](https://play.google.com/store/apps/details?id=ru.normakirov.stroyka)
* [Prezzi Benzina (AndroidFuel)](https://play.google.com/store/apps/details?id=org.vernazza.androidfuel)
* [Quiz Guess The Guy] (https://play.google.com/store/apps/details?id=com.game.guesstheguy)
* [Volksempfänger (alpha)](http://volksempfaenger.0x4a42.net)
* [ROM Toolbox Lite](https://play.google.com/store/apps/details?id=com.jrummy.liberty.toolbox) | [Pro](https://play.google.com/store/apps/details?id=com.jrummy.liberty.toolboxpro)
* [London 2012 Games](https://play.google.com/store/apps/details?id=com.mbwasi.london)
* [카톡 이미지 - 예쁜 프로필 이미지](https://play.google.com/store/apps/details?id=com.bydoori.firstbasea)
* [dailyPen](https://play.google.com/store/apps/details?id=com.bydoori.dailypen)

## License
Copyright (c) 2011-2012, [<NAME>](http://nostra13android.blogspot.com)

If you use Universal Image Loader code in your application you have to inform the author about it (*email: nostra13[at]gmail[dot]com*). Also you should (but you don't have to) mention it in application UI with string **"Used Universal-Image-Loader (c) 2011-2012, <NAME>"** (e.g. in some "About" section).

Licensed under the [BSD 3-clause](http://www.opensource.org/licenses/BSD-3-Clause)<commit_msg>Added applications<commit_after>﻿# Universal Image Loader for Android

This project aims to provide a reusable instrument for asynchronous image loading, caching and displaying. It is originally based on [<NAME>'s project](https://github.com/thest1/LazyList) and has been vastly refactored and improved since then.

**Download:** [JAR library](https://github.com/nostra13/Android-Universal-Image-Loader/downloads); [sources](https://github.com/nostra13/Android-Universal-Image-Loader/downloads) (you can attach it to project as _source attachment_ so you can see Java docs)

![Screenshot](https://github.com/nostra13/Android-Universal-Image-Loader/raw/master/UniversalImageLoader.png)

## Features
 * Multithread image loading
 * Possibility of wide tuning ImageLoader's configuration (thread pool size, HTTP options, memory and disc cache, display image options, and others)
 * Possibility of image caching in memory and/or on device's file sysytem (or SD card)
 * Possibility to "listen" loading process
 * Possibility to customize every display image call with separated options
 * Widget support

## Documentation
 * Universal Image Loader. Part 1 - Introduction [[RU](http://nostra13android.blogspot.com/2012/03/4-universal-image-loader-part-1.html) | [EN](http://www.intexsoft.com/blog/item/68-universal-image-loader-part-1.html)]
 * Universal Image Loader. Part 2 - Configuration [[RU](http://nostra13android.blogspot.com/2012/03/5-universal-image-loader-part-2.html) | [EN](http://www.intexsoft.com/blog/item/72-universal-image-loader-part-2.html)]
 * Universal Image Loader. Part 3 - Usage [[RU](http://nostra13android.blogspot.com/2012/03/6-universal-image-loader-part-3-usage.html) | [EN](http://www.intexsoft.com/blog/item/74-universal-image-loader-part-3.html)]

### [Changelog](https://github.com/nostra13/Android-Universal-Image-Loader/commits/master)
 
## Usage

### Simple

``` java
ImageView imageView = ...
String imageUrl = "http://site.com/image.png"; // or "file:///mnt/sdcard/images/image.jpg"

// Get singletone instance of ImageLoader
ImageLoader imageLoader = ImageLoader.getInstance();
// Initialize ImageLoader with configuration. Do it once.
imageLoader.init(ImageLoaderConfiguration.createDefault(context));
// Load and display image asynchronously
imageLoader.displayImage(imageUrl, imageView);
```

### Most detailed
``` java
ImageView imageView = ...
String imageUrl = "http://site.com/image.png"; // or "file:///mnt/sdcard/images/image.jpg"
ProgressBar spinner = ...
File cacheDir = StorageUtils.getOwnCacheDirectory(getApplicationContext(), "UniversalImageLoader/Cache");

// Get singletone instance of ImageLoader
ImageLoader imageLoader = ImageLoader.getInstance();
// Create configuration for ImageLoader (all options are optional, use only those you really want to customize)
ImageLoaderConfiguration config = new ImageLoaderConfiguration.Builder(getApplicationContext())
			.memoryCacheExtraOptions(480, 800) // max width, max height
			.discCacheExtraOptions(480, 800, CompressFormat.JPEG, 75) // Can slow ImageLoader, use it carefully (Better don't use it)
			.threadPoolSize(3)
			.threadPriority(Thread.NORM_PRIORITY - 1)
			.denyCacheImageMultipleSizesInMemory()
			.offOutOfMemoryHandling()
			.memoryCache(new UsingFreqLimitedMemoryCache(2 * 1024 * 1024)) // You can pass your own memory cache implementation
			.discCache(new UnlimitedDiscCache(cacheDir)) // You can pass your own disc cache implementation
			.discCacheFileNameGenerator(new HashCodeFileNameGenerator())
			.imageDownloader(new URLConnectionImageDownloader(5 * 1000, 20 * 1000)) // connectTimeout (5 s), readTimeout (20 s)
			.defaultDisplayImageOptions(DisplayImageOptions.createSimple())
			.enableLogging()
			.build();
// Initialize ImageLoader with created configuration. Do it once.
imageLoader.init(config);

// Creates display image options for custom display task (all options are optional)
DisplayImageOptions options = new DisplayImageOptions.Builder()
                                       .showStubImage(R.drawable.stub_image)
									   .showImageForEmptyUri(R.drawable.image_for_empty_url)
                                       .cacheInMemory()
                                       .cacheOnDisc()
									   .imageScaleType(ImageScaleType.POWER_OF_2)
                                       .build();
// Load and display image
imageLoader.displayImage(imageUrl, imageView, options, new ImageLoadingListener() {
    @Override
    public void onLoadingStarted() {
       spinner.show();
    }
	@Override
	public void onLoadingFailed(FailReason failReason) {
		spinner.hide();
	}
    @Override
    public void onLoadingComplete(Bitmap loadedImage) {
        spinner.hide();
    }
	@Override
    public void onLoadingCancelled() {
        // Do nothing
    }
});
```

## Useful info
1. How UIL define Bitmap size needed for exact ImageView? Search defined parameters top-down:
 * Get ```android:layout_width``` or ```android:layout_height``` parameters
 * Get ```android:maxWidth``` and ```android:maxHeight``` parameters
 * Get maximum size parameters from configuration (```memoryCacheExtraOptions(int, int)``` option)

 Set ```android:layout_width```|```android:layout_height``` or ```android:maxWidth```|```android:maxHeight``` parameters for ImageView if you know approximate maximum size of it. It will help correctly compute Bitmap size needed for this view and **save memory**.

2. If you often got **OutOfMemoryError** in your app using Universal Image Loader then try set WeakMemoryCache into configuration:
``` java
ImageLoaderConfiguration config = new ImageLoaderConfiguration.Builder(getApplicationContext())
			...
			.memoryCache(new WeakMemoryCache())
			...
			.build();
```

3. For memory cache configuration (ImageLoaderConfiguration.Builder.memoryCache(...)) you can use already prepared implementations:
 * UsingFreqLimitedMemoryCache (The least frequently used bitmap is deleted when cache size limit is exceeded) - Used by default
 * LRULimitedMemoryCache (Least recently used bitmap is deleted when cache size limit is exceeded)
 * FIFOLimitedMemoryCache (FIFO rule is used for deletion when cache size limit is exceeded)
 * LargestLimitedMemoryCache (The largest bitmap is deleted when cache size limit is exceeded)
 * LimitedAgeMemoryCache (Decorator. Cached object is deleted when its age exceeds defined value)
 * WeakMemoryCache (Memory cache with only weak references to bitmaps)

4. For disc cache configuration (ImageLoaderConfiguration.Builder.discCache(...)) you can use already prepared implementations:
 * UnlimitedDiscCache (The fastest cache, doesn't limit cache size) - Used by default
 * TotalSizeLimitedDiscCache (Cache limited by total cache size. If cache size exceeds specified limit then file with the most oldest last usage date will be deleted)
 * FileCountLimitedDiscCache (Cache limited by file count. If file count in cache directory exceeds specified limit then file with the most oldest last usage date will be deleted. Use it if your cached files are of about the same size.)
 * LimitedAgeDiscCache (Size-unlimited cache with limited files' lifetime. If age of cached file exceeds defined limit then it will be deleted from cache.)
 
 **NOTE:** UnlimitedDiscCache is 30%-faster than other limited disc cache implementations.

## Applications using Universal Image Loader
* [MediaHouse, UPnP/DLNA Browser](https://play.google.com/store/apps/details?id=com.dbapp.android.mediahouse)
* [Деловой Киров](https://play.google.com/store/apps/details?id=ru.normakirov.dknorma)
* [Бизнес-завтрак](https://play.google.com/store/apps/details?id=ru.normakirov.businesslunch)
* [Menu55](http://www.free-lance.ru/users/max475imus/viewproj.php?prjid=3152141)
* [SpokenPic](http://spokenpic.com)
* [Kumir](https://play.google.com/store/apps/details?id=ru.premiakumir.android)
* [EUKO 2012](https://play.google.com/store/apps/details?id=de.netlands.emsapp)
* [TuuSo Image Search](https://play.google.com/store/apps/details?id=com.tuuso)
* [Газета Стройка](https://play.google.com/store/apps/details?id=ru.normakirov.stroyka)
* [<NAME> (AndroidFuel)](https://play.google.com/store/apps/details?id=org.vernazza.androidfuel)
* [Quiz Guess The Guy] (https://play.google.com/store/apps/details?id=com.game.guesstheguy)
* [Volksempfänger (alpha)](http://volksempfaenger.0x4a42.net)
* [ROM Toolbox Lite](https://play.google.com/store/apps/details?id=com.jrummy.liberty.toolbox) | [Pro](https://play.google.com/store/apps/details?id=com.jrummy.liberty.toolboxpro)
* [London 2012 Games](https://play.google.com/store/apps/details?id=com.mbwasi.london)
* [카톡 이미지 - 예쁜 프로필 이미지](https://play.google.com/store/apps/details?id=com.bydoori.firstbasea)
* [dailyPen](https://play.google.com/store/apps/details?id=com.bydoori.dailypen)
* [TK App](https://play.google.com/store/apps/details?id=com.opendream.tkapp)
* [Mania!](https://play.google.com/store/apps/details?id=com.astro.mania.activities)
* [Stadium Astro](https://play.google.com/store/apps/details?id=com.astro.stadium.activities)
* [Chef Astro](https://play.google.com/store/apps/details?id=com.sencha.test)
* [Lafemme Fashion Finder](https://play.google.com/store/apps/details?id=me.getlafem.lafemme2)

## License
Copyright (c) 2011-2012, [<NAME>](http://nostra13android.blogspot.com)

If you use Universal Image Loader code in your application you have to inform the author about it (*email: nostra13[at]gmail[dot]com*). Also you should (but you don't have to) mention it in application UI with string **"Used Universal-Image-Loader (c) 2011-2012, <NAME>"** (e.g. in some "About" section).

Licensed under the [BSD 3-clause](http://www.opensource.org/licenses/BSD-3-Clause)
{'fraction_non_alphanumeric': 0.11917453950493481, 'fraction_numerical': 0.015147516757270281, 'mean_word_length': 4.674752920035939, 'pattern_counts': {'":': 0, '<': 10, '<?xml version=': 0, '>': 10, 'https://': 43, 'lorem ipsum': 0, 'www.': 10, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 18, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3645393', 'n_tokens_mistral': 5926, 'n_tokens_neox': 5427, 'n_words': 1485}