ExtendedImage.asset constructor

ExtendedImage.asset(String name, { Key? key, AssetBundle? bundle, String? semanticLabel, bool excludeFromSemantics = false, double? scale, 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, String? package, FilterQuality filterQuality = FilterQuality.low, LoadStateChanged? loadStateChanged, BoxShape? shape, BoxBorder? border, BorderRadius? borderRadius, Clip clipBehavior = Clip.antiAlias, bool enableLoadState = false, BeforePaintImage? beforePaintImage, AfterPaintImage? afterPaintImage, ExtendedImageMode mode = ExtendedImageMode.none, bool enableMemoryCache = true, bool clearMemoryCacheIfFailed = true, DoubleTap? onDoubleTap, InitGestureConfigHandler? initGestureConfigHandler, bool enableSlideOutPage = false, BoxConstraints? constraints, Key? extendedImageEditorKey, InitEditorConfigHandler? initEditorConfigHandler, HeroBuilderForSlidingPage? heroBuilderForSlidingPage, bool clearMemoryCacheWhenDispose = false, Key? extendedImageGestureKey, int? cacheWidth, int? cacheHeight, bool isAntiAlias = false, double? compressionRatio, int? maxBytes, bool cacheRawData = false, String? imageCacheName, EdgeInsets layoutInsets = EdgeInsets.zero, })

Creates a widget that displays an ImageStream obtained from an asset bundle. The key for the image is given by the name argument.

The package argument must be non-null when displaying an image from a package and null otherwise. See the Assets in packages section for details.

If the bundle argument is omitted or null, then the DefaultAssetBundle will be used.

By default, the pixel-density-aware asset resolution will be attempted. In addition:

• If the scale argument is provided and is not null, then the exact asset specified will be used. To display an image variant with a specific density, the exact path must be provided (e.g. images/2x/cat.png).

If excludeFromSemantics is true, then semanticLabel will be ignored.

The name and repeat arguments must not be null.

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 change the quality when scaling an image. Use the FilterQuality.low quality setting to scale the image, which corresponds to bilinear interpolation, rather than the default FilterQuality.none which corresponds to nearest-neighbor.

{@tool sample}

Suppose that the project's pubspec.yaml file contains the following:

flutter:
  assets:
    - images/cat.png
    - images/2x/cat.png
    - images/3.5x/cat.png

{@end-tool}

On a screen with a device pixel ratio of 2.0, the following widget would render the images/2x/cat.png file:

Image.asset('images/cat.png')

This corresponds to the file that is in the project's images/2x/ directory with the name cat.png (the paths are relative to the pubspec.yaml file).

On a device with a 4.0 device pixel ratio, the images/3.5x/cat.png asset would be used. On a device with a 1.0 device pixel ratio, the images/cat.png resource would be used.

The images/cat.png image can be omitted from disk (though it must still be present in the manifest). If it is omitted, then on a device with a 1.0 device pixel ratio, the images/2x/cat.png image would be used instead.

Assets in packages

To create the widget with an asset from a package, the package argument must be provided. For instance, suppose a package called my_icons has icons/heart.png .

{@tool sample} Then to display the image, use:

Image.asset('icons/heart.png', package: 'my_icons')

{@end-tool}

Assets used by the package itself should also be displayed using the package argument as above.

If the desired asset is specified in the pubspec.yaml of the package, it is bundled automatically with the app. In particular, assets used by the package itself must be specified in its pubspec.yaml.

A package can also choose to have assets in its 'lib/' folder that are not specified in its pubspec.yaml. In this case for those images to be bundled, the app has to specify which ones to include. For instance a package named fancy_backgrounds could have:

lib/backgrounds/background1.png
lib/backgrounds/background2.png
lib/backgrounds/background3.png

To include, say the first image, the pubspec.yaml of the app should specify it in the assets section:

 assets:
   - packages/fancy_backgrounds/backgrounds/background1.png

The lib/ is implied, so it should not be included in the asset path.

See also:

• AssetImage, which is used to implement the behavior when the scale is omitted.
• ExactAssetImage, which is used to implement the behavior when the scale is present.
• flutter.io/assets-and-images/, an introduction to assets in Flutter.

Implementation

