Fork me on GitHub

VutaImage

Android Library that makes it easy to download images with a simple and straight forward API.

Introduction

VutaImage is an Android library that makes the work of downloading images from a URL to the device's SDCARD pretty much easy with a very simple and straight forward API.

At a glance

final String imageUrl = "http://myexample.com/img/sample1.png";
VutaImage.download( imageUrl, new ImageDownloadCallback() {
   @Override
   public void progress(int elapsed, int totalSize) {
      Log.e( TAG , "Image download progress = "+elapsed+" out of "+totalSize );
   }

   @Override
   public void done(boolean success) {
      Log.e( TAG , "Image download done with success = "+success );
   }
});

Installation

1. Using Library Jar file - Recommended

Download the latest jar file from VutaImage_Jar_1.0

  • Copy the jar file to your project’s libs folder
  • Right click the imported jar file, select build path then click add to build path.

2. Using the Library project

Download VutaImage project from the github project page https://github.com/bmutinda/VutaImage, import VutaImage-Library to your workspace as an Android Project. Once the project has been imported successfully,

  • Right click the project VutaImage
  • Go to properties->Android then on Library panel..click Is Library checkbox.
  • Go to your project, right click , go to properties->Android then on Library panel Click Add, then select VutaImage in the list of theavailable libraries
  • Click Apply then Ok.

NB:

Remember to add these permissions to your Android project 

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

Usage & Examples

Lets see how to use VutaImage to download images

1. Single image download

a). Given the image url only

You can download an image without specifying the destination filename and the library with automatically resolve the filename from the supplied link. For instance, downloading an image from http://www.example.com/images/image.png, the downloaded image will be saved with the name image.png in the default storage location - which is the sdcard 

final String imageUrl = "http://myexample.com/img/sample1.png";
VutaImage.download( imageUrl, new ImageDownloadCallback() {
   @Override
   public void progress(int elapsed, int totalSize) {
      Log.e( TAG , "Image download progress = "+elapsed+" out of "+totalSize );
   }

   @Override
   public void done(boolean success) {
      Log.e( TAG , "Image download done with success = "+success );
   }
});

b). Given the image url and the destination filename

NB: The destination filename must be the complete path together with the directory.

  • This will work /sdcard0/mydir/myfile.png
  • While this won't work myfile.png
final String imageUrl = "http://myexample.com/img/sample1.png";
String sdCard = VutaImage.getExternalStorage( );
String filename = sdCard+"/file.png";

VutaImage.download( imageUrl, filename, new ImageDownloadCallback() {
   @Override
   public void progress(int elapsed, int totalSize) {
      Log.e( TAG , "Image download progress = "+elapsed+" out of "+totalSize );
   }
   
   @Override
   public void done(boolean success) {
      Log.e( TAG , "Image download done with success = "+success );
   }
});

c). Using the VutaImageItem object

You can use an instance of the VutaImageItem as a parameter to download the image 

String sdCard = VutaImage.getExternalStorage( );
VutaImageItem vutaImageItem = new VutaImageItem(
	"http://domain.com/img.png", sdcard+"/image.png" );

VutaImage.download( vutaImageItem, new ImageDownloadCallback() {
   @Override
   public void progress(int elapsedSize, int totalSize) {
      Log.e("TAG_", "iMAGE progress --- "+elapsedSize+" out of ->"+totalSize );
   }
   
   @Override
   public void done(boolean success) {
      Log.e("TAG_", "iMAGE done with status --- "+success );
   }
});


2. Multiple images download

Define a list of all the images you want to download using the VutaImageItem class as follows 

// Get the sdcard directory 
String sdcard = VutaImage.getExternalStorage();

// Create a list of all the images we want to download 
List images = new ArrayList();
images.add( new VutaImageItem("http://myexample.com/img/sample1.png", sdcard+"/img.png" ));
images.add( new VutaImageItem("http://myexample.com/img/sample2.png", sdcard+"/Logo1.png" ));
images.add( new VutaImageItem("http://myexample.com/img/sampl23.png", sdcard+"/Logo2.png" ));

With multiple images download, there are two callbacks you can use

  • ImagesDownloadCallback - you are notified on
    1. Each image download error and
    2. When all the downloads are complete
  • EachImageDownloadCallback - you are notified on
    1. Each image download complete
    2. Each image download error and
    3. When all the downloads are complete

a). With callback for each image download - EachImageDownloadCallback 

VutaImage.download(images, new EachImageDownloadCallback() {
   @Override
   public void onProgress(VutaImageItem image, boolean success) {
      Log.e(TAG, "Image downloads progress.."+image.getUrl()+"->success = "+success );
   }

   @Override
   public void onError(VutaImageItem image) {
      Log.e(TAG, "Image failed to download.."+image.getUrl() );
   }

   @Override
   public void done() {
      Log.e(TAG, "All images downloaded" );
   }
});

b). With callback for all images download - ImagesDownloadCallback 

VutaImage.download(images, new ImagesDownloadCallback() {
   @Override
   public void onError(VutaImageItem image) {
      Log.e(TAG, "Image failed to download..."+image.getUrl()+"->"+image.getFilename() );
   }

   @Override
   public void done() {
      Log.e(TAG, "All images downloaded" );
   }
});

Configurations

1. Setting default storage location

You can set the default storage location for the downloaded images in cases where you are supplying only the image url. For instance, in this case 

VutaImage.download("http://myexample.com/img/sample1.png", new ImageDownloadCallback() {
   ......
});
The image is downloaded to the default storage which is the SDCARD.
To choose a different storage location, use the method below. All subsequent image downloads will be stored in the location specified as the parameter to the method. 
VutaImage.setDefaultStorageDir( "/my/dir/path/")

2. Getting the default storage location

To get the set default location, use the method below: 

VutaImage.getDefaultStorageDir()
NB: If you don't call the VutaImage.setDefaultStorageDir( "/my/dir/path/"), the default storage will be the root of the sdcard.

Methods Documentation

1. Callback methods

1). progress(int elapsed, int totalSize)

Called during the download progress of a single image 

// The first parameter(elapsed) holds the total file size already downloaded in KB
// Second parameter (totalSize) - Is the file total size in KB
@Override
public void progress(int elapsed, int totalSize) { .... }

2). public void onProgress(VutaImageItem image, boolean success)

Called during the download of multiple images after one image has been downloaded fully or an error occurred while downloading. 

// First parameter -image - represents the VutaImageItem instance of the image downloaded
// Second parameter - success - tells whether the download went on ok (True) or an error occurred (False)
@Override
public void onProgress(VutaImageItem image, boolean success) { .... }

3). public void onError(VutaImageItem image) {

Called if an error is encountered during the download process of multiple images
NB: This method is triggered just before onProgress(VutaImageItem image, boolean success) 

// First parameter -image - represents the VutaImageItem instance of the image that failed
@Override
public void onError(VutaImageItem image) { .... }

4). done(boolean success)

Called when the download is fully completed with or without errors for a single image download 

// success - True if everything was downloaded without error 
//         - False if an error occurred during download process
@Override
public void done( boolean success) { .... }

5). done()

Called when the download is fully completed with or without errors for multiple images download 

@Override
public void done() { .... }

Contributing

Code changes

Clone the project from the GitHub page, work on your changes then submit a pull-request and I will review and merge to the main branch for the next release

Library issues

Feel free to submit any issues about the library on the GitHub project issues page

Features

Need to propose a feature or need to say something? Drop me an email at boniface.info@gmail.com with the subject VutaImage Library