@octane-xplat/nativescript-mason-core 0.0.1 → 1.0.0-beta.0

package/platforms/ios/include/SDWebImage/NSButton+WebCache.h

@@ -0,0 +1,340 @@
+/*
+ * This file is part of the SDWebImage package.
+ * (c) Olivier Poitrey <rs@dailymotion.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+#import "SDWebImageCompat.h"
+
+#if SD_MAC
+
+#import "SDWebImageManager.h"
+
+/**
+ * Integrates SDWebImage async downloading and caching of remote images with NSButton.
+ */
+@interface NSButton (WebCache)
+
+#pragma mark - Image
+
+/**
+ * Get the current image URL.
+ */
+@property (nonatomic, strong, readonly, nullable) NSURL *sd_currentImageURL;
+
+/**
+ * Set the button `image` with an `url`.
+ *
+ * The download is asynchronous and cached.
+ *
+ * @param url The url for the image.
+ */
+- (void)sd_setImageWithURL:(nullable NSURL *)url NS_REFINED_FOR_SWIFT;
+
+/**
+ * Set the button `image` with an `url` and a placeholder.
+ *
+ * The download is asynchronous and cached.
+ *
+ * @param url         The url for the image.
+ * @param placeholder The image to be set initially, until the image request finishes.
+ * @see sd_setImageWithURL:placeholderImage:options:
+ */
+- (void)sd_setImageWithURL:(nullable NSURL *)url
+          placeholderImage:(nullable UIImage *)placeholder NS_REFINED_FOR_SWIFT;
+
+/**
+ * Set the button `image` with an `url`, placeholder and custom options.
+ *
+ * The download is asynchronous and cached.
+ *
+ * @param url         The url for the image.
+ * @param placeholder The image to be set initially, until the image request finishes.
+ * @param options     The options to use when downloading the image. @see SDWebImageOptions for the possible values.
+ */
+- (void)sd_setImageWithURL:(nullable NSURL *)url
+          placeholderImage:(nullable UIImage *)placeholder
+                   options:(SDWebImageOptions)options NS_REFINED_FOR_SWIFT;
+
+/**
+ * Set the button `image` with an `url`, placeholder and custom options.
+ *
+ * The download is asynchronous and cached.
+ *
+ * @param url         The url for the image.
+ * @param placeholder The image to be set initially, until the image request finishes.
+ * @param options     The options to use when downloading the image. @see SDWebImageOptions for the possible values.
+ * @param 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.
+ */
+- (void)sd_setImageWithURL:(nullable NSURL *)url
+          placeholderImage:(nullable UIImage *)placeholder
+                   options:(SDWebImageOptions)options
+                   context:(nullable SDWebImageContext *)context;
+
+/**
+ * Set the button `image` with an `url`.
+ *
+ * The download is asynchronous and cached.
+ *
+ * @param url            The url for the image.
+ * @param 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.
+ */
+- (void)sd_setImageWithURL:(nullable NSURL *)url
+                 completed:(nullable SDExternalCompletionBlock)completedBlock;
+
+/**
+ * Set the button `image` with an `url`, placeholder.
+ *
+ * The download is asynchronous and cached.
+ *
+ * @param url            The url for the image.
+ * @param placeholder    The image to be set initially, until the image request finishes.
+ * @param 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.
+ */
+- (void)sd_setImageWithURL:(nullable NSURL *)url
+          placeholderImage:(nullable UIImage *)placeholder
+                 completed:(nullable SDExternalCompletionBlock)completedBlock NS_REFINED_FOR_SWIFT;
+
+/**
+ * Set the button `image` with an `url`, placeholder and custom options.
+ *
+ * The download is asynchronous and cached.
+ *
+ * @param url            The url for the image.
+ * @param placeholder    The image to be set initially, until the image request finishes.
+ * @param options        The options to use when downloading the image. @see SDWebImageOptions for the possible values.
+ * @param 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.
+ */
+- (void)sd_setImageWithURL:(nullable NSURL *)url
+          placeholderImage:(nullable UIImage *)placeholder
+                   options:(SDWebImageOptions)options
+                 completed:(nullable SDExternalCompletionBlock)completedBlock;
+
+/**
+ * Set the button `image` with an `url`, placeholder and custom options.
+ *
+ * The download is asynchronous and cached.
+ *
+ * @param url            The url for the image.
+ * @param placeholder    The image to be set initially, until the image request finishes.
+ * @param options        The options to use when downloading the image. @see SDWebImageOptions for the possible values.
+ * @param progressBlock  A block called while image is downloading
+ *                       @note the progress block is executed on a background queue
+ * @param 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.
+ */
+- (void)sd_setImageWithURL:(nullable NSURL *)url
+          placeholderImage:(nullable UIImage *)placeholder
+                   options:(SDWebImageOptions)options
+                  progress:(nullable SDImageLoaderProgressBlock)progressBlock
+                 completed:(nullable SDExternalCompletionBlock)completedBlock;
+
+/**
+ * Set the button `image` with an `url`, placeholder and custom options.
+ *
+ * The download is asynchronous and cached.
+ *
+ * @param url            The url for the image.
+ * @param placeholder    The image to be set initially, until the image request finishes.
+ * @param options        The options to use when downloading the image. @see SDWebImageOptions for the possible values.
+ * @param 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.
+ * @param progressBlock  A block called while image is downloading
+ *                       @note the progress block is executed on a background queue
+ * @param 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.
+ */
+- (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;
+
+#pragma mark - Alternate Image
+
+/**
+ * Get the current alternateImage URL.
+ */
+@property (nonatomic, strong, readonly, nullable) NSURL *sd_currentAlternateImageURL;
+
+/**
+ * Set the button `alternateImage` with an `url`.
+ *
+ * The download is asynchronous and cached.
+ *
+ * @param url The url for the alternateImage.
+ */
+- (void)sd_setAlternateImageWithURL:(nullable NSURL *)url NS_REFINED_FOR_SWIFT;
+
+/**
+ * Set the button `alternateImage` with an `url` and a placeholder.
+ *
+ * The download is asynchronous and cached.
+ *
+ * @param url         The url for the alternateImage.
+ * @param placeholder The alternateImage to be set initially, until the alternateImage request finishes.
+ * @see sd_setAlternateImageWithURL:placeholderImage:options:
+ */
+- (void)sd_setAlternateImageWithURL:(nullable NSURL *)url
+                   placeholderImage:(nullable UIImage *)placeholder NS_REFINED_FOR_SWIFT;
+
+/**
+ * Set the button `alternateImage` with an `url`, placeholder and custom options.
+ *
+ * The download is asynchronous and cached.
+ *
+ * @param url         The url for the alternateImage.
+ * @param placeholder The alternateImage to be set initially, until the alternateImage request finishes.
+ * @param options     The options to use when downloading the alternateImage. @see SDWebImageOptions for the possible values.
+ */
+- (void)sd_setAlternateImageWithURL:(nullable NSURL *)url
+                   placeholderImage:(nullable UIImage *)placeholder
+                            options:(SDWebImageOptions)options NS_REFINED_FOR_SWIFT;
+
+/**
+ * Set the button `alternateImage` with an `url`, placeholder, custom options and context.
+ *
+ * The download is asynchronous and cached.
+ *
+ * @param url         The url for the alternateImage.
+ * @param placeholder The alternateImage to be set initially, until the alternateImage request finishes.
+ * @param options     The options to use when downloading the alternateImage. @see SDWebImageOptions for the possible values.
+ * @param 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.
+ */
+- (void)sd_setAlternateImageWithURL:(nullable NSURL *)url
+                   placeholderImage:(nullable UIImage *)placeholder
+                            options:(SDWebImageOptions)options
+                            context:(nullable SDWebImageContext *)context;
+
+/**
+ * Set the button `alternateImage` with an `url`.
+ *
+ * The download is asynchronous and cached.
+ *
+ * @param url            The url for the alternateImage.
+ * @param 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 alternateImage parameter
+ *                       is nil and the second parameter may contain an NSError. The third parameter is a Boolean
+ *                       indicating if the alternateImage was retrieved from the local cache or from the network.
+ *                       The fourth parameter is the original alternateImage url.
+ */
+- (void)sd_setAlternateImageWithURL:(nullable NSURL *)url
+                          completed:(nullable SDExternalCompletionBlock)completedBlock;
+
+/**
+ * Set the button `alternateImage` with an `url`, placeholder.
+ *
+ * The download is asynchronous and cached.
+ *
+ * @param url            The url for the alternateImage.
+ * @param placeholder    The alternateImage to be set initially, until the alternateImage request finishes.
+ * @param 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 alternateImage parameter
+ *                       is nil and the second parameter may contain an NSError. The third parameter is a Boolean
+ *                       indicating if the alternateImage was retrieved from the local cache or from the network.
+ *                       The fourth parameter is the original alternateImage url.
+ */
+- (void)sd_setAlternateImageWithURL:(nullable NSURL *)url
+                   placeholderImage:(nullable UIImage *)placeholder
+                          completed:(nullable SDExternalCompletionBlock)completedBlock NS_REFINED_FOR_SWIFT;
+
+/**
+ * Set the button `alternateImage` with an `url`, placeholder and custom options.
+ *
+ * The download is asynchronous and cached.
+ *
+ * @param url            The url for the alternateImage.
+ * @param placeholder    The alternateImage to be set initially, until the alternateImage request finishes.
+ * @param options        The options to use when downloading the alternateImage. @see SDWebImageOptions for the possible values.
+ * @param 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 alternateImage parameter
+ *                       is nil and the second parameter may contain an NSError. The third parameter is a Boolean
+ *                       indicating if the alternateImage was retrieved from the local cache or from the network.
+ *                       The fourth parameter is the original alternateImage url.
+ */
+- (void)sd_setAlternateImageWithURL:(nullable NSURL *)url
+                   placeholderImage:(nullable UIImage *)placeholder
+                            options:(SDWebImageOptions)options
+                          completed:(nullable SDExternalCompletionBlock)completedBlock;
+
+/**
+ * Set the button `alternateImage` with an `url`, placeholder and custom options.
+ *
+ * The download is asynchronous and cached.
+ *
+ * @param url            The url for the alternateImage.
+ * @param placeholder    The alternateImage to be set initially, until the alternateImage request finishes.
+ * @param options        The options to use when downloading the alternateImage. @see SDWebImageOptions for the possible values.
+ * @param progressBlock  A block called while alternateImage is downloading
+ *                       @note the progress block is executed on a background queue
+ * @param 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 alternateImage parameter
+ *                       is nil and the second parameter may contain an NSError. The third parameter is a Boolean
+ *                       indicating if the alternateImage was retrieved from the local cache or from the network.
+ *                       The fourth parameter is the original alternateImage url.
+ */
+- (void)sd_setAlternateImageWithURL:(nullable NSURL *)url
+                   placeholderImage:(nullable UIImage *)placeholder
+                            options:(SDWebImageOptions)options
+                           progress:(nullable SDImageLoaderProgressBlock)progressBlock
+                          completed:(nullable SDExternalCompletionBlock)completedBlock;
+
+/**
+ * Set the button `alternateImage` with an `url`, placeholder, custom options and context.
+ *
+ * The download is asynchronous and cached.
+ *
+ * @param url            The url for the alternateImage.
+ * @param placeholder    The alternateImage to be set initially, until the alternateImage request finishes.
+ * @param options        The options to use when downloading the alternateImage. @see SDWebImageOptions for the possible values.
+ * @param 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.
+ * @param progressBlock  A block called while alternateImage is downloading
+ *                       @note the progress block is executed on a background queue
+ * @param 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 alternateImage parameter
+ *                       is nil and the second parameter may contain an NSError. The third parameter is a Boolean
+ *                       indicating if the alternateImage was retrieved from the local cache or from the network.
+ *                       The fourth parameter is the original alternateImage url.
+ */
+- (void)sd_setAlternateImageWithURL:(nullable NSURL *)url
+                   placeholderImage:(nullable UIImage *)placeholder
+                            options:(SDWebImageOptions)options
+                            context:(nullable SDWebImageContext *)context
+                           progress:(nullable SDImageLoaderProgressBlock)progressBlock
+                          completed:(nullable SDExternalCompletionBlock)completedBlock;
+
+#pragma mark - Cancel
+
+/**
+ * Cancel the current image download
+ */
+- (void)sd_cancelCurrentImageLoad;
+
+/**
+ * Cancel the current alternateImage download
+ */
+- (void)sd_cancelCurrentAlternateImageLoad;
+
+@end
+
+#endif

package/platforms/ios/include/SDWebImage/NSData+ImageContentType.h

@@ -0,0 +1,63 @@
+/*
+ * This file is part of the SDWebImage package.
+ * (c) Olivier Poitrey <rs@dailymotion.com>
+ * (c) Fabrice Aneche
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+#import <Foundation/Foundation.h>
+#import "SDWebImageCompat.h"
+
+/**
+ You can use switch case like normal enum. It's also recommended to add a default case. You should not assume anything about the raw value.
+ For custom coder plugin, it can also extern the enum for supported format. See `SDImageCoder` for more detailed information.
+ */
+typedef NSInteger SDImageFormat NS_TYPED_EXTENSIBLE_ENUM;
+static const SDImageFormat SDImageFormatUndefined = -1;
+static const SDImageFormat SDImageFormatJPEG      = 0;
+static const SDImageFormat SDImageFormatPNG       = 1;
+static const SDImageFormat SDImageFormatGIF       = 2;
+static const SDImageFormat SDImageFormatTIFF      = 3;
+static const SDImageFormat SDImageFormatWebP      = 4;
+static const SDImageFormat SDImageFormatHEIC      = 5;
+static const SDImageFormat SDImageFormatHEIF      = 6;
+static const SDImageFormat SDImageFormatPDF       = 7;
+static const SDImageFormat SDImageFormatSVG       = 8;
+static const SDImageFormat SDImageFormatBMP       = 9;
+static const SDImageFormat SDImageFormatRAW       = 10;
+
+/**
+ NSData category about the image content type and UTI.
+ */
+@interface NSData (ImageContentType)
+
+/**
+ *  Return image format
+ *
+ *  @param data the input image data
+ *
+ *  @return the image format as `SDImageFormat` (enum)
+ */
++ (SDImageFormat)sd_imageFormatForImageData:(nullable NSData *)data;
+
+/**
+ *  Convert SDImageFormat to UTType
+ *
+ *  @param format Format as SDImageFormat
+ *  @return The UTType as CFStringRef
+ *  @note For unknown format, `kSDUTTypeImage` abstract type will return
+ */
++ (nonnull CFStringRef)sd_UTTypeFromImageFormat:(SDImageFormat)format CF_RETURNS_NOT_RETAINED NS_SWIFT_NAME(sd_UTType(from:));
+
+/**
+ *  Convert UTType to SDImageFormat
+ *
+ *  @param uttype The UTType as CFStringRef
+ *  @return The Format as SDImageFormat
+ *  @note For unknown type, `SDImageFormatUndefined` will return
+ */
++ (SDImageFormat)sd_imageFormatFromUTType:(nonnull CFStringRef)uttype;
+
+@end

package/platforms/ios/include/SDWebImage/NSImage+Compatibility.h

@@ -0,0 +1,67 @@
+/*
+ * This file is part of the SDWebImage package.
+ * (c) Olivier Poitrey <rs@dailymotion.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+#import "SDWebImageCompat.h"
+
+#if SD_MAC
+
+/**
+ This category is provided to easily write cross-platform(AppKit/UIKit) code. For common usage, see `UIImage+Metadata.h`.
+ */
+@interface NSImage (Compatibility)
+
+/**
+The underlying Core Graphics image object. This will actually use `CGImageForProposedRect` with the image size.
+ */
+@property (nonatomic, readonly, nullable) CGImageRef CGImage;
+/**
+ The underlying Core Image data. This will actually use `bestRepresentationForRect` with the image size to find the `NSCIImageRep`.
+ */
+@property (nonatomic, readonly, nullable) CIImage *CIImage;
+/**
+ The scale factor of the image. This wil actually use `bestRepresentationForRect` with image size and pixel size to calculate the scale factor. If failed, use the default value 1.0. Should be greater than or equal to 1.0.
+ */
+@property (nonatomic, readonly) CGFloat scale;
+
+// These are convenience methods to make AppKit's `NSImage` match UIKit's `UIImage` behavior. The scale factor should be greater than or equal to 1.0.
+
+/**
+ Returns an image object with the scale factor and orientation. The representation is created from the Core Graphics image object.
+ @note The difference between this and `initWithCGImage:size` is that `initWithCGImage:size` will actually create a `NSCGImageSnapshotRep` representation and always use `backingScaleFactor` as scale factor. So we should avoid it and use `NSBitmapImageRep` with `initWithCGImage:` instead.
+ @note The difference between this and UIKit's `UIImage` equivalent method is the way to process orientation. If the provided image orientation is not equal to Up orientation, this method will firstly rotate the CGImage to the correct orientation to work compatible with `NSImageView`. However, UIKit will not actually rotate CGImage and just store it as `imageOrientation` property.
+
+ @param cgImage A Core Graphics image object
+ @param scale The image scale factor
+ @param orientation The orientation of the image data
+ @return The image object
+ */
+- (nonnull instancetype)initWithCGImage:(nonnull CGImageRef)cgImage scale:(CGFloat)scale orientation:(CGImagePropertyOrientation)orientation;
+
+/**
+ Initializes and returns an image object with the specified Core Image object. The representation is `NSCIImageRep`.
+ 
+ @param ciImage A Core Image image object
+ @param scale The image scale factor
+ @param orientation The orientation of the image data
+ @return The image object
+ */
+- (nonnull instancetype)initWithCIImage:(nonnull CIImage *)ciImage scale:(CGFloat)scale orientation:(CGImagePropertyOrientation)orientation;
+
+/**
+ Returns an image object with the scale factor. The representation is created from the image data.
+ @note The difference between these this and `initWithData:` is that `initWithData:` will always use `backingScaleFactor` as scale factor.
+
+ @param data The image data
+ @param scale The image scale factor
+ @return The image object
+ */
+- (nullable instancetype)initWithData:(nonnull NSData *)data scale:(CGFloat)scale;
+
+@end
+
+#endif

package/platforms/ios/include/SDWebImage/SDAnimatedImage.h

@@ -0,0 +1,136 @@
+/*
+ * This file is part of the SDWebImage package.
+ * (c) Olivier Poitrey <rs@dailymotion.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+#import "SDWebImageCompat.h"
+#import "SDImageCoder.h"
+
+
+/**
+ This is the protocol for SDAnimatedImage class only but not for SDAnimatedImageCoder. If you want to provide a custom animated image class with full advanced function, you can conform to this instead of the base protocol.
+ */
+@protocol SDAnimatedImage <SDAnimatedImageProvider>
+
+@required
+/**
+ Initializes and returns the image object with the specified data, scale factor and possible animation decoding options.
+ @note We use this to create animated image instance for normal animation decoding.
+ 
+ @param data The data object containing the image data.
+ @param scale The scale factor to assume when interpreting the image data. Applying a scale factor of 1.0 results in an image whose size matches the pixel-based dimensions of the image. Applying a different scale factor changes the size of the image as reported by the `size` property.
+ @param options A dictionary containing any animation decoding options.
+ @return An initialized object
+ */
+- (nullable instancetype)initWithData:(nonnull NSData *)data scale:(CGFloat)scale options:(nullable SDImageCoderOptions *)options;
+
+/**
+ Initializes the image with an animated coder. You can use the coder to decode the image frame later.
+ @note We use this with animated coder which conforms to `SDProgressiveImageCoder` for progressive animation decoding.
+ 
+ @param animatedCoder An animated coder which conform `SDAnimatedImageCoder` protocol
+ @param scale The scale factor to assume when interpreting the image data. Applying a scale factor of 1.0 results in an image whose size matches the pixel-based dimensions of the image. Applying a different scale factor changes the size of the image as reported by the `size` property.
+ @return An initialized object
+ */
+- (nullable instancetype)initWithAnimatedCoder:(nonnull id<SDAnimatedImageCoder>)animatedCoder scale:(CGFloat)scale;
+
+@optional
+// These methods are used for optional advanced feature, like image frame preloading.
+/**
+ Pre-load all animated image frame into memory. Then later frame image request can directly return the frame for index without decoding.
+ This method may be called on background thread.
+ 
+ @note If one image instance is shared by lots of imageViews, the CPU performance for large animated image will drop down because the request frame index will be random (not in order) and the decoder should take extra effort to keep it re-entrant. You can use this to reduce CPU usage if need. Attention this will consume more memory usage.
+ */
+- (void)preloadAllFrames;
+
+/**
+ Unload all animated image frame from memory if are already pre-loaded. Then later frame image request need decoding. You can use this to free up the memory usage if need.
+ */
+- (void)unloadAllFrames;
+
+/**
+ Returns a Boolean value indicating whether all animated image frames are already pre-loaded into memory.
+ */
+@property (nonatomic, assign, readonly, getter=isAllFramesLoaded) BOOL allFramesLoaded;
+
+/**
+ Return the animated image coder if the image is created with `initWithAnimatedCoder:scale:` method.
+ @note We use this with animated coder which conforms to `SDProgressiveImageCoder` for progressive animation decoding.
+ */
+@property (nonatomic, strong, readonly, nullable) id<SDAnimatedImageCoder> animatedCoder;
+
+@end
+
+/**
+ The image class which supports animating on `SDAnimatedImageView`. You can also use it on normal UIImageView/NSImageView.
+ */
+NS_SWIFT_NONISOLATED
+@interface SDAnimatedImage : UIImage <SDAnimatedImage>
+
+// This class override these methods from UIImage(NSImage), and it supports NSSecureCoding.
+// You should use these methods to create a new animated image. Use other methods just call super instead.
+// @note Before 5.19, these initializer will return nil for static image (when all candidate SDAnimatedImageCoder returns nil instance), like JPEG data. After 5.19, these initializer will retry for static image as well, so JPEG data will return non-nil instance. For vector image(PDF/SVG), always return nil.
+// @note When the animated image frame count <= 1, all the `SDAnimatedImageProvider` protocol methods will return nil or 0 value, you'd better check the frame count before usage and keep fallback.
++ (nullable instancetype)imageNamed:(nonnull NSString *)name; // Cache in memory, no Asset Catalog support
+#if __has_include(<UIKit/UITraitCollection.h>) && !SD_WATCH
++ (nullable instancetype)imageNamed:(nonnull NSString *)name inBundle:(nullable NSBundle *)bundle compatibleWithTraitCollection:(nullable UITraitCollection *)traitCollection; // Cache in memory, no Asset Catalog support
+#else
++ (nullable instancetype)imageNamed:(nonnull NSString *)name inBundle:(nullable NSBundle *)bundle; // Cache in memory, no Asset Catalog support
+#endif
++ (nullable instancetype)imageWithContentsOfFile:(nonnull NSString *)path;
++ (nullable instancetype)imageWithData:(nonnull NSData *)data;
++ (nullable instancetype)imageWithData:(nonnull NSData *)data scale:(CGFloat)scale;
+- (nullable instancetype)initWithContentsOfFile:(nonnull NSString *)path;
+- (nullable instancetype)initWithData:(nonnull NSData *)data;
+- (nullable instancetype)initWithData:(nonnull NSData *)data scale:(CGFloat)scale;
+
+/**
+ Current animated image format.
+ @note This format is only valid when `animatedImageData` not nil.
+ @note This actually just call `[NSData sd_imageFormatForImageData:self.animatedImageData]`
+ */
+@property (nonatomic, assign, readonly) SDImageFormat animatedImageFormat;
+
+/**
+ Current animated image data, you can use this to grab the compressed format data and create another animated image instance.
+ If this image instance is an animated image created by using animated image coder (which means using the API listed above or using `initWithAnimatedCoder:scale:`), this property is non-nil.
+ */
+@property (nonatomic, copy, readonly, nullable) NSData *animatedImageData;
+
+/**
+ The scale factor of the image.
+ 
+ @note For UIKit, this just call super instead.
+ @note For AppKit, `NSImage` can contains multiple image representations with different scales. However, this class does not do that from the design. We process the scale like UIKit. This will actually be calculated from image size and pixel size.
+ */
+@property (nonatomic, readonly) CGFloat scale;
+
+// By default, animated image frames are returned by decoding just in time without keeping into memory. But you can choose to preload them into memory as well, See the description in `SDAnimatedImage` protocol.
+// After preloaded, there is no huge difference on performance between this and UIImage's `animatedImageWithImages:duration:`. But UIImage's animation have some issues such like blanking and pausing during segue when using in `UIImageView`. It's recommend to use only if need.
+/**
+ Pre-load all animated image frame into memory. Then later frame image request can directly return the frame for index without decoding.
+ This method may be called on background thread.
+ 
+ @note If one image instance is shared by lots of imageViews, the CPU performance for large animated image will drop down because the request frame index will be random (not in order) and the decoder should take extra effort to keep it re-entrant. You can use this to reduce CPU usage if need. Attention this will consume more memory usage.
+ */
+- (void)preloadAllFrames;
+
+/**
+ Unload all animated image frame from memory if are already pre-loaded. Then later frame image request need decoding. You can use this to free up the memory usage if need.
+ */
+- (void)unloadAllFrames;
+/**
+ Returns a Boolean value indicating whether all animated image frames are already pre-loaded into memory.
+ */
+@property (nonatomic, assign, readonly, getter=isAllFramesLoaded) BOOL allFramesLoaded;
+/**
+ Return the animated image coder if the image is created with `initWithAnimatedCoder:scale:` method.
+ @note We use this with animated coder which conforms to `SDProgressiveImageCoder` for progressive animation decoding.
+ */
+@property (nonatomic, strong, readonly, nullable) id<SDAnimatedImageCoder> animatedCoder;
+
+@end