SDAnimatedImageView

@interface SDAnimatedImageView : UIImageView

A drop-in replacement for UIImageView/NSImageView, you can use this for animated image rendering. Call setImage: with UIImage(NSImage) which conform to SDAnimatedImage protocol will start animated image rendering. Call with normal UIImage(NSImage) will back to normal UIImageView(NSImageView) rendering For UIKit: use -startAnimating, -stopAnimating to control animating. isAnimating to check animation state. For AppKit: use -setAnimates: to control animating, animates to check animation state. This view is layer-backed.

  • Current display frame image. This value is KVO Compliance.

    Declaration

    Objective-C

    @property (readonly, strong, nonatomic, nullable) UIImage *currentFrame;

    Swift

    var currentFrame: UIImage? { get }
  • Current frame index, zero based. This value is KVO Compliance.

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSUInteger currentFrameIndex;

    Swift

    var currentFrameIndex: UInt { get }
  • Current loop count since its latest animating. This value is KVO Compliance.

    Declaration

    Objective-C

    @property (readonly, nonatomic) NSUInteger currentLoopCount;

    Swift

    var currentLoopCount: UInt { get }
  • YES to choose animationRepeatCount property for animation loop count. No to use animated image’s animatedImageLoopCount instead. Default is NO.

    Declaration

    Objective-C

    @property (nonatomic) BOOL shouldCustomLoopCount;

    Swift

    var shouldCustomLoopCount: Bool { get set }
  • Total loop count for animated image rendering. Default is animated image’s loop count. If you need to set custom loop count, set shouldCustomLoopCount to YES and change this value. This class override UIImageView’s animationRepeatCount property on iOS, use this property as well.

    Declaration

    Objective-C

    @property (nonatomic) NSInteger animationRepeatCount;

    Swift

    var animationRepeatCount: Int { get set }
  • The animation playback rate. Default is 1.0. 1.0 means the normal speed. 0.0 means stopping the animation. 0.0-1.0 means the slow speed. > 1.0 means the fast speed. < 0.0 is not supported currently and stop animation. (may support reverse playback in the future)

    Declaration

    Objective-C

    @property (nonatomic) double playbackRate;

    Swift

    var playbackRate: Double { get set }
  • Provide a max buffer size by bytes. This is used to adjust frame buffer count and can be useful when the decoding cost is expensive (such as Animated WebP software decoding). Default is 0. 0 means automatically adjust by calculating current memory usage. 1 means without any buffer cache, each of frames will be decoded and then be freed after rendering. (Lowest Memory and Highest CPU) NSUIntegerMax means cache all the buffer. (Lowest CPU and Highest Memory)

    Declaration

    Objective-C

    @property (nonatomic) NSUInteger maxBufferSize;

    Swift

    var maxBufferSize: UInt { get set }
  • Whehter or not to enable incremental image load for animated image. This is for the animated image which sd_isIncremental is YES (See UIImage+Metadata.h). If enable, animated image rendering will stop at the last frame available currently, and continue when another setImage: trigger, where the new animated image’s animatedImageData should be updated from the previous one. If the sd_isIncremental is NO. The incremental image load stop.

    Note

    If you are confused about this description, open Chrome browser to view some large GIF images with low network speed to see the animation behavior.

    Note

    The best practice to use incremental load is using initWithAnimatedCoder:scale: in SDAnimatedImage with animated coder which conform to SDProgressiveImageCoder as well. Then call incremental update and incremental decode method to produce the image. Default is YES. Set to NO to only render the static poster for incremental animated image.

    Declaration

    Objective-C

    @property (nonatomic) BOOL shouldIncrementalLoad;

    Swift

    var shouldIncrementalLoad: Bool { get set }
  • Whether or not to clear the frame buffer cache when animation stopped. See maxBufferSize This is useful when you want to limit the memory usage during frequently visibility changes (such as image view inside a list view, then push and pop) Default is NO.

    Declaration

    Objective-C

    @property (nonatomic) BOOL clearBufferWhenStopped;

    Swift

    var clearBufferWhenStopped: Bool { get set }
  • Whether or not to reset the current frame index when animation stopped. For some of use case, you may want to reset the frame index to 0 when stop, but some other want to keep the current frame index. Default is NO.

    Declaration

    Objective-C

    @property (nonatomic) BOOL resetFrameIndexWhenStopped;

    Swift

    var resetFrameIndexWhenStopped: Bool { get set }
  • If the image has more than one frame, set this value to YES will automatically play/stop the animation when the view become visible/invisible. Default is YES.

    Declaration

    Objective-C

    @property (nonatomic) BOOL autoPlayAnimatedImage;

    Swift

    var autoPlayAnimatedImage: Bool { get set }
  • You can specify a runloop mode to let it rendering. Default is NSRunLoopCommonModes on multi-core device, NSDefaultRunLoopMode on single-core device

    Note

    This is useful for some cases, for example, always specify NSDefaultRunLoopMode, if you want to pause the animation when user scroll (for Mac user, drag the mouse or touchpad)

    Declaration

    Objective-C

    @property (copy, nonatomic, nonnull) NSRunLoopMode runLoopMode;

    Swift

    var runLoopMode: RunLoop.Mode { get set }

