KingfisherWrapper

public struct KingfisherWrapper<Base>

Wrapper for Kingfisher compatible types. This type provides an extension point for connivence methods in Kingfisher.

Setting Image

  • Sets an image to the image view with a Source.

    Note

    This is the easiest way to use Kingfisher to boost the image setting process from a source. Since all parameters have a default value except the source, you can set an image from a certain URL to an image view like this:

    // Set image from a network source.
    let url = URL(string: "https://example.com/image.png")!
    imageView.kf.setImage(with: .network(url))
    
    // Or set image from a data provider.
    let provider = LocalFileImageDataProvider(fileURL: fileURL)
    imageView.kf.setImage(with: .provider(provider))
    

    For both .network and .provider source, there are corresponding view extension methods. So the code above is equivalent to:

    imageView.kf.setImage(with: url)
    imageView.kf.setImage(with: provider)
    

    Internally, this method will use KingfisherManager to get the source. Since this method will perform UI changes, you must call it from the main thread. Both progressBlock and completionHandler will be also executed in the main thread.

    Declaration

    Swift

    @discardableResult
    public func setImage(
        with source: Source?,
        placeholder: Placeholder? = nil,
        options: KingfisherOptionsInfo? = nil,
        progressBlock: DownloadProgressBlock? = nil,
        completionHandler: ((Result<RetrieveImageResult, KingfisherError>) -> Void)? = nil) -> DownloadTask?

    Parameters

    source

    The Source object defines data information from network or a data provider.

    placeholder

    A placeholder to show while retrieving the image from the given resource.

    options

    An options set to define image setting behaviors. See KingfisherOptionsInfo for more.

    progressBlock

    Called when the image downloading progress gets updated. If the response does not contain an expectedContentLength, this block will not be called.

    completionHandler

    Called when the image retrieved and set finished.

    Return Value

    A task represents the image downloading.

  • Sets an image to the image view with a requested resource.

    Note

    This is the easiest way to use Kingfisher to boost the image setting process from network. Since all parameters have a default value except the resource, you can set an image from a certain URL to an image view like this:

    let url = URL(string: "https://example.com/image.png")!
    imageView.kf.setImage(with: url)
    

    Internally, this method will use KingfisherManager to get the requested resource, from either cache or network. Since this method will perform UI changes, you must call it from the main thread. Both progressBlock and completionHandler will be also executed in the main thread.

    Declaration

    Swift

    @discardableResult
    public func setImage(
        with resource: Resource?,
        placeholder: Placeholder? = nil,
        options: KingfisherOptionsInfo? = nil,
        progressBlock: DownloadProgressBlock? = nil,
        completionHandler: ((Result<RetrieveImageResult, KingfisherError>) -> Void)? = nil) -> DownloadTask?

    Parameters

    resource

    The Resource object contains information about the resource.

    placeholder

    A placeholder to show while retrieving the image from the given resource.

    options

    An options set to define image setting behaviors. See KingfisherOptionsInfo for more.

    progressBlock

    Called when the image downloading progress gets updated. If the response does not contain an expectedContentLength, this block will not be called.

    completionHandler

    Called when the image retrieved and set finished.

    Return Value

    A task represents the image downloading.

  • Sets an image to the image view with a data provider.

    Internally, this method will use KingfisherManager to get the image data, from either cache or the data provider. Since this method will perform UI changes, you must call it from the main thread. Both progressBlock and completionHandler will be also executed in the main thread.

    Declaration

    Swift

    @discardableResult
    public func setImage(
        with provider: ImageDataProvider?,
        placeholder: Placeholder? = nil,
        options: KingfisherOptionsInfo? = nil,
        progressBlock: DownloadProgressBlock? = nil,
        completionHandler: ((Result<RetrieveImageResult, KingfisherError>) -> Void)? = nil) -> DownloadTask?

    Parameters

    provider

    The ImageDataProvider object contains information about the data.

    placeholder

    A placeholder to show while retrieving the image from the given resource.

    options

    An options set to define image setting behaviors. See KingfisherOptionsInfo for more.

    progressBlock

    Called when the image downloading progress gets updated. If the response does not contain an expectedContentLength, this block will not be called.

    completionHandler

    Called when the image retrieved and set finished.

    Return Value

    A task represents the image downloading.

Cancelling Downloading Task

  • Cancels the image download task of the image view if it is running. Nothing will happen if the downloading has already finished.

    Declaration

    Swift

    public func cancelDownloadTask()

