Skip to content

Latest commit

 

History

History
265 lines (226 loc) · 16 KB

README.md

File metadata and controls

265 lines (226 loc) · 16 KB
Raw

Logo Universal Image Loader

UIL aims to provide a powerful, flexible and highly customizable instrument for image loading, caching and displaying. It provides a lot of configuration options and good control over the image loading and caching process.

Screenshot

Project News

Upcoming changes in new UIL version (1.9.4+)

  • Memory Cache redesign
  • New API: DisplayImageOptions.targetSize(ImageSize)
  • HTTP cache support
  • Consider BitmapFactory.Options.inBitmap
  • ImageLoader.loadImageSync() fix
  • Time-to-live option for files in LruDiskCache

Features

  • Multithread image loading (async or sync)
  • Wide customization of ImageLoader's configuration (thread executors, downloader, decoder, memory and disk cache, display image options, etc.)
  • Many customization options for every display image call (stub images, caching switch, decoding options, Bitmap processing and displaying, etc.)
  • Image caching in memory and/or on disk (device's file system or SD card)
  • Listening loading process (including downloading progress)

Android 2.0+ support

Downloads

Documentation | Useful Info | User Support | Changelog

Quick Setup

1. Include library

Manual:

  • Download JAR
  • Put the JAR in the libs subfolder of your Android project

or

Maven dependency:

<dependency>
	<groupId>com.nostra13.universalimageloader</groupId>
	<artifactId>universal-image-loader</artifactId>
	<version>1.9.3</version>
</dependency>

or

Gradle dependency:

compile 'com.nostra13.universalimageloader:universal-image-loader:1.9.3'

2. Android Manifest

<manifest>
	<!-- Include following permission if you load images from Internet -->
	<uses-permission android:name="android.permission.INTERNET" />
	<!-- Include following permission if you want to cache images on SD card -->
	<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
	...
</manifest>

3. Application or Activity class (before the first usage of ImageLoader)

public class MyActivity extends Activity {
	@Override
	public void onCreate() {
		super.onCreate();

		// Create global configuration and initialize ImageLoader with this config
		ImageLoaderConfiguration config = new ImageLoaderConfiguration.Builder(this)
			...
			.build();
		ImageLoader.getInstance().init(config);
		...
	}
}

Configuration and Display Options

  • ImageLoader Configuration (ImageLoaderConfiguration) is global for application.
  • Display Options (DisplayImageOptions) are local for every display task (ImageLoader.displayImage(...)).

Configuration

All options in Configuration builder are optional. Use only those you really want to customize.
See default values for config options in Java docs for every option.

// DON'T COPY THIS CODE TO YOUR PROJECT! This is just example of ALL options using.
// See the sample project how to use ImageLoader correctly.
File cacheDir = StorageUtils.getCacheDirectory(context);
ImageLoaderConfiguration config = new ImageLoaderConfiguration.Builder(context)
		.memoryCacheExtraOptions(480, 800) // default = device screen dimensions
		.diskCacheExtraOptions(480, 800, null)
		.taskExecutor(...)
		.taskExecutorForCachedImages(...)
		.threadPoolSize(3) // default
		.threadPriority(Thread.NORM_PRIORITY - 2) // default
		.tasksProcessingOrder(QueueProcessingType.FIFO) // default
		.denyCacheImageMultipleSizesInMemory()
		.memoryCache(new LruMemoryCache(2 * 1024 * 1024))
		.memoryCacheSize(2 * 1024 * 1024)
		.memoryCacheSizePercentage(13) // default
		.diskCache(new UnlimitedDiscCache(cacheDir)) // default
		.diskCacheSize(50 * 1024 * 1024)
		.diskCacheFileCount(100)
		.diskCacheFileNameGenerator(new HashCodeFileNameGenerator()) // default
		.imageDownloader(new BaseImageDownloader(context)) // default
		.imageDecoder(new BaseImageDecoder()) // default
		.defaultDisplayImageOptions(DisplayImageOptions.createSimple()) // default
		.writeDebugLogs()
		.build();

Display Options

Display Options can be applied to every display task (ImageLoader.displayImage(...) call).

Note: If Display Options wasn't passed to ImageLoader.displayImage(...)method then default Display Options from configuration (ImageLoaderConfiguration.defaultDisplayImageOptions(...)) will be used.

// DON'T COPY THIS CODE TO YOUR PROJECT! This is just example of ALL options using.
// See the sample project how to use ImageLoader correctly.
DisplayImageOptions options = new DisplayImageOptions.Builder()
		.showImageOnLoading(R.drawable.ic_stub) // resource or drawable
		.showImageForEmptyUri(R.drawable.ic_empty) // resource or drawable
		.showImageOnFail(R.drawable.ic_error) // resource or drawable
		.resetViewBeforeLoading(false)  // default
		.delayBeforeLoading(1000)
		.cacheInMemory(false) // default
		.cacheOnDisk(false) // default
		.preProcessor(...)
		.postProcessor(...)
		.extraForDownloader(...)
		.considerExifParams(false) // default
		.imageScaleType(ImageScaleType.IN_SAMPLE_POWER_OF_2) // default
		.bitmapConfig(Bitmap.Config.ARGB_8888) // default
		.decodingOptions(...)
		.displayer(new SimpleBitmapDisplayer()) // default
		.handler(new Handler()) // default
		.build();

Usage

Acceptable URIs examples

String imageUri = "http://site.com/image.png"; // from Web
String imageUri = "file:///mnt/sdcard/image.png"; // from SD card
String imageUri = "content://media/external/audio/albumart/13"; // from content provider
String imageUri = "assets://image.png"; // from assets
String imageUri = "drawable://" + R.drawable.img; // from drawables (non-9patch images)

NOTE: Use drawable:// only if you really need it! Always consider the native way to load drawables - ImageView.setImageResource(...) instead of using of ImageLoader.

Simple

// Load image, decode it to Bitmap and display Bitmap in ImageView (or any other view 
//	which implements ImageAware interface)
imageLoader.displayImage(imageUri, imageView);
// Load image, decode it to Bitmap and return Bitmap to callback
imageLoader.loadImage(imageUri, new SimpleImageLoadingListener() {
	@Override
	public void onLoadingComplete(String imageUri, View view, Bitmap loadedImage) {
		// Do whatever you want with Bitmap
	}
});
// Load image, decode it to Bitmap and return Bitmap synchronously
Bitmap bmp = imageLoader.loadImageSync(imageUri);

Complete

// Load image, decode it to Bitmap and display Bitmap in ImageView (or any other view 
//	which implements ImageAware interface)
imageLoader.displayImage(imageUri, imageView, options, new ImageLoadingListener() {
	@Override
	public void onLoadingStarted(String imageUri, View view) {
		...
	}
	@Override
	public void onLoadingFailed(String imageUri, View view, FailReason failReason) {
		...
	}
	@Override
	public void onLoadingComplete(String imageUri, View view, Bitmap loadedImage) {
		...
	}
	@Override
	public void onLoadingCancelled(String imageUri, View view) {
		...
	}
}, new ImageLoadingProgressListener() {
	@Override
	public void onProgressUpdate(String imageUri, View view, int current, int total) {
		...
	}
});
// Load image, decode it to Bitmap and return Bitmap to callback
ImageSize targetSize = new ImageSize(80, 50); // result Bitmap will be fit to this size
imageLoader.loadImage(imageUri, targetSize, options, new SimpleImageLoadingListener() {
	@Override
	public void onLoadingComplete(String imageUri, View view, Bitmap loadedImage) {
		// Do whatever you want with Bitmap
	}
});
// Load image, decode it to Bitmap and return Bitmap synchronously
ImageSize targetSize = new ImageSize(80, 50); // result Bitmap will be fit to this size
Bitmap bmp = imageLoader.loadImageSync(imageUri, targetSize, options);

Applications using Universal Image Loader

MediaHouse, UPnP/DLNA Browser | Prezzi Benzina (AndroidFuel) | ROM Toolbox Lite, Pro | Stadium Astro | Chef Astro | Sporee - Live Soccer Scores | EyeEm - Photo Filter Camera | PhotoDownloader for Facebook | Topface - meeting is easy | reddit is fun | Diaro - personal diary | WebMoney Keeper Mobile | LoL Memento League of Legends | Meetup | Vingle - Magazines by Fans | Anime Music Radio | WidgetLocker Theme Viewer | ShortBlogger for Tumblr | SnapDish Food Camera | Twitch | TVShow Time, TV show guide | Planning Center Services | Daybe - 일기가 되는 SNS | Lapse It | My Cloud Player for SoundCloud | SoundTracking | LoopLR Social Video | Reddit Pics HD | Hír24 | Immobilien Scout24 | Lieferheld - Pizza Pasta Sushi | Loocator: free sex datings | 벨팡-개편 이벤트,컬러링,벨소리,무료,최신가요,링투유 | Streambels AirPlay/DLNA Player | Ship Mate - All Cruise Lines | Disk & Storage Analyzer | 糗事百科 | Balance BY | Anti Theft Alarm - Security | XiiaLive™ - Internet Radio | Bandsintown Concerts | Save As Web Archive

Donation

You can support the project and thank the author for his hard work :)

Click here to lend your support to: Universal Image Loader for Android and make a donation at pledgie.com ! Flattr this

  • PayPal - nostra.uil[at]gmail[dot]com

Alternative libraries

License

If you use Universal Image Loader code in your application you should inform the author about it ( email: nostra13[at]gmail[dot]com ) like this:

Subject: UIL usage notification
Text: I use Universal Image Loader {lib_version} in {application_name} - {http://link_to_google_play}. I [allow | don't allow] to mention my app in section "Applications using Universal Image Loader" on GitHub.

Also I'll be grateful if you mention UIL in application UI with string "Using Universal Image Loader (c) 2011-2014, Sergey Tarasevich" (e.g. in some "About" section).

Copyright 2011-2014 Sergey Tarasevich

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.