Kingfisher Documentation

Class KF.​Builder

public class Builder  

A builder class to configure an image retrieving task and set it to a holder view or component.

%215 KF.Builder KF.Builder KFOptionSetter KFOptionSetter KF.Builder->KFOptionSetter

Member Of

KF

A helper type to create image setting tasks in a builder pattern. Use methods in this type to create a KF.Builder instance and configure image tasks there.

Conforms To

KFOptionSetter

Properties

options

public var options  

on​Failure​Delegate

public let onFailureDelegate  

on​Success​Delegate

public let onSuccessDelegate  

on​Progress​Delegate

public let onProgressDelegate  

delegate​Observer

public var delegateObserver: AnyObject  

Methods

set(to:​)

@discardableResult
    public func set(to imageView: KFCrossPlatformImageView) -> DownloadTask?  

Builds the image task request and sets it to an image view.

Parameters

image​View KFCross​Platform​Image​View

The image view which loads the task and should be set with the image.

Returns

A task represents the image downloading, if initialized. This value is nil if the image is being loaded from cache.

set(to:​attributed​View:​)

@discardableResult
    public func set(to attachment: NSTextAttachment, attributedView: KFCrossPlatformView) -> DownloadTask?  

Builds the image task request and sets it to an NSTextAttachment object.

Parameters

attachment NSText​Attachment

The text attachment object which loads the task and should be set with the image.

attributed​View KFCross​Platform​View

The owner of the attributed string which this NSTextAttachment is added.

Returns

A task represents the image downloading, if initialized. This value is nil if the image is being loaded from cache.

set(to:​for:​)

@discardableResult
    public func set(to button: UIButton, for state: UIControl.State) -> DownloadTask?  

Builds the image task request and sets it to a button.

Parameters

button UIButton

The button which loads the task and should be set with the image.

state UIControl.​State

The button state to which the image should be set.

Returns

A task represents the image downloading, if initialized. This value is nil if the image is being loaded from cache.

set​Background(to:​for:​)

@discardableResult
    public func setBackground(to button: UIButton, for state: UIControl.State) -> DownloadTask?  

Builds the image task request and sets it to the background image for a button.

Parameters

button UIButton

The button which loads the task and should be set with the image.

state UIControl.​State

The button state to which the image should be set.

Returns

A task represents the image downloading, if initialized. This value is nil if the image is being loaded from cache.

set(to:​)

@discardableResult
    public func set(to button: NSButton) -> DownloadTask?  

Builds the image task request and sets it to a button.

Parameters

button NSButton

The button which loads the task and should be set with the image.

Returns

A task represents the image downloading, if initialized. This value is nil if the image is being loaded from cache.

set​Alternative(to:​)

@discardableResult
    public func setAlternative(to button: NSButton) -> DownloadTask?  

Builds the image task request and sets it to the alternative image for a button.

Parameters

button NSButton

The button which loads the task and should be set with the image.

Returns

A task represents the image downloading, if initialized. This value is nil if the image is being loaded from cache.

set(to:​)

@discardableResult
    public func set(to interfaceImage: WKInterfaceImage) -> DownloadTask?  

Builds the image task request and sets it to a WKInterfaceImage object.

Parameters

interface​Image WKInterface​Image

The watch interface image which loads the task and should be set with the image.

Returns

A task represents the image downloading, if initialized. This value is nil if the image is being loaded from cache.

set(to:​)

@available(tvOS 12.0, *)
    @discardableResult
    public func set(to monogramView: TVMonogramView) -> DownloadTask?  

Builds the image task request and sets it to a TV monogram view.

Parameters

monogram​View TVMonogram​View

The monogram view which loads the task and should be set with the image.

Returns

A task represents the image downloading, if initialized. This value is nil if the image is being loaded from cache.

placeholder(_:​)

public func placeholder(_ placeholder: Placeholder?) -> Self  

Sets a placeholder which is used while retrieving the image.

Parameters

placeholder Placeholder?

A placeholder to show while retrieving the image from its source.

Returns

A KF.Builder with changes applied.

placeholder(_:​)

public func placeholder(_ image: KFCrossPlatformImage?) -> Self  

Sets a placeholder image which is used while retrieving the image.

Parameters

placeholder

An image to show while retrieving the image from its source.

Returns

A KF.Builder with changes applied.

transition(_:​)

public func transition(_ transition: ImageTransition) -> Self  

Sets the transition for the image task.

Kingfisher will use the transition to animate the image in if it is downloaded from web. The transition will not happen when the image is retrieved from either memory or disk cache by default. If you need to do the transition even when the image being retrieved from cache, also call forceRefresh() on the returned KF.Builder.

Parameters

transition Image​Transition

The desired transition effect when setting the image to image view.

Returns

A KF.Builder with changes applied.

fade(duration:​)

public func fade(duration: TimeInterval) -> Self  

Sets a fade transition for the image task.

Kingfisher will use the fade transition to animate the image in if it is downloaded from web. The transition will not happen when the image is retrieved from either memory or disk cache by default. If you need to do the transition even when the image being retrieved from cache, also call forceRefresh() on the returned KF.Builder.

Parameters

duration Time​Interval

The duration of the fade transition.

Returns

A KF.Builder with changes applied.

keep​Current​Image​While​Loading(_:​)

public func keepCurrentImageWhileLoading(_ enabled: Bool = true) -> Self  

Sets whether keeping the existing image of image view while setting another image to it.

By setting this option, the placeholder image parameter of image view extension method will be ignored and the current image will be kept while loading or downloading the new image.

Parameters

enabled Bool

Whether the existing image should be kept.

Returns

A KF.Builder with changes applied.

only​Load​First​Frame(_:​)

public func onlyLoadFirstFrame(_ enabled: Bool = true) -> Self  

Sets whether only the first frame from an animated image file should be loaded as a single image.

Loading an animated images may take too much memory. It will be useful when you want to display a static preview of the first frame from an animated image.

This option will be ignored if the target image is not animated image data.

Parameters

enabled Bool

Whether the only the first frame should be loaded.

Returns

A KF.Builder with changes applied.

on​Failure​Image(_:​)

public func onFailureImage(_ image: KFCrossPlatformImage?) -> Self  

Sets the image that will be used if an image retrieving task fails.

If set and an image retrieving error occurred Kingfisher will set provided image (or empty) in place of requested one. It's useful when you don't want to show placeholder during loading time but wants to use some default image when requests will be failed.

Parameters

image KFCross​Platform​Image?

The image that will be used when something goes wrong.

Returns

A KF.Builder with changes applied.

progressive​JPEG(_:​)

public func progressiveJPEG(_ progressive: ImageProgressive? = .default) -> Self  

Enables progressive image loading with a specified ImageProgressive setting to process the progressive JPEG data and display it in a progressive way.

Parameters

progressive Image​Progressive?

The progressive settings which is used while loading.

Returns

A KF.Builder with changes applied.