Properties

Available where Base: KFCrossPlatformImageView

  • Gets the image URL bound to this image view.

    Declaration

    Swift

    @available(*, deprecated, message: "Use `taskIdentifier` instead to identify a setting task.")
    public private(set) var webURL: URL? { get set }

Setting Image

  • Sets an image to the button with a source.

    Note

    Internally, this method will use KingfisherManager to get the requested source. Since this method will perform UI changes, you must call it from the main thread. Both progressBlock and completionHandler will be also executed in the main thread.

    Declaration

    Swift

    @discardableResult
    public func setImage(
        with source: Source?,
        placeholder: KFCrossPlatformImage? = nil,
        options: KingfisherOptionsInfo? = nil,
        progressBlock: DownloadProgressBlock? = nil,
        completionHandler: ((Result<RetrieveImageResult, KingfisherError>) -> Void)? = nil) -> DownloadTask?

    Parameters

    source

    The Source object contains information about how to get the image.

    placeholder

    A placeholder to show while retrieving the image from the given resource.

    options

    An options set to define image setting behaviors. See KingfisherOptionsInfo for more.

    progressBlock

    Called when the image downloading progress gets updated. If the response does not contain an expectedContentLength, this block will not be called.

    completionHandler

    Called when the image retrieved and set finished.

    Return Value

    A task represents the image downloading.

  • Sets an image to the button with a requested resource.

    Note

    Internally, this method will use KingfisherManager to get the requested resource, from either cache or network. Since this method will perform UI changes, you must call it from the main thread. Both progressBlock and completionHandler will be also executed in the main thread.

    Declaration

    Swift

    @discardableResult
    public func setImage(
        with resource: Resource?,
        placeholder: KFCrossPlatformImage? = nil,
        options: KingfisherOptionsInfo? = nil,
        progressBlock: DownloadProgressBlock? = nil,
        completionHandler: ((Result<RetrieveImageResult, KingfisherError>) -> Void)? = nil) -> DownloadTask?

    Parameters

    resource

    The Resource object contains information about the resource.

    placeholder

    A placeholder to show while retrieving the image from the given resource.

    options

    An options set to define image setting behaviors. See KingfisherOptionsInfo for more.

    progressBlock

    Called when the image downloading progress gets updated. If the response does not contain an expectedContentLength, this block will not be called.

    completionHandler

    Called when the image retrieved and set finished.

    Return Value

    A task represents the image downloading.

Cancelling Downloading Task

  • Cancels the image download task of the button if it is running. Nothing will happen if the downloading has already finished.

    Declaration

    Swift

    public func cancelImageDownloadTask()

Setting Alternate Image

Cancelling Alternate Image Downloading Task

  • Cancels the alternate image download task of the button if it is running. Nothing will happen if the downloading has already finished.

    Declaration

    Swift

    public func cancelAlternateImageDownloadTask()

Properties

Available where Base: NSButton

  • Gets the image URL bound to this button.

    Declaration

    Swift

    @available(*, deprecated, message: "Use `taskIdentifier` instead to identify a setting task.")
    public private(set) var webURL: URL? { get set }
  • Gets the image URL bound to this button.

    Declaration

    Swift

    @available(*, deprecated, message: "Use `alternateTaskIdentifier` instead to identify a setting task.")
    public private(set) var alternateWebURL: URL? { get set }

Available where Base: KFCrossPlatformImage

Available where Base: KFCrossPlatformImageView

Available where Base: NSButton

