mirror of
https://github.com/zhigang1992/RETableViewManager.git
synced 2026-06-11 00:09:35 +08:00
371 lines
14 KiB
HTML
371 lines
14 KiB
HTML
<!DOCTYPE HTML>
|
||
<html>
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||
<title>SDWebImage 3.2 Reference</title>
|
||
<link rel="stylesheet" type="text/css" href="css/styles.css" media="all" />
|
||
<link rel="stylesheet" type="text/css" media="print" href="css/stylesPrint.css" />
|
||
<meta name="generator" content="appledoc 2.1 (build 840)" />
|
||
</head>
|
||
<body>
|
||
<header id="top_header">
|
||
<div id="library" class="hideInXcode">
|
||
<h1><a id="libraryTitle" href="index.html">SDWebImage 3.2 </a></h1>
|
||
<a id="developerHome" href="index.html">Olivier Poitrey</a>
|
||
</div>
|
||
|
||
<div id="title" role="banner">
|
||
<h1 class="hideInXcode">SDWebImage 3.2 Reference</h1>
|
||
</div>
|
||
<ul id="headerButtons" role="toolbar"></ul>
|
||
</header>
|
||
<article>
|
||
<div id="overview_contents" role="main">
|
||
<div class="main-navigation navigation-top">
|
||
<a href="hierarchy.html">Next</a>
|
||
</div>
|
||
<div id="header">
|
||
<div class="section-header">
|
||
<h1 class="title title-header">SDWebImage 3.2 Reference</h1>
|
||
</div>
|
||
</div>
|
||
<div id="container">
|
||
|
||
<div class="section section-overview index-overview">
|
||
|
||
|
||
<h1>Web Image</h1>
|
||
|
||
<p>This library provides a category for UIImageVIew with support for remote images coming from the web.</p>
|
||
|
||
<p>It provides:</p>
|
||
|
||
<ul>
|
||
<li>An UIImageView category adding web image and cache management to the Cocoa Touch framework</li>
|
||
<li>An asynchronous image downloader</li>
|
||
<li>An asynchronous memory + disk image caching with automatic cache expiration handling</li>
|
||
<li>A background image decompression</li>
|
||
<li>A guarantee that the same URL won’t be downloaded several times</li>
|
||
<li>A guarantee that bogus URLs won’t be retried again and again</li>
|
||
<li>A guarantee that main thread will never be blocked</li>
|
||
<li>Performances!</li>
|
||
<li>Use GCD and ARC</li>
|
||
</ul>
|
||
|
||
|
||
<p>NOTE: The version 3.0 of SDWebImage isn’t fully backward compatible with 2.0 and requires iOS 5.0
|
||
minimum deployement version. If you need iOS < 5.0 support, please use the last <a href="https://github.com/rs/SDWebImage/tree/2.0-compat">2.0 version</a>.</p>
|
||
|
||
<p><a href="https://github.com/rs/SDWebImage/wiki/How-is-SDWebImage-better-than-X%3F">How is SDWebImage better than X?</a></p>
|
||
|
||
<h2>Who Use It</h2>
|
||
|
||
<p>Find out <a href="https://github.com/rs/SDWebImage/wiki/Who-Use-SDWebImage">who use SDWebImage</a> and add your app to the list.</p>
|
||
|
||
<h2>How To Use</h2>
|
||
|
||
<p>API documentation is available at <a href="http://hackemist.com/SDWebImage/doc/">http://hackemist.com/SDWebImage/doc/</a></p>
|
||
|
||
<h3>Using UIImageView+WebCache category with UITableView</h3>
|
||
|
||
<p>Just #import the UIImageView+WebCache.h header, and call the setImageWithURL:placeholderImage:
|
||
method from the tableView:cellForRowAtIndexPath: UITableViewDataSource method. Everything will be
|
||
handled for you, from async downloads to caching management.</p>
|
||
|
||
<p>```objective-c</p>
|
||
|
||
<h1>import <SDWebImage/UIImageView+WebCache.h></h1>
|
||
|
||
<p>…</p>
|
||
|
||
<ul>
|
||
<li><p>(UITableViewCell <em>)tableView:(UITableView </em>)tableView cellForRowAtIndexPath:(NSIndexPath <em>)indexPath
|
||
{
|
||
static NSString </em>MyIdentifier = @“MyIdentifier”;</p>
|
||
|
||
<p> UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:MyIdentifier];</p>
|
||
|
||
<p> if (cell == nil)
|
||
{
|
||
cell = [[[UITableViewCell alloc] initWithStyle:UITableViewCellStyleDefault
|
||
reuseIdentifier:MyIdentifier] autorelease];
|
||
}</p>
|
||
|
||
<p> // Here we use the new provided setImageWithURL: method to load the web image
|
||
[cell.imageView setImageWithURL:[NSURL URLWithString:@“<a href="http://www.domain.com/path/to/image.jpg">http://www.domain.com/path/to/image.jpg</a>”]
|
||
placeholderImage:[UIImage imageNamed:@“placeholder.png”]];</p>
|
||
|
||
<p> cell.textLabel.text = @“My Text”;
|
||
return cell;
|
||
}
|
||
```</p></li>
|
||
</ul>
|
||
|
||
|
||
<h3>Using blocks</h3>
|
||
|
||
<p>With blocks, you can be notified about the image download progress and whenever the image retrival
|
||
has completed with success or not:</p>
|
||
|
||
<p>```objective-c
|
||
// Here we use the new provided setImageWithURL: method to load the web image
|
||
[cell.imageView setImageWithURL:[NSURL URLWithString:@“<a href="http://www.domain.com/path/to/image.jpg">http://www.domain.com/path/to/image.jpg</a>”]</p>
|
||
|
||
<pre><code> placeholderImage:[UIImage imageNamed:@"placeholder.png"]
|
||
completed:^(UIImage *image, NSError *error, SDImageCacheType cacheType) {... completion code here ...}];
|
||
</code></pre>
|
||
|
||
<p>```</p>
|
||
|
||
<p>Note: neither your success nor failure block will be call if your image request is canceled before completion.</p>
|
||
|
||
<h3>Using <a href="Classes/SDWebImageManager.html">SDWebImageManager</a></h3>
|
||
|
||
<p>The <a href="Classes/SDWebImageManager.html">SDWebImageManager</a> is the class behind the UIImageView+WebCache category. It ties the
|
||
asynchronous downloader with the image cache store. You can use this class directly to benefit
|
||
from web image downloading with caching in another context than a UIView (ie: with Cocoa).</p>
|
||
|
||
<p>Here is a simple example of how to use <a href="Classes/SDWebImageManager.html">SDWebImageManager</a>:</p>
|
||
|
||
<p>```objective-c
|
||
<a href="Classes/SDWebImageManager.html">SDWebImageManager</a> *manager = <a href="Classes/SDWebImageManager.html#//api/name/sharedManager">[SDWebImageManager sharedManager]</a>;
|
||
[manager downloadWithURL:imageURL</p>
|
||
|
||
<pre><code> options:0
|
||
progress:^(NSUInteger receivedSize, long long expectedSize)
|
||
{
|
||
// progression tracking code
|
||
}
|
||
completed:^(UIImage *image, NSError *error, SDImageCacheType cacheType)
|
||
{
|
||
if (image)
|
||
{
|
||
// do something with image
|
||
}
|
||
}];
|
||
</code></pre>
|
||
|
||
<p>```</p>
|
||
|
||
<h3>Using Asynchronous Image Downloader Independently</h3>
|
||
|
||
<p>It’s also possible to use the async image downloader independently:</p>
|
||
|
||
<p>```objective-c
|
||
[<a href="Classes/SDWebImageDownloader.html">SDWebImageDownloader</a>.sharedDownloader downloadImageWithURL:imageURL</p>
|
||
|
||
<pre><code> 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
|
||
}
|
||
}];
|
||
</code></pre>
|
||
|
||
<p>```</p>
|
||
|
||
<h3>Using Asynchronous Image Caching Independently</h3>
|
||
|
||
<p>It is also possible to use the aync based image cache store independently. <a href="Classes/SDImageCache.html">SDImageCache</a>
|
||
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.</p>
|
||
|
||
<p>The <a href="Classes/SDImageCache.html">SDImageCache</a> class provides a singleton instance for convenience but you can create your own
|
||
instance if you want to create separated cache namespace.</p>
|
||
|
||
<p>To lookup the cache, you use the imageForKey: method. If the method returns nil, it means the cache
|
||
doesn’t currently own the image. You are thus responsible for generating and caching it. The cache
|
||
key is an application unique identifier for the image to cache. It is generally the absolute URL of
|
||
the image.</p>
|
||
|
||
<p>```objective-c
|
||
<a href="Classes/SDImageCache.html">SDImageCache</a> <em>imageCache = [SDImageCache.alloc initWithNamespace:@“myNamespace”];
|
||
[imageCache queryDiskCacheForKey:myCacheKey done:^(UIImage </em>image)
|
||
{</p>
|
||
|
||
<pre><code>// image is not nil if image was found
|
||
</code></pre>
|
||
|
||
<p>}];
|
||
```</p>
|
||
|
||
<p>By default <a href="Classes/SDImageCache.html">SDImageCache</a> will lookup the disk cache if an image can’t be found in the memory cache.
|
||
You can prevent this from happening by calling the alternative method <code>imageFromMemoryCacheForKey:</code>.</p>
|
||
|
||
<p>To store an image into the cache, you use the storeImage:forKey: method:</p>
|
||
|
||
<p><code>objective-c
|
||
[[SDImageCache sharedImageCache] storeImage:myImage forKey:myCacheKey];
|
||
</code></p>
|
||
|
||
<p>By default, the image will be stored in memory cache as well as on disk cache (asynchronously). If
|
||
you want only the memory cache, use the alternative method storeImage:forKey:toDisk: with a negative
|
||
third argument.</p>
|
||
|
||
<h3>Using cache key filter</h3>
|
||
|
||
<p>Sometime, you may not want to use the image URL as cache key because part of the URL is dynamic
|
||
(i.e.: for access control purpose). <a href="Classes/SDWebImageManager.html">SDWebImageManager</a> provides a way to set a cache key filter that
|
||
takes the NSURL as input, and output a cache key NSString.</p>
|
||
|
||
<p>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:</p>
|
||
|
||
<p>```objective-c
|
||
– (BOOL)application:(UIApplication <em>)application didFinishLaunchingWithOptions:(NSDictionary </em>)launchOptions
|
||
{</p>
|
||
|
||
<pre><code>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;
|
||
</code></pre>
|
||
|
||
<p>}
|
||
```</p>
|
||
|
||
<h2>Common Problems</h2>
|
||
|
||
<h3>Using dynamic image size with UITableViewCell</h3>
|
||
|
||
<p>UITableView determins the size of the image by the first image set for a cell. If your remote images
|
||
don’t have the same size as your placeholder image, you may experience strange anamorphic scaling issue.
|
||
The following article gives a way to workaround this issue:</p>
|
||
|
||
<p><a href="http://www.wrichards.com/blog/2011/11/sdwebimage-fixed-width-cell-images/">http://www.wrichards.com/blog/2011/11/sdwebimage-fixed-width-cell-images/</a></p>
|
||
|
||
<h2>Installation</h2>
|
||
|
||
<p>There are two ways to use this in your project: copy all the files into your project, or import the project as a static library.</p>
|
||
|
||
<h3>Add the SDWebImage project to your project</h3>
|
||
|
||
<ul>
|
||
<li>Download and unzip the last version of the framework from the <a href="https://github.com/rs/SDWebImage/wiki/Download-Complied-Framework">download page</a></li>
|
||
<li>Right-click on the project navigator and select “Add Files to "Your Project”:</li>
|
||
<li>In the dialog, select SDWebImage.framework:</li>
|
||
<li>Check the “Copy items into destination group’s folder (if needed)” checkbox</li>
|
||
</ul>
|
||
|
||
|
||
<h3>Add dependencies</h3>
|
||
|
||
<ul>
|
||
<li>In you application project app’s target settings, find the “Build Phases” section and open the “Link Binary With Libraries” block:</li>
|
||
<li>Click the “+” button again and select the “ImageIO.framework”, this is needed by the progressive download feature:</li>
|
||
</ul>
|
||
|
||
|
||
<h3>Add Linker Flag</h3>
|
||
|
||
<p>Open the “Build Settings” tab, in the “Linking” section, locate the “Other Linker Flags” setting and add the “-ObjC” flag:</p>
|
||
|
||
<p><img src="[http://dl.dropbox.com/u/123346/SDWebImage/10](http://dl.dropbox.com/u/123346/SDWebImage/10" alt="Other Linker Flags" />_other_linker_flags.jpg)</p>
|
||
|
||
<h3>Import headers in your source files</h3>
|
||
|
||
<p>In the source files where you need to use the library, import the header file:</p>
|
||
|
||
<p>```objective-c</p>
|
||
|
||
<h1>import <SDWebImage/UIImageView+WebCache.h></h1>
|
||
|
||
<p>```</p>
|
||
|
||
<h3>Build Project</h3>
|
||
|
||
<p>At this point your workspace should build without error. If you are having problem, post to the Issue and the
|
||
community can help you solve it.</p>
|
||
|
||
<h2>Future Enhancements</h2>
|
||
|
||
<ul>
|
||
<li>LRU memory cache cleanup instead of reset on memory warning</li>
|
||
</ul>
|
||
|
||
|
||
<h2>Licenses</h2>
|
||
|
||
<p>All source code is licensed under the <a href="https://raw.github.com/rs/SDWebImage/master/LICENSE">MIT License</a>.</p>
|
||
|
||
|
||
</div>
|
||
|
||
|
||
|
||
|
||
|
||
<div class="index-column">
|
||
<h2 class="index-title">Class References</h2>
|
||
<ul>
|
||
|
||
<li><a href="Classes/SDImageCache.html">SDImageCache</a></li>
|
||
|
||
<li><a href="Classes/SDWebImageDownloader.html">SDWebImageDownloader</a></li>
|
||
|
||
<li><a href="Classes/SDWebImageDownloaderOperation.html">SDWebImageDownloaderOperation</a></li>
|
||
|
||
<li><a href="Classes/SDWebImageManager.html">SDWebImageManager</a></li>
|
||
|
||
<li><a href="Classes/SDWebImagePrefetcher.html">SDWebImagePrefetcher</a></li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
|
||
|
||
<div class="index-column">
|
||
|
||
<h2 class="index-title">Protocol References</h2>
|
||
<ul>
|
||
|
||
<li><a href="Protocols/SDWebImageManagerDelegate.html">SDWebImageManagerDelegate</a></li>
|
||
|
||
<li><a href="Protocols/SDWebImageOperation.html">SDWebImageOperation</a></li>
|
||
|
||
</ul>
|
||
|
||
|
||
<h2 class="index-title">Category References</h2>
|
||
<ul>
|
||
|
||
<li><a href="Categories/MKAnnotationView+WebCache.html">MKAnnotationView(WebCache)</a></li>
|
||
|
||
<li><a href="Categories/UIButton+WebCache.html">UIButton(WebCache)</a></li>
|
||
|
||
<li><a href="Categories/UIImage+ForceDecode.html">UIImage(ForceDecode)</a></li>
|
||
|
||
<li><a href="Categories/UIImageView+WebCache.html">UIImageView(WebCache)</a></li>
|
||
|
||
</ul>
|
||
|
||
</div>
|
||
|
||
</div>
|
||
<div class="main-navigation navigation-bottom">
|
||
<a href="hierarchy.html">Next</a>
|
||
</div>
|
||
<div id="footer">
|
||
<hr />
|
||
<div class="footer-copyright">
|
||
<p><span class="copyright">© 2013 Olivier Poitrey. All rights reserved. (Last updated: 2013-04-02)</span><br />
|
||
|
||
<span class="generator">Generated by <a href="http://appledoc.gentlebytes.com">appledoc 2.1 (build 840)</a>.</span></p>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</article>
|
||
</body>
|
||
</html> |