Image.file constructor

Image.file(
  1. File file, {
  2. Key? key,
  3. double scale = 1.0,
  4. ImageFrameBuilder? frameBuilder,
  5. ImageErrorWidgetBuilder? errorBuilder,
  6. String? semanticLabel,
  7. bool excludeFromSemantics = false,
  8. double? width,
  9. double? height,
  10. Color? color,
  11. Animation<double>? opacity,
  12. BlendMode? colorBlendMode,
  13. BoxFit? fit,
  14. AlignmentGeometry alignment = Alignment.center,
  15. ImageRepeat repeat = ImageRepeat.noRepeat,
  16. Rect? centerSlice,
  17. bool matchTextDirection = false,
  18. bool gaplessPlayback = false,
  19. bool isAntiAlias = false,
  20. FilterQuality filterQuality = FilterQuality.medium,
  21. int? cacheWidth,
  22. int? cacheHeight,
})

Creates a widget that displays an ImageStream obtained from a File.

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).

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.

On Android, this may require the android.permission.READ_EXTERNAL_STORAGE permission.

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, they indicate 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.

Loading an image from a file creates an in memory copy of the file, which is retained in the ImageCache. The underlying file is not monitored for changes. If it does change, the application should evict the entry from the ImageCache.

See also:

  • FileImage provider for evicting the underlying file easily.

Implementation

Image.file(
  File file, {
  super.key,
  double scale = 1.0,
  this.frameBuilder,
  this.errorBuilder,
  this.semanticLabel,
  this.excludeFromSemantics = false,
  this.width,
  this.height,
  this.color,
  this.opacity,
  this.colorBlendMode,
  this.fit,
  this.alignment = Alignment.center,
  this.repeat = ImageRepeat.noRepeat,
  this.centerSlice,
  this.matchTextDirection = false,
  this.gaplessPlayback = false,
  this.isAntiAlias = false,
  this.filterQuality = FilterQuality.medium,
  int? cacheWidth,
  int? cacheHeight,
}) :
     // FileImage is not supported on Flutter Web therefore neither this method.
     assert(
       !kIsWeb,
       'Image.file is not supported on Flutter Web. '
       'Consider using either Image.asset or Image.network instead.',
      ),
     image = ResizeImage.resizeIfNeeded(cacheWidth, cacheHeight, FileImage(file, scale: scale)),
     loadingBuilder = null,
     assert(cacheWidth == null || cacheWidth > 0),
     assert(cacheHeight == null || cacheHeight > 0);