Available where Base: KFCrossPlatformImage

  • Applies a Filter containing CIImage transformer to self.

    Note

    Only CG-based images are supported. If any error happens during transforming, self will be returned.

    Declaration

    Swift

    public func apply(_ filter: Filter) -> KFCrossPlatformImage

    Parameters

    filter

    The filter used to transform self.

    Return Value

    A transformed image by input Filter.

  • Normalize the image. This getter does nothing on macOS but return the image itself.

    Declaration

    Swift

    public var normalized: KFCrossPlatformImage { get }
  • Returns normalized image for current base image. This method will try to redraw an image with orientation and scale considered.

  • Returns PNG representation of base image.

    Declaration

    Swift

    public func pngRepresentation() -> Data?

    Return Value

    PNG data of image.

  • Returns JPEG representation of base image.

    Declaration

    Swift

    public func jpegRepresentation(compressionQuality: CGFloat) -> Data?

    Parameters

    compressionQuality

    The compression quality when converting image to JPEG data.

    Return Value

    JPEG data of image.

  • Returns GIF representation of base image.

    Declaration

    Swift

    public func gifRepresentation() -> Data?

    Return Value

    Original GIF data of image.

  • Returns a data representation for base image, with the format as the format indicator.

    Declaration

    Swift

    public func data(format: ImageFormat, compressionQuality: CGFloat = 1.0) -> Data?

    Parameters

    format

    The format in which the output data should be. If unknown, the base image will be converted in the PNG representation.

    compressionQuality

    The compression quality when converting image to a lossy format data.

    format

    The format in which the output data should be. If unknown, the base image will be converted in the PNG representation.

    Return Value

    The output data representing. Returns a data representation for base image, with the format as the format indicator.

  • Creates an animated image from a given data and options. Currently only GIF data is supported.

    Declaration

    Swift

    public static func animatedImage(data: Data, options: ImageCreatingOptions) -> KFCrossPlatformImage?

    Parameters

    data

    The animated image data.

    options

    Options to use when creating the animated image.

    Return Value

    An Image object represents the animated image. It is in form of an array of image frames with a certain duration. nil if anything wrong when creating animated image.

  • Creates an image from a given data and options. .JPEG, .PNG or .GIF is supported. For other image format, image initializer from system will be used. If no image object could be created from the given data, nil will be returned.

    Declaration

    Swift

    public static func image(data: Data, options: ImageCreatingOptions) -> KFCrossPlatformImage?

    Parameters

    data

    The image data representation.

    options

    Options to use when creating the image.

    Return Value

    An Image object represents the image if created. If the data is invalid or not supported, nil will be returned.

  • Creates a downsampled image from given data to a certain size and scale.

    Note

    Different from image resize methods, downsampling will not render the original input image in pixel format. It does downsampling from the image data, so it is much more memory efficient and friendly. Choose to use downsampling as possible as you can.

    The input size should be smaller than the size of input image. If it is larger than the original image size, the result image will be the same size of input without downsampling.

    Declaration

    Swift

    public static func downsampledImage(data: Data, to pointSize: CGSize, scale: CGFloat) -> KFCrossPlatformImage?

    Parameters

    data

    The image data contains a JPEG or PNG image.

    pointSize

    The target size in point to which the image should be downsampled.

    scale

    The scale of result image.

    Return Value

    A downsampled Image object following the input conditions.

Blend Mode

Compositing

  • Creates image from base image and apply compositing operation.

    Note

    This method only works for CG-based image. For any non-CG-based image, base itself is returned.

    Declaration

    Swift

    public func image(withCompositingOperation compositingOperation: NSCompositingOperation,
                      alpha: CGFloat = 1.0,
                      backgroundColor: KFCrossPlatformColor? = nil) -> KFCrossPlatformImage

    Parameters

    compositingOperation

    The compositing operation of creating image.

    alpha

    The alpha should be used for image.

    backgroundColor

    The background color for the output image.

    Return Value

    An image with compositing operation applied.

Round Corner

  • Creates a round corner image from on base image.

    Note

    This method only works for CG-based image. The current image scale is kept. For any non-CG-based image, base itself is returned.

    Declaration

    Swift

    public func image(withRoundRadius radius: CGFloat,
                      fit size: CGSize,
                      roundingCorners corners: RectCorner = .all,
                      backgroundColor: KFCrossPlatformColor? = nil) -> KFCrossPlatformImage

    Parameters

    radius

    The round corner radius of creating image.

    size

    The target size of creating image.

    corners

    The target corners which will be applied rounding.

    backgroundColor

    The background color for the output image

    Return Value

    An image with round corner of self.

Resizing

  • Resizes base image to an image with new size.

    Note

    This method only works for CG-based image. The current image scale is kept. For any non-CG-based image, base itself is returned.

    Declaration

    Swift

    public func resize(to size: CGSize) -> KFCrossPlatformImage

    Parameters

    size

    The target size in point.

    Return Value

    An image with new size.

  • Resizes base image to an image of new size, respecting the given content mode.

    Note

    This method only works for CG-based image. The current image scale is kept. For any non-CG-based image, base itself is returned.

    Declaration

    Swift

    public func resize(to targetSize: CGSize, for contentMode: ContentMode) -> KFCrossPlatformImage

    Parameters

    targetSize

    The target size in point.

    contentMode

    Content mode of output image should be.

    Return Value

    An image with new size.