//
//
// ///
// /// * If [width] and [height] are both specified, and [scale] is not, then
// ///   size-aware asset resolution will be attempted also, with the given
// ///   dimensions interpreted as logical pixels.
// ///
// /// * If the images have platform, locale, or directionality variants, the
// ///   current platform, locale, and directionality are taken into account
// ///   during asset resolution as well.
///
/// The [name] and [repeat] arguments must not be null.
///
/// 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 change the quality when scaling an image.
/// Use the [FilterQuality.low] quality setting to scale the image,
/// which corresponds to bilinear interpolation, rather than the default
/// [FilterQuality.none] which corresponds to nearest-neighbor.
///
/// {@tool sample}
///
/// Suppose that the project's `pubspec.yaml` file contains the following:
///
/// ```yaml
/// flutter:
///   assets:
///     - images/cat.png
///     - images/2x/cat.png
///     - images/3.5x/cat.png
/// ```
/// {@end-tool}
///
/// On a screen with a device pixel ratio of 2.0, the following widget would
/// render the `images/2x/cat.png` file:
///
/// ```dart
/// Image.asset('images/cat.png')
/// ```
///
/// This corresponds to the file that is in the project's `images/2x/`
/// directory with the name `cat.png` (the paths are relative to the
/// `pubspec.yaml` file).
///
/// On a device with a 4.0 device pixel ratio, the `images/3.5x/cat.png` asset
/// would be used. On a device with a 1.0 device pixel ratio, the
/// `images/cat.png` resource would be used.
///
/// The `images/cat.png` image can be omitted from disk (though it must still
/// be present in the manifest). If it is omitted, then on a device with a 1.0
/// device pixel ratio, the `images/2x/cat.png` image would be used instead.
///
///
/// ## Assets in packages
///
/// To create the widget with an asset from a package, the [package] argument
/// must be provided. For instance, suppose a package called `my_icons` has
/// `icons/heart.png` .
///
/// {@tool sample}
/// Then to display the image, use:
///
/// ```dart
/// Image.asset('icons/heart.png', package: 'my_icons')
/// ```
/// {@end-tool}
///
/// Assets used by the package itself should also be displayed using the
/// [package] argument as above.
///
/// If the desired asset is specified in the `pubspec.yaml` of the package, it
/// is bundled automatically with the app. In particular, assets used by the
/// package itself must be specified in its `pubspec.yaml`.
///
/// A package can also choose to have assets in its 'lib/' folder that are not
/// specified in its `pubspec.yaml`. In this case for those images to be
/// bundled, the app has to specify which ones to include. For instance a
/// package named `fancy_backgrounds` could have:
///
/// ```
/// lib/backgrounds/background1.png
/// lib/backgrounds/background2.png
/// lib/backgrounds/background3.png
/// ```
///
/// To include, say the first image, the `pubspec.yaml` of the app should
/// specify it in the assets section:
///
/// ```yaml
///  assets:
///    - packages/fancy_backgrounds/backgrounds/background1.png
/// ```
///
/// The `lib/` is implied, so it should not be included in the asset path.
///
///
/// See also:
///
///  * [AssetImage], which is used to implement the behavior when the scale is
///    omitted.
///  * [ExactAssetImage], which is used to implement the behavior when the
///    scale is present.
///  * <https://flutter.io/assets-and-images/>, an introduction to assets in
///    Flutter.
ExtendedImage.asset(
  String name, {
  Key? key,
  AssetBundle? bundle,
  this.semanticLabel,
  this.excludeFromSemantics = false,
  double? scale,
  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,
  String? package,
  this.filterQuality = FilterQuality.low,
  this.loadStateChanged,
  this.shape,
  this.border,
  this.borderRadius,
  this.clipBehavior = Clip.antiAlias,
  this.enableLoadState = false,
  this.beforePaintImage,
  this.afterPaintImage,
  this.mode = ExtendedImageMode.none,
  this.enableMemoryCache = true,
  this.clearMemoryCacheIfFailed = true,
  this.onDoubleTap,
  this.initGestureConfigHandler,
  this.enableSlideOutPage = false,
  BoxConstraints? constraints,
  this.extendedImageEditorKey,
  this.initEditorConfigHandler,
  this.heroBuilderForSlidingPage,
  this.clearMemoryCacheWhenDispose = false,
  this.extendedImageGestureKey,
  int? cacheWidth,
  int? cacheHeight,
  this.isAntiAlias = false,
  double? compressionRatio,
  int? maxBytes,
  bool cacheRawData = false,
  String? imageCacheName,
  this.layoutInsets = EdgeInsets.zero,
})  : assert(cacheWidth == null || cacheWidth > 0),
      assert(cacheHeight == null || cacheHeight > 0),
      image = ExtendedResizeImage.resizeIfNeeded(
        provider: scale != null
            ? ExtendedExactAssetImageProvider(
                name,
                bundle: bundle,
                scale: scale,
                package: package,
                cacheRawData: cacheRawData,
                imageCacheName: imageCacheName,
              )
            : ExtendedAssetImageProvider(
                name,
                bundle: bundle,
                package: package,
                cacheRawData: cacheRawData,
                imageCacheName: imageCacheName,
              ),
        compressionRatio: compressionRatio,
        maxBytes: maxBytes,
        cacheWidth: cacheWidth,
        cacheHeight: cacheHeight,
        cacheRawData: cacheRawData,
        imageCacheName: imageCacheName,
      ),
      constraints = (width != null || height != null)
          ? constraints?.tighten(width: width, height: height) ??
              BoxConstraints.tightFor(width: width, height: height)
          : constraints,
      handleLoadingProgress = false,
      super(key: key);