mirrors
/
SDWebImage
mirror of https://github.com/SDWebImage/SDWebImage.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add appledoc comments

This commit is contained in:
Olivier Poitrey 2012-05-10 14:07:38 +02:00
parent 6574083a95
commit 110799614f
15 changed files with 375 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
Examples/SDWebImage Demo.xcodeproj/project.pbxproj
View File

@ -18,7 +18,7 @@
537612B6155AB74D005750A4 /* DetailViewController.xib in Resources */ = {isa = PBXBuildFile; fileRef = 537612B4155AB74D005750A4 /* DetailViewController.xib */; };
537612E7155ABA44005750A4 /* ImageIO.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 537612E6155ABA44005750A4 /* ImageIO.framework */; };
53761328155AD31B005750A4 /* MapKit.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 537612E3155ABA3C005750A4 /* MapKit.framework */; };
53A2B4FC155B096D00B12423 /* libSDWebImage ARC.a in Frameworks */ = {isa = PBXBuildFile; fileRef = 53A2B4F9155B095800B12423 /* libSDWebImage ARC.a */; };
53A2B4FC155B096D00B12423 /* libSDWebImageARC.a in Frameworks */ = {isa = PBXBuildFile; fileRef = 53A2B4F9155B095800B12423 /* libSDWebImageARC.a */; };
53A2B50D155B155A00B12423 /* placeholder.png in Resources */ = {isa = PBXBuildFile; fileRef = 53A2B50B155B155A00B12423 /* placeholder.png */; };
53A2B50E155B155A00B12423 /* placeholder@2x.png in Resources */ = {isa = PBXBuildFile; fileRef = 53A2B50C155B155A00B12423 /* placeholder@2x.png */; };
/* End PBXBuildFile section */
@ -77,7 +77,7 @@
isa = PBXFrameworksBuildPhase;
buildActionMask = 2147483647;
files = (
53A2B4FC155B096D00B12423 /* libSDWebImage ARC.a in Frameworks */,
53A2B4FC155B096D00B12423 /* libSDWebImageARC.a in Frameworks */,
53761328155AD31B005750A4 /* MapKit.framework in Frameworks */,
537612E7155ABA44005750A4 /* ImageIO.framework in Frameworks */,
5376129A155AB74D005750A4 /* UIKit.framework in Frameworks */,
@ -222,7 +222,7 @@
53A2B4F9155B095800B12423 /* libSDWebImage ARC.a */ = {
isa = PBXReferenceProxy;
fileType = archive.ar;
path = "libSDWebImage ARC.a";
path = libSDWebImageARC.a;
remoteRef = 53A2B4F8155B095800B12423 /* PBXContainerItemProxy */;
sourceTree = BUILT_PRODUCTS_DIR;
};

30
README.md
View File

@ -115,28 +115,14 @@ Here is a simple example of how to use SDWebImageManager:
```objective-c
SDWebImageManager *manager = [SDWebImageManager sharedManager];
UIImage *cachedImage = [manager imageWithURL:url];
if (cachedImage)
{
// Use the cached image immediatly
}
else
{
// Start an async download
[manager downloadWithURL:url delegate:self];
}
```
Your class will have to implement the SDWebImageManagerDelegate protocol, and to implement the
webImageManager:didFinishWithImage: method from this protocol:
```objective-c
- (void)webImageManager:(SDWebImageManager *)imageManager didFinishWithImage:(UIImage *)image
{
// Do something with the downloaded image
}
[manager downloadWithURL:imageURL
delegate:self
options:0
success:^(UIImage *image)
{
// do something with image
}
failure:nil];
```
### Using Asynchronous Image Downloader Independently

3
SDWebImage/MKAnnotationView+WebCache.h
View File

@ -11,6 +11,9 @@
#import "SDWebImageManagerDelegate.h"
#import "SDWebImageManager.h"
/**
* Integrates SDWebImage async downloading and caching of remote images with MKAnnotationView.
*/
@interface MKAnnotationView (WebCache) <SDWebImageManagerDelegate>
/**

91
SDWebImage/SDImageCache.h
View File

@ -9,6 +9,10 @@
#import <Foundation/Foundation.h>
#import "SDImageCacheDelegate.h"
/**
* 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.
*/
@interface SDImageCache : NSObject
{
NSMutableDictionary *memCache;
@ -16,19 +20,106 @@
NSOperationQueue *cacheInQueue, *cacheOutQueue;
}
/**
* Returns global shared cache instance
*
* @return SDImageCache global instance
*/
+ (SDImageCache *)sharedImageCache;
/**
* Store an image into memory and disk cache at the given key.
*
* @param image The image to store
* @param key The unique image cache key, usually it's image absolute URL
*/
- (void)storeImage:(UIImage *)image forKey:(NSString *)key;
/**
* Store an image into memory and optionally disk cache at the given key.
*
* @param image The image to store
* @param key The unique image cache key, usually it's image absolute URL
* @param toDisk Store the image to disk cache if YES
*/
- (void)storeImage:(UIImage *)image forKey:(NSString *)key toDisk:(BOOL)toDisk;
/**
* Store an image into memory and optionally disk cache at the given key.
*
* @param image The image to store
* @param data The image data as returned by the server, this representation will be used for disk storage
* instead of converting the given image object into a storable/compressed image format in order
* to save quality and CPU
* @param key The unique image cache key, usually it's image absolute URL
* @param toDisk Store the image to disk cache if YES
*/
- (void)storeImage:(UIImage *)image imageData:(NSData *)data forKey:(NSString *)key toDisk:(BOOL)toDisk;
/**
* Query the memory cache for an image at a given key and fallback to disk cache
* synchronousely if not found in memory.
*
* @warning This method may perform some synchronous IO operations
*
* @param key The unique key used to store the wanted image
*/
- (UIImage *)imageFromKey:(NSString *)key;
/**
* Query the memory cache for an image at a given key and optionnaly fallback to disk cache
* synchronousely if not found in memory.
*
* @warning This method may perform some synchronous IO operations if fromDisk is YES
*
* @param key The unique key used to store the wanted image
* @param fromDisk Try to retrive the image from disk if not found in memory if YES
*/
- (UIImage *)imageFromKey:(NSString *)key fromDisk:(BOOL)fromDisk;
/**
* Query the disk cache asynchronousely.
*
* @param key The unique key used to store the wanted image
* @param delegate The delegate object to send response to
* @param info An NSDictionary with some user info sent back to the delegate
*/
- (void)queryDiskCacheForKey:(NSString *)key delegate:(id <SDImageCacheDelegate>)delegate userInfo:(NSDictionary *)info;
/**
* Remove the image from memory and disk cache synchronousely
*
* @param key The unique image cache key
*/
- (void)removeImageForKey:(NSString *)key;
/**
* Remove the image from memory and optionaly disk cache synchronousely
*
* @param key The unique image cache key
* @param fromDisk Also remove cache entry from disk if YES
*/
- (void)removeImageForKey:(NSString *)key fromDisk:(BOOL)fromDisk;
/**
* Clear all memory cached images
*/
- (void)clearMemory;
/**
* Clear all disk cached images
*/
- (void)clearDisk;
/**
* Remove all expired cached image from disk
*/
- (void)cleanDisk;
/**
* Get the size used by the disk cache
*/
- (int)getSize;
@end

20
SDWebImage/SDImageCacheDelegate.h
View File

@ -10,10 +10,30 @@
@class SDImageCache;
/**
* Delegate protocol for SDImageCache
*/
@protocol SDImageCacheDelegate <NSObject>
@optional
/**
* Called when [SDImageCache queryDiskCacheForKey:delegate:userInfo:] retrived the image from cache
*
* @param imageCache The cache store instance
* @param image The requested image instance
* @param key The requested image cache key
* @param info The provided user info dictionary
*/
- (void)imageCache:(SDImageCache *)imageCache didFindImage:(UIImage *)image forKey:(NSString *)key userInfo:(NSDictionary *)info;
/**
* Called when [SDImageCache queryDiskCacheForKey:delegate:userInfo:] did not find the image in the cache
*
* @param imageCache The cache store instance
* @param key The requested image cache key
* @param info The provided user info dictionary
*/
- (void)imageCache:(SDImageCache *)imageCache didNotFindImageForKey:(NSString *)key userInfo:(NSDictionary *)info;
@end

18
SDWebImage/SDWebImageCompat.h
View File

@ -49,14 +49,26 @@
#endif
NS_INLINE UIImage *SDScaledImageForPath(NSString *path, NSData *imageData)
NS_INLINE UIImage *SDScaledImageForPath(NSString *path, NSObject *imageOrData)
{
if (!imageData)
if (!imageOrData)
{
return nil;
}
UIImage *image = [[UIImage alloc] initWithData:imageData];
UIImage *image = nil;
if ([imageOrData isKindOfClass:[NSData class]])
{
image = [[UIImage alloc] initWithData:(NSData *)imageOrData];
}
else if ([imageOrData isKindOfClass:[NSData class]])
{
image = SDWIReturnRetained((UIImage *)imageOrData);
}
else
{
return nil;
}
if ([[UIScreen mainScreen] respondsToSelector:@selector(scale)])
{

31
SDWebImage/SDWebImageDecoder.h
View File

@ -13,18 +13,49 @@
@protocol SDWebImageDecoderDelegate;
/**
* Decoding image data is the most expensive step, and it is performed on the main thread. SDWebImageDecoder force the
* image decoding in a separate thread so UIImage will have high chance to reuse the cached result when used by UI in
* the main thread.
*
* @see https://github.com/rs/SDWebImage/pull/18
*/
@interface SDWebImageDecoder : NSObject
{
NSOperationQueue *imageDecodingQueue;
}
/**
* Returns a shared global instance of image decoder
*
* @return An SDWebImageDecoder shared instance
*/
+ (SDWebImageDecoder *)sharedImageDecoder;
/**
* Pre-decode a given image in a separate thread.
*
* @param image The image to pre-decode
* @param delegate The object to notify once pre-decoding is completed
* @param info A user info object
*/
- (void)decodeImage:(UIImage *)image withDelegate:(id <SDWebImageDecoderDelegate>)delegate userInfo:(NSDictionary *)info;
@end
/**
* Delegate protocol for SDWebImageDecoder
*/
@protocol SDWebImageDecoderDelegate <NSObject>
/**
* Called when pre-decoding is completed
*
* @param decoder The image decoder instance
* @param image The pre-decoded image
* @param userInfo the provided user info dictionary
*/
- (void)imageDecoder:(SDWebImageDecoder *)decoder didFinishDecodingImage:(UIImage *)image userInfo:(NSDictionary *)userInfo;
@end

32
SDWebImage/SDWebImageDownloader.h
View File

@ -13,6 +13,9 @@
extern NSString *const SDWebImageDownloadStartNotification;
extern NSString *const SDWebImageDownloadStopNotification;
/**
* Asynchronous downloader dedicated and optimized for image loading.
*/
@interface SDWebImageDownloader : NSObject
{
@private
@ -32,12 +35,41 @@ extern NSString *const SDWebImageDownloadStopNotification;
@property (nonatomic, retain) NSMutableData *imageData;
@property (nonatomic, retain) id userInfo;
@property (nonatomic, readwrite) BOOL lowPriority;
/**
* If set to YES, enables progressive download support.
*
* The [SDWebImageDownloaderDelegate imageDownloader:didUpdatePartialImage:] delegate method is then called
* while the image is downloaded with an image object containing the portion of the currently downloaded
* image.
*
* @see http://www.cocoaintheshell.com/2011/05/progressive-images-download-imageio/
*/
@property (nonatomic, readwrite) BOOL progressive;
/**
* Creates a SDWebImageDownloader async downloader instance with a given URL
*
* The delegate will be informed when the image is finish downloaded or an error has happen.
*
* @see SDWebImageDownloaderDelegate
*
* @param url The URL to the image to download
* @param delegate The delegate object
* @param userInfo A NSDictionary containing custom info
* @param lowPriority Ensure the download won't run during UI interactions
*
* @return A new SDWebImageDownloader instance
*/
+ (id)downloaderWithURL:(NSURL *)url delegate:(id<SDWebImageDownloaderDelegate>)delegate userInfo:(id)userInfo lowPriority:(BOOL)lowPriority;
+ (id)downloaderWithURL:(NSURL *)url delegate:(id<SDWebImageDownloaderDelegate>)delegate userInfo:(id)userInfo;
+ (id)downloaderWithURL:(NSURL *)url delegate:(id<SDWebImageDownloaderDelegate>)delegate;
- (void)start;
/**
* Cancel the download immediatelly
*/
- (void)cancel;
// This method is now no-op and is deprecated

24
SDWebImage/SDWebImageDownloaderDelegate.h
View File

@ -10,13 +10,37 @@
@class SDWebImageDownloader;
/**
* Delegate protocol for SDWebImageDownloader
*/
@protocol SDWebImageDownloaderDelegate <NSObject>
@optional
- (void)imageDownloaderDidFinish:(SDWebImageDownloader *)downloader;
/**
* Called repeatedly while the image is downloading when [SDWebImageDownloader progressive] is enabled.
*
* @param downloader The SDWebImageDownloader instance
* @param image The partial image representing the currently download portion of the image
*/
- (void)imageDownloader:(SDWebImageDownloader *)downloader didUpdatePartialImage:(UIImage *)image;
/**
* Called when download completed successfuly.
*
* @param downloader The SDWebImageDownloader instance
* @param image The downloaded image object
*/
- (void)imageDownloader:(SDWebImageDownloader *)downloader didFinishWithImage:(UIImage *)image;
/**
* Called when an error occurred
*
* @param downloader The SDWebImageDownloader instance
* @param error The error details
*/
- (void)imageDownloader:(SDWebImageDownloader *)downloader didFailWithError:(NSError *)error;
@end

81
SDWebImage/SDWebImageManager.h
View File

@ -19,6 +19,24 @@ typedef enum
SDWebImageProgressiveDownload = 1 << 3
} SDWebImageOptions;
/**
* The SDWebImageManager is the class behind the UIImageView+WebCache category and likes.
* It ties the asynchronous downloader (SDWebImageDownloader) with the image cache store (SDImageCache).
* You can use this class directly to benefit from web image downloading with caching in another context than
* a UIView.
*
* Here is a simple example of how to use SDWebImageManager:
*
* SDWebImageManager *manager = [SDWebImageManager sharedManager];
* [manager downloadWithURL:imageURL
* delegate:self
* options:0
* success:^(UIImage *image)
* {
* // do something with image
* }
* failure:nil];
*/
@interface SDWebImageManager : NSObject <SDWebImageDownloaderDelegate, SDImageCacheDelegate>
{
NSMutableArray *downloadDelegates;
@ -31,19 +49,76 @@ typedef enum
#if NS_BLOCKS_AVAILABLE
typedef NSString *(^CacheKeyFilter)(NSURL *url);
/**
* The cache filter is a block used each time SDWebManager need to convert an URL into a cache key. This can
* be used to remove dynamic part of an image URL.
*
* The following example sets a filter in the application delegate that will remove any query-string from the
* URL before to use it as a cache key:
*
* [[SDWebImageManager sharedManager] setCacheKeyFilter:^(NSURL *url)
* {
* url = [[NSURL alloc] initWithScheme:url.scheme host:url.host path:url.path];
* return [url absoluteString];
* }];
*/
@property (strong) CacheKeyFilter cacheKeyFilter;
#endif
/**
* Returns global SDWebImageManager instance.
*
* @return SDWebImageManager shared instance
*/
+ (id)sharedManager;
- (UIImage *)imageWithURL:(NSURL *)url;
- (UIImage *)imageWithURL:(NSURL *)url __attribute__ ((deprecated));
/**
* Downloads the image at the given URL if not present in cache or return the cached version otherwise.
*
* @param url The URL to the image
* @param delegate The delegate object used to send result back
* @see [SDWebImageManager downloadWithURL:delegate:options:]
* @see [SDWebImageManager downloadWithURL:delegate:options:success:failure:]
*/
- (void)downloadWithURL:(NSURL *)url delegate:(id<SDWebImageManagerDelegate>)delegate;
/**
* Downloads the image at the given URL if not present in cache or return the cached version otherwise.
*
* @param url The URL to the image
* @param delegate The delegate object used to send result back
* @param options A mask to specify options to use for this request
* @see [SDWebImageManager downloadWithURL:delegate:options:success:failure:]
*/
- (void)downloadWithURL:(NSURL *)url delegate:(id<SDWebImageManagerDelegate>)delegate options:(SDWebImageOptions)options;
- (void)downloadWithURL:(NSURL *)url delegate:(id<SDWebImageManagerDelegate>)delegate retryFailed:(BOOL)retryFailed __attribute__ ((deprecated)); // use options:SDWebImageRetryFailed instead
- (void)downloadWithURL:(NSURL *)url delegate:(id<SDWebImageManagerDelegate>)delegate retryFailed:(BOOL)retryFailed lowPriority:(BOOL)lowPriority __attribute__ ((deprecated)); // use options:SDWebImageRetryFailed|SDWebImageLowPriority instead
// use options:SDWebImageRetryFailed instead
- (void)downloadWithURL:(NSURL *)url delegate:(id<SDWebImageManagerDelegate>)delegate retryFailed:(BOOL)retryFailed __attribute__ ((deprecated));
// use options:SDWebImageRetryFailed|SDWebImageLowPriority instead
- (void)downloadWithURL:(NSURL *)url delegate:(id<SDWebImageManagerDelegate>)delegate retryFailed:(BOOL)retryFailed lowPriority:(BOOL)lowPriority __attribute__ ((deprecated));
#if NS_BLOCKS_AVAILABLE
/**
* Downloads the image at the given URL if not present in cache or return the cached version otherwise.
*
* @param url The URL to the image
* @param delegate The delegate object used to send result back
* @param options A mask to specify options to use for this request
* @param success A block called when image has been retrived successfuly
* @param failure A block called when couldn't be retrived for some reason
* @see [SDWebImageManager downloadWithURL:delegate:options:]
*/
- (void)downloadWithURL:(NSURL *)url delegate:(id)delegate options:(SDWebImageOptions)options success:(void (^)(UIImage *image))success failure:(void (^)(NSError *error))failure;
#endif
/**
* Cancel all pending download requests for a given delegate
*
* @param delegate The delegate to cancel requests for
*/
- (void)cancelForDelegate:(id<SDWebImageManagerDelegate>)delegate;
@end

6
SDWebImage/SDWebImageManager.m
View File

@ -76,7 +76,7 @@ static SDWebImageManager *instance;
#endif
}
/**
/*
* @deprecated
*/
- (UIImage *)imageWithURL:(NSURL *)url
@ -84,7 +84,7 @@ static SDWebImageManager *instance;
return [[SDImageCache sharedImageCache] imageFromKey:[self cacheKeyForURL:url]];
}
/**
/*
* @deprecated
*/
- (void)downloadWithURL:(NSURL *)url delegate:(id<SDWebImageManagerDelegate>)delegate retryFailed:(BOOL)retryFailed
@ -92,7 +92,7 @@ static SDWebImageManager *instance;
[self downloadWithURL:url delegate:delegate options:(retryFailed ? SDWebImageRetryFailed : 0)];
}
/**
/*
* @deprecated
*/
- (void)downloadWithURL:(NSURL *)url delegate:(id<SDWebImageManagerDelegate>)delegate retryFailed:(BOOL)retryFailed lowPriority:(BOOL)lowPriority

27
SDWebImage/SDWebImageManagerDelegate.h
View File

@ -9,14 +9,37 @@
@class SDWebImageManager;
@class UIImage;
/**
* Delegate protocol for SDWebImageManager
*/
@protocol SDWebImageManagerDelegate <NSObject>
@optional
/**
* Called while an image is downloading with an partial image object representing the currently downloaded portion of the image.
* This delegate is called only if ImageIO is available and `SDWebImageProgressiveDownload` option has been used.
*/
- (void)webImageManager:(SDWebImageManager *)imageManager didProgressWithPartialImage:(UIImage *)image forURL:(NSURL *)url;
- (void)webImageManager:(SDWebImageManager *)imageManager didFinishWithImage:(UIImage *)image;
/**
* Called when image download is completed successfuly.
*
* @param imageManager The image manager
* @param image The retrived image object
* @param url The image URL used to retrive the image
*/
- (void)webImageManager:(SDWebImageManager *)imageManager didFinishWithImage:(UIImage *)image forURL:(NSURL *)url;
- (void)webImageManager:(SDWebImageManager *)imageManager didFailWithError:(NSError *)error;
- (void)webImageManager:(SDWebImageManager *)imageManager didFinishWithImage:(UIImage *)image;
/**
* Called when an error occurred.
*
* @param imageManager The image manager
* @param error The error
* @param url The image URL used to retrive the image
*/
- (void)webImageManager:(SDWebImageManager *)imageManager didFailWithError:(NSError *)error forURL:(NSURL *)url;
- (void)webImageManager:(SDWebImageManager *)imageManager didFailWithError:(NSError *)error;
@end

8
SDWebImage/SDWebImagePrefetcher.h
View File

@ -9,6 +9,9 @@
#import <Foundation/Foundation.h>
#import "SDWebImageManagerDelegate.h"
/**
* Prefetch some URLs in the cache for future use. Images are downloaded in low priority.
*/
@interface SDWebImagePrefetcher : NSObject <SDWebImageManagerDelegate>
{
NSArray *_prefetchURLs;
@ -23,6 +26,9 @@
*/
@property (nonatomic, assign) NSUInteger maxConcurrentDownloads;
/**
* Return the global image prefetcher instance.
*/
+ (SDWebImagePrefetcher *)sharedImagePrefetcher;
/**
@ -30,7 +36,7 @@
* currently one image is downloaded at a time,
* and skips images for failed downloads and proceed to the next image in the list
*
* @param NSArray list of URLs to prefetch
* @param urls list of URLs to prefetch
*/
- (void)prefetchURLs:(NSArray *)urls;

3
SDWebImage/UIButton+WebCache.h
View File

@ -10,6 +10,9 @@
#import "SDWebImageManagerDelegate.h"
#import "SDWebImageManager.h"
/**
* Integrates SDWebImage async downloading and caching of remote images with UIButtonView.
*/
@interface UIButton (WebCache) <SDWebImageManagerDelegate>
/**

32
SDWebImage/UIImageView+WebCache.h
View File

@ -10,6 +10,38 @@
#import "SDWebImageManagerDelegate.h"
#import "SDWebImageManager.h"
/**
* Integrates SDWebImage async downloading and caching of remote images with UIImageView.
*
* Usage with a UITableViewCell sub-class:
*
* #import <SDWebImage/UIImageView+WebCache.h>
*
* ...
*
* - (UITableViewCell *)tableView:(UITableView *)tableView
* cellForRowAtIndexPath:(NSIndexPath *)indexPath
* {
* static NSString *MyIdentifier = @"MyIdentifier";
*
* UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:MyIdentifier];
*
* if (cell == nil)
* {
* cell = [[[UITableViewCell alloc] initWithStyle:UITableViewCellStyleDefault
* reuseIdentifier:MyIdentifier] autorelease];
* }
*
* // Here we use the provided setImageWithURL: method to load the web image
* // Ensure you use a placeholder image otherwise cells will be initialized with no image
* [cell.imageView setImageWithURL:[NSURL URLWithString:@"http://example.com/image.jpg"]
* placeholderImage:[UIImage imageNamed:@"placeholder"]];
*
* cell.textLabel.text = @"My Text";
* return cell;
* }
*
*/
@interface UIImageView (WebCache) <SDWebImageManagerDelegate>
/**