Cropping

  • Crops base image to a new size with a given anchor.

    Note

    This method only works for CG-based image. The current image scale is kept. For any non-CG-based image, base itself is returned.

    Declaration

    Swift

    public func crop(to size: CGSize, anchorOn anchor: CGPoint) -> KFCrossPlatformImage

    Parameters

    size

    The target size.

    anchor

    The anchor point from which the size should be calculated.

    Return Value

    An image with new size.

Blur

  • Creates an image with blur effect based on base image.

    Note

    This method only works for CG-based image. The current image scale is kept. For any non-CG-based image, base itself is returned.

    Declaration

    Swift

    public func blurred(withRadius radius: CGFloat) -> KFCrossPlatformImage

    Parameters

    radius

    The blur radius should be used when creating blur effect.

    Return Value

    An image with blur effect applied.

Overlay

  • Creates an image from base image with a color overlay layer.

    Note

    This method only works for CG-based image. The current image scale is kept. For any non-CG-based image, base itself is returned.

    Declaration

    Swift

    public func overlaying(with color: KFCrossPlatformColor, fraction: CGFloat) -> KFCrossPlatformImage

    Parameters

    color

    The color should be use to overlay.

    fraction

    Fraction of input color. From 0.0 to 1.0. 0.0 means solid color, 1.0 means transparent overlay.

    Return Value

    An image with a color overlay applied.

Tint

Color Control

  • Create an image from self with color control.

    Declaration

    Swift

    public func adjusted(brightness: CGFloat, contrast: CGFloat, saturation: CGFloat, inputEV: CGFloat) -> KFCrossPlatformImage

    Parameters

    brightness

    Brightness changing to image.

    contrast

    Contrast changing to image.

    saturation

    Saturation changing to image.

    inputEV

    InputEV changing to image.

    Return Value

    An image with color control applied.

  • Return an image with given scale.

    Declaration

    Swift

    public func scaled(to scale: CGFloat) -> KFCrossPlatformImage

    Parameters

    scale

    Target scale factor the new image should have.

    Return Value

    The image with target scale. If the base image is already in the scale, base will be returned.

Available where Base: KFCrossPlatformImage

  • Returns the decoded image of the base image. It will draw the image in a plain context and return the data from it. This could improve the drawing performance when an image is just created from data but not yet displayed for the first time.

    Note

    This method only works for CG-based image. The current image scale is kept. For any non-CG-based image or animated image, base itself is returned.

    Declaration

    Swift

    public var decoded: KFCrossPlatformImage { get }
  • Returns decoded image of the base image at a given scale. It will draw the image in a plain context and return the data from it. This could improve the drawing performance when an image is just created from data but not yet displayed for the first time.

    Note

    This method only works for CG-based image. The current image scale is kept. For any non-CG-based image or animated image, base itself is returned.

    Declaration

    Swift

    public func decoded(scale: CGFloat) -> KFCrossPlatformImage

    Parameters

    scale

    The given scale of target image should be.

    Return Value

    The decoded image ready to be displayed.

Available where Base == Data

Available where Base == CGSize

  • Returns a size by resizing the base size to a target size under a given content mode.

    Declaration

    Swift

    public func resize(to size: CGSize, for contentMode: ContentMode) -> CGSize

    Parameters

    size

    The target size to resize to.

    contentMode

    Content mode of the target size should be when resizing.

    Return Value

    The resized size under the given ContentMode.

  • Returns a size by resizing the base size by making it aspect fitting the given size.

    Declaration

    Swift

    public func constrained(_ size: CGSize) -> CGSize

    Parameters

    size

    The size in which the base should fit in.

    Return Value

    The size fitted in by the input size, while keeps base aspect.

  • Returns a size by resizing the base size by making it aspect filling the given size.

    Declaration

    Swift

    public func filling(_ size: CGSize) -> CGSize

    Parameters

    size

    The size in which the base should fill.

    Return Value

    The size be filled by the input size, while keeps base aspect.

  • Returns a CGRect for which the base size is constrained to an input size at a given anchor point.

    Declaration

    Swift

    public func constrainedRect(for size: CGSize, anchor: CGPoint) -> CGRect

    Parameters

    size

    The size in which the base should be constrained to.

    anchor

    An anchor point in which the size constraint should happen.

    Return Value

    The result CGRect for the constraint operation.