WebCache

  • Set the imageView image with an url.

    The download is asynchronous and cached.

    Declaration

    Objective-C

    - (void)sd_setImageWithURL:(nullable NSURL *)url;

    Swift

    func __sd_setImage(with url: URL?)

    Parameters

    url

    The url for the image.

  • Set the imageView image with an url and a placeholder.

    The download is asynchronous and cached.

    See

    sd_setImageWithURL:placeholderImage:options:

    Declaration

    Objective-C

    - (void)sd_setImageWithURL:(nullable NSURL *)url
              placeholderImage:(nullable UIImage *)placeholder;

    Swift

    func __sd_setImage(with url: URL?, placeholderImage placeholder: UIImage?)

    Parameters

    url

    The url for the image.

    placeholder

    The image to be set initially, until the image request finishes.

  • Set the imageView image with an url, placeholder and custom options.

    The download is asynchronous and cached.

    Declaration

    Objective-C

    - (void)sd_setImageWithURL:(nullable NSURL *)url
              placeholderImage:(nullable UIImage *)placeholder
                       options:(SDWebImageOptions)options;

    Swift

    func __sd_setImage(with url: URL?, placeholderImage placeholder: UIImage?, options: SDWebImageOptions = [])

    Parameters

    url

    The url for the image.

    placeholder

    The image to be set initially, until the image request finishes.

    options

    The options to use when downloading the image. - see: SDWebImageOptions for the possible values.

  • Set the imageView image with an url, placeholder, custom options and context.

    The download is asynchronous and cached.

    Declaration

    Objective-C

    - (void)sd_setImageWithURL:(nullable NSURL *)url
              placeholderImage:(nullable UIImage *)placeholder
                       options:(SDWebImageOptions)options
                       context:(nullable SDWebImageContext *)context;

    Swift

    func sd_setImage(with url: URL?, placeholderImage placeholder: UIImage?, options: SDWebImageOptions = [], context: [SDWebImageContextOption : Any]?)

    Parameters

    url

    The url for the image.

    placeholder

    The image to be set initially, until the image request finishes.

    options

    The options to use when downloading the image. - see: SDWebImageOptions for the possible values.

    context

    A context contains different options to perform specify changes or processes, see SDWebImageContextOption. This hold the extra objects which options enum can not hold.

  • Set the imageView image with an url.

    The download is asynchronous and cached.

    Declaration

    Objective-C

    - (void)sd_setImageWithURL:(nullable NSURL *)url
                     completed:(nullable SDExternalCompletionBlock)completedBlock;

    Swift

    func sd_setImage(with url: URL?, completed completedBlock: SDExternalCompletionBlock? = nil)

    Parameters

    url

    The url for the image.

    completedBlock

    A block called when operation has been completed. This block has no return value and takes the requested UIImage as first parameter. In case of error the image parameter is nil and the second parameter may contain an NSError. The third parameter is a Boolean indicating if the image was retrieved from the local cache or from the network. The fourth parameter is the original image url.

  • Set the imageView image with an url, placeholder.

    The download is asynchronous and cached.

    Declaration

    Objective-C

    - (void)sd_setImageWithURL:(nullable NSURL *)url
              placeholderImage:(nullable UIImage *)placeholder
                     completed:(nullable SDExternalCompletionBlock)completedBlock;

    Swift

    func __sd_setImage(with url: URL?, placeholderImage placeholder: UIImage?, completed completedBlock: SDExternalCompletionBlock? = nil)

    Parameters

    url

    The url for the image.

    placeholder

    The image to be set initially, until the image request finishes.

    completedBlock

    A block called when operation has been completed. This block has no return value and takes the requested UIImage as first parameter. In case of error the image parameter is nil and the second parameter may contain an NSError. The third parameter is a Boolean indicating if the image was retrieved from the local cache or from the network. The fourth parameter is the original image url.

  • Set the imageView image with an url, placeholder and custom options.

    The download is asynchronous and cached.

    Declaration

    Objective-C

    - (void)sd_setImageWithURL:(nullable NSURL *)url
              placeholderImage:(nullable UIImage *)placeholder
                       options:(SDWebImageOptions)options
                     completed:(nullable SDExternalCompletionBlock)completedBlock;

    Swift

    func sd_setImage(with url: URL?, placeholderImage placeholder: UIImage?, options: SDWebImageOptions = [], completed completedBlock: SDExternalCompletionBlock? = nil)

    Parameters

    url

    The url for the image.

    placeholder

    The image to be set initially, until the image request finishes.

    options

    The options to use when downloading the image. - see: SDWebImageOptions for the possible values.

    completedBlock

    A block called when operation has been completed. This block has no return value and takes the requested UIImage as first parameter. In case of error the image parameter is nil and the second parameter may contain an NSError. The third parameter is a Boolean indicating if the image was retrieved from the local cache or from the network. The fourth parameter is the original image url.

  • Set the imageView image with an url, placeholder and custom options.

    The download is asynchronous and cached.

    Declaration

    Objective-C

    - (void)sd_setImageWithURL:(nullable NSURL *)url
              placeholderImage:(nullable UIImage *)placeholder
                       options:(SDWebImageOptions)options
                      progress:(nullable SDImageLoaderProgressBlock)progressBlock
                     completed:(nullable SDExternalCompletionBlock)completedBlock;

    Swift

    func sd_setImage(with url: URL?, placeholderImage placeholder: UIImage?, options: SDWebImageOptions = [], progress progressBlock: SDImageLoaderProgressBlock?, completed completedBlock: SDExternalCompletionBlock? = nil)

    Parameters

    url

    The url for the image.

    placeholder

    The image to be set initially, until the image request finishes.

    options

    The options to use when downloading the image. - see: SDWebImageOptions for the possible values.

    progressBlock

    A block called while image is downloading - note: the progress block is executed on a background queue

    completedBlock

    A block called when operation has been completed. This block has no return value and takes the requested UIImage as first parameter. In case of error the image parameter is nil and the second parameter may contain an NSError. The third parameter is a Boolean indicating if the image was retrieved from the local cache or from the network. The fourth parameter is the original image url.

  • Set the imageView image with an url, placeholder, custom options and context.

    The download is asynchronous and cached.

    Declaration

    Objective-C

    - (void)sd_setImageWithURL:(nullable NSURL *)url
              placeholderImage:(nullable UIImage *)placeholder
                       options:(SDWebImageOptions)options
                       context:(nullable SDWebImageContext *)context
                      progress:(nullable SDImageLoaderProgressBlock)progressBlock
                     completed:(nullable SDExternalCompletionBlock)completedBlock;

    Swift

    func sd_setImage(with url: URL?, placeholderImage placeholder: UIImage?, options: SDWebImageOptions = [], context: [SDWebImageContextOption : Any]?, progress progressBlock: SDImageLoaderProgressBlock?, completed completedBlock: SDExternalCompletionBlock? = nil)

    Parameters

    url

    The url for the image.

    placeholder

    The image to be set initially, until the image request finishes.

    options

    The options to use when downloading the image. - see: SDWebImageOptions for the possible values.

    context

    A context contains different options to perform specify changes or processes, see SDWebImageContextOption. This hold the extra objects which options enum can not hold.

    progressBlock

    A block called while image is downloading - note: the progress block is executed on a background queue

    completedBlock

    A block called when operation has been completed. This block has no return value and takes the requested UIImage as first parameter. In case of error the image parameter is nil and the second parameter may contain an NSError. The third parameter is a Boolean indicating if the image was retrieved from the local cache or from the network. The fourth parameter is the original image url.