Permalink
Browse files

First beta of SDWebImage 3.0

This version is a rewrite of the lib using iOS 5.0 as minimum target.
The lib as thus been refactored to use blocks/GCD from the ground up.
As a consequence, all delegate code style has been removed. The result
is a lot less lines of code and more flexibility.
  • Loading branch information...
1 parent 8963f99 commit 2227266c41c65f55d1e7f9a37ca2a30325689658 @rs committed Nov 4, 2012
View
@@ -1,3 +1,4 @@
+
Web Image
=========
@@ -8,9 +9,15 @@ It provides:
- An UIImageView category adding web image and cache management to the Cocoa Touch framework
- An asynchronous image downloader
- An asynchronous memory + disk image caching with automatic cache expiration handling
+- A background image decompression
- A guarantee that the same URL won't be downloaded several times
- A guarantee that bogus URLs won't be retried again and again
+- A guarantee that main thread will never be blocked
- Performances!
+- Use GCD and ARC
+
+NOTE: The version 3.0 of SDWebImage isn't fully backward compatible with 1.0 and requires iOS 5.0
+minimum. If you need iOS < 5.0 support, please use the last 2.0 version.
Motivation
----------
@@ -94,15 +101,14 @@ handled for you, from async downloads to caching management.
### Using blocks
-If your project's deployement target is set to iOS 4+, you may want to use the success/failure blocks to be
-notified when image have been retrieved from cache.
+With blocks, you can be notified about the image download progress and whenever the image retrival
+has completed with success or not:
+
```objective-c
// Here we use the new provided setImageWithURL: method to load the web image
[cell.imageView setImageWithURL:[NSURL URLWithString:@"http://www.domain.com/path/to/image.jpg"]
placeholderImage:[UIImage imageNamed:@"placeholder.png"]
- success:^(UIImage *image, BOOL cached) {... success code here ...}
- failure:^(NSError *error) {... failure code here ...}];
-];
+ completed:^(UIImage *image, NSError *error, BOOL fromCache) {... completion code here ...}];
```
Note: neither your success nor failure block will be call if your image request is canceled before completion.
@@ -118,29 +124,43 @@ Here is a simple example of how to use SDWebImageManager:
```objective-c
SDWebImageManager *manager = [SDWebImageManager sharedManager];
[manager downloadWithURL:imageURL
- delegate:self
options:0
- success:^(UIImage *image, BOOL cached)
+ progress:^(NSUInteger receivedSize, long long expectedSize)
{
- // do something with image
+ // progression tracking code
}
- failure:nil];
+ completed:^(UIImage *image, NSError *error, BOOL fromCache)
+ {
+ if (image)
+ {
+ // do something with image
+ }
+ }];
```
### Using Asynchronous Image Downloader Independently
-It is possible to use the async image downloader independently. You just have to create an instance
-of SDWebImageDownloader using its convenience constructor downloaderWithURL:delegate:.
+It's also possible to use the async image downloader independently:
+
```objective-c
-downloader = [SDWebImageDownloader downloaderWithURL:url delegate:self];
+[SDWebImageDownloader.sharedDownloader downloadImageWithURL:imageURL
+ options:0
+ progress:^(NSUInteger receivedSize, long long expectedSize)
+ {
+ // progression tracking code
+ }
+ completed:^(UIImage *image, NSError *error, BOOL finished)
+ {
+ if (image && finished)
+ {
+ // do something with image
+ }
+ }];
```
-The download will start immediately and the imageDownloader:didFinishWithImage: method from the
-SDWebImageDownloaderDelegate protocol will be called as soon as the download of image is completed.
-
### Using Asynchronous Image Caching Independently
-It is also possible to use the NSOperation based image cache store independently. SDImageCache
+It is also possible to use the aync based image cache store independently. SDImageCache
maintains a memory cache and an optional disk cache. Disk cache write operations are performed
asynchronous so it doesn't add unnecessary latency to the UI.
@@ -153,7 +173,11 @@ key is an application unique identifier for the image to cache. It is generally
the image.
```objective-c
-UIImage *myCachedImage = [[SDImageCache sharedImageCache] imageFromKey:myCacheKey];
+SDImageCache *imageCache = [SDImageCache.alloc initWithNamespace:@"myNamespace"];
+[imageCache queryDiskCacheForKey:myCacheKey done:^(UIImage *image)
+{
+ // image is not nil if image was found
+}];
```
By default SDImageCache will lookup the disk cache if an image can't be found in the memory cache.
@@ -182,11 +206,11 @@ the URL before to use it as a cache key:
```objective-c
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
- [[SDWebImageManager sharedManager] setCacheKeyFilter:^(NSURL *url)
+ SDWebImageManager.sharedManager.cacheKeyFilter:^(NSURL *url)
{
url = [[[NSURL alloc] initWithScheme:url.scheme host:url.host path:url.path] autorelease];
return [url absoluteString];
- }];
+ };
// Your app init code...
return YES;
@@ -205,12 +229,6 @@ The following article gives a way to workaround this issue:
[http://www.wrichards.com/blog/2011/11/sdwebimage-fixed-width-cell-images/](http://www.wrichards.com/blog/2011/11/sdwebimage-fixed-width-cell-images/)
-Automatic Reference Counting (ARC)
-----------------------------------
-
-You can use either style in your Cocoa project. SDWebImage Will figure out which you are using at compile
-time and do the right thing.
-
Installation
------------
Oops, something went wrong.

0 comments on commit 2227266

Please sign in to comment.