ScalableImageWidget.fromSISource constructor

ScalableImageWidget.fromSISource({
  1. Key? key,
  2. required ScalableImageSource si,
  3. BoxFit fit = BoxFit.contain,
  4. Alignment alignment = Alignment.center,
  5. bool clip = true,
  6. double scale = 1,
  7. Color? currentColor,
  8. Color? background,
  9. bool reload = false,
  10. bool isComplex = false,
  11. ScalableImageCache? cache,
  12. Widget onLoading(
    1. BuildContext
    )?,
  13. Widget onError(
    1. BuildContext
    )?,
  14. Widget switcher(
    1. BuildContext,
    2. Widget child
    )?,
})

Create a widget to load and then render a ScalableImage. In a production application, pre-loading the ScalableImage and using the default constructor is usually preferable, because the asynchronous loading that is necessary with an asynchronous source might cause a momentary flash. If the widget is frequently rebuilt, it is generally recommended to provide a cache with an appropriate lifetime and size.

For a discussion of caching and potential reloading, see https://github.com/zathras/jovial_svg/issues/10.

fit controls how the scalable image is scaled within the widget. If fit does not control scaling, then scale is used.

alignment sets the alignment of the scalable image within the widget.

clip, if true, will cause the widget to enforce the boundaries of the scalable image.

cache can used to share ScalableImage instances, and avoid excessive reloading. If null, a default cache that retains no unreferenced images is used.

reload forces the ScalableImage to be reloaded, e.g. if a networking error might have been resolved, or if the asset might have changed.

isComplex see ScalableImageWidget.isComplex

onLoading is called to give a widget to show while the asset is being loaded. It defaults to a 1x1 SizedBox.

onError is called to give a widget to show if the asset has failed loading. It defaults to onLoading.

switcher, if set, is called when switching to a new widget (either from nothing to onLoading, or onLoading to either loaded or onError). A reasonable choice is to create an AnimatedSwitcher. See, for example, example/lib/cache.dart.

currentColor, if provided, sets the ScalableImage.currentColor of the displayed image, using ScalableImage.modifyCurrentColor to create an appropriate ScalableImage instance.

background, if provided, will be the background color for a layer under the SVG asset. In relatively rare circumstances, this can be needed. For example, browsers generally render an SVG over a white background, which affects advanced use of the mix-blend-mode attribute applied over areas without other drawing.

NOTE: If no cache is provided, a default of size zero is used. There is no provision for client code to change the size of this default cache; this is intentional. Having a system-wide cache would invite conflicts in the case where two unrelated modules within a single application attempted to set a cache size. This could even result in a too-large cache retaining large SVG assets, perhaps leading to memory exhaustion. Any module or application that wishes to have a global cache can simply hold one in a static data member, and provide it as the cache parameter to the widgets it manages.

Implementation

factory ScalableImageWidget.fromSISource(
    {Key? key,
    required ScalableImageSource si,
    BoxFit fit = BoxFit.contain,
    Alignment alignment = Alignment.center,
    bool clip = true,
    double scale = 1,
    Color? currentColor,
    Color? background,
    bool reload = false,
    bool isComplex = false,
    ScalableImageCache? cache,
    Widget Function(BuildContext)? onLoading,
    Widget Function(BuildContext)? onError,
    Widget Function(BuildContext, Widget child)? switcher}) {
  onLoading ??= _AsyncSIWidget.defaultOnLoading;
  onError ??= onLoading;
  cache = cache ?? ScalableImageCache._defaultCache;
  if (reload) {
    cache.forceReload(si);
  }
  return _AsyncSIWidget(key, si, fit, alignment, clip, scale, cache,
      onLoading, onError, switcher, currentColor, background, isComplex);
}