FastCachedImage class

FastCachedImage creates a widget to display network images. This widget downloads the network image when this widget is build for the first time. Later whenever this widget is called the image will be displayed from the downloaded database instead of the network. This can avoid unnecessary downloads and load images much faster. Provide the url for the image to display. errorBuilder must return a widget. This widget will be displayed if there is any error in downloading or displaying the downloaded image loadingBuilder must return a widget. This widget is shown when the image is being downloaded and processed fadeInDuration can be adjusted to change the duration of the fade transition between the loadingBuilder and the actual image. Default value is 500 ms. disableErrorLogs can be set to true if you want to ignore error logs from the widget

The underlying widget is Image.memory The scale argument specifies the linear scale factor for drawing this image at its intended size and applies to both the width and the height. For example, if this is 2.0, it means that there are four image pixels for every one logical pixel, and the image's actual width and height (as given by the dart:ui.Image.width and dart:ui.Image.height properties) are double the height and width that should be used when painting the image (e.g. in the arguments given to Canvas.drawImage).

The bytes, scale, and repeat arguments must not be null.

This only accepts compressed image formats (e.g. PNG). Uncompressed formats like rawRgba (the default format of dart:ui.Image.toByteData) will lead to exceptions.

Either the width and height arguments should be specified, or the widget should be placed in a context that sets tight layout constraints. Otherwise, the image dimensions will change as the image is loaded, which will result in ugly layout changes.

Use filterQuality to specify the rendering quality of the image.

If excludeFromSemantics is true, then semanticLabel will be ignored.

If cacheWidth or cacheHeight are provided, it indicates to the engine that the image must be decoded at the specified size. The image will be rendered to the constraints of the layout or width and height regardless of these parameters. These parameters are primarily intended to reduce the memory usage of ImageCache. If non-null, this color is blended with each image pixel using colorBlendMode. If the image is of a high quality and its pixels are perfectly aligned with the physical screen pixels, extra quality enhancement may not be necessary. If so, then FilterQuality.none would be the most efficient.

If the pixels are not perfectly aligned with the screen pixels, or if the image itself is of a low quality, FilterQuality.none may produce undesirable artifacts. Consider using other FilterQuality values to improve the rendered image quality in this case. Pixels may be misaligned with the screen pixels as a result of transforms or scaling. opacity can be used to adjust the opacity of the image. Used to combine color with this image.

The default is BlendMode.srcIn. In terms of the blend mode, color is the source and this image is the destination.

See also:

  • BlendMode, which includes an illustration of the effect of each blend mode. How to inscribe the image into the space allocated during layout.

The default varies based on the other fields. See the discussion at paintImage. How to align the image within its bounds.

The alignment aligns the given position in the image to the given position in the layout bounds. For example, an Alignment alignment of (-1.0, -1.0) aligns the image to the top-left corner of its layout bounds, while an Alignment alignment of (1.0, 1.0) aligns the bottom right of the image with the bottom right corner of its layout bounds. Similarly, an alignment of (0.0, 1.0) aligns the bottom middle of the image with the middle of the bottom edge of its layout bounds.

To display a subpart of an image, consider using a CustomPainter and Canvas.drawImageRect.

If the alignment is TextDirection-dependent (i.e. if it is a AlignmentDirectional), then an ambient Directionality widget must be in scope.

Defaults to Alignment.center.

See also:

  • Alignment, a class with convenient constants typically used to specify an AlignmentGeometry.
  • AlignmentDirectional, like Alignment for specifying alignments relative to text direction. How to paint any portions of the layout bounds not covered by the image. The center slice for a nine-patch image.

The region of the image inside the center slice will be stretched both horizontally and vertically to fit the image into its destination. The region of the image above and below the center slice will be stretched only horizontally and the region of the image to the left and right of the center slice will be stretched only vertically. Whether to paint the image in the direction of the TextDirection.

If this is true, then in TextDirection.ltr contexts, the image will be drawn with its origin in the top left (the "normal" painting direction for images); and in TextDirection.rtl contexts, the image will be drawn with a scaling factor of -1 in the horizontal direction so that the origin is in the top right.

This is occasionally used with images in right-to-left environments, for images that were designed for left-to-right locales. Be careful, when using this, to not flip images with integral shadows, text, or other effects that will look incorrect when flipped.

If this is true, there must be an ambient Directionality widget in scope. Whether to continue showing the old image (true), or briefly show nothing (false), when the image provider changes. The default value is false.

Design discussion

Why is the default value of gaplessPlayback false?

Having the default value of gaplessPlayback be false helps prevent situations where stale or misleading information might be presented. Consider the following case:

We have constructed a 'Person' widget that displays an avatar Image of the currently loaded person along with their name. We could request for a new person to be loaded into the widget at any time. Suppose we have a person currently loaded and the widget loads a new person. What happens if the Image fails to load?

  • Option A (gaplessPlayback = false): The new person's name is coupled with a blank image.

  • Option B (gaplessPlayback = true): The widget displays the avatar of the previous person and the name of the newly loaded person.

This is why the default value is false. Most of the time, when you change the image provider you're not just changing the image, you're removing the old widget and adding a new one and not expecting them to have any relationship. With gaplessPlayback on you might accidentally break this expectation and re-use the old widget. A Semantic description of the image.

Used to provide a description of the image to TalkBack on Android, and VoiceOver on iOS. Whether to exclude this image from semantics.

Useful for images which do not contribute meaningful information to an application. Whether to paint the image with anti-aliasing.

Anti-aliasing alleviates the sawtooth artifact when the image is rotated.

Inheritance

Constructors

FastCachedImage.new({required String url, double scale = 1.0, ImageErrorWidgetBuilder? errorBuilder, String? semanticLabel, Widget loadingBuilder(BuildContext)?, bool excludeFromSemantics = false, bool disableErrorLogs = false, double? width, double? height, Color? color, Animation<double>? opacity, BlendMode? colorBlendMode, BoxFit? fit, AlignmentGeometry alignment = Alignment.center, ImageRepeat repeat = ImageRepeat.noRepeat, Rect? centerSlice, bool matchTextDirection = false, bool gaplessPlayback = false, bool isAntiAlias = false, FilterQuality filterQuality = FilterQuality.low, Duration fadeInDuration = const Duration(milliseconds: 500), int? cacheWidth, int? cacheHeight, Key? key})
const

Properties

alignment → AlignmentGeometry
final
centerSlice → Rect?
final
color → Color?
final
colorBlendMode → BlendMode?
final
disableErrorLogs → bool
final
errorBuilder → ImageErrorWidgetBuilder?
final
excludeFromSemantics → bool
final
fadeInDuration → Duration
final
filterQuality → FilterQuality
final
fit → BoxFit?
final
gaplessPlayback → bool
final
hashCode → int
The hash code for this object.
no setterinherited
height → double?
final
isAntiAlias → bool
final
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
loadingBuilder → Widget Function(BuildContext)?
final
matchTextDirection → bool
final
opacity → Animation<double>?
final
repeat → ImageRepeat
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
scale → double
final
semanticLabel → String?
final
url → String
final
width → double?
final

Methods

createElement() → StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<FastCachedImage>
Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String
Returns a one-line detailed description of the object.
inherited
toStringShort() → String
A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited