PictureProvider<T, U> class abstract

Identifies a picture without committing to the precise final asset. This allows a set of pictures to be identified and for the precise picture to later be resolved based on the environment, e.g. the device pixel ratio.

To obtain an PictureStream from an PictureProvider, call resolve, passing it an PictureConfiguration object.

PictureProvider uses the global pictureCache to cache pictures.

The type argument T is the type of the object used to represent a resolved configuration. This is also the type used for the key in the picture cache. It should be immutable and implement the == operator and the hashCode getter. Subclasses should subclass a variant of PictureProvider with an explicit T type argument.

The type argument does not have to be specified when using the type as an argument (where any Picture provider is acceptable).

The following picture formats are supported:

Sample code

The following shows the code required to write a widget that fully conforms to the PictureProvider and Widget protocols. (It is essentially a bare-bones version of the widgets.Picture widget.)

class MyPicture extends StatefulWidget {
  const MyPicture({
    Key key,
    @required this.PictureProvider,
  }) : assert(PictureProvider != null),
       super(key: key);

  final PictureProvider PictureProvider;

  @override
  _MyPictureState createState() => _MyPictureState();
}

class _MyPictureState extends State<MyPicture> {
  PictureStream _PictureStream;
  PictureInfo _pictureInfo;

  @override
  void didChangeDependencies() {
    super.didChangeDependencies();
    // We call _getPicture here because createLocalPictureConfiguration() needs to
    // be called again if the dependencies changed, in case the changes relate
    // to the DefaultAssetBundle, MediaQuery, etc, which that method uses.
    _getPicture();
  }

  @override
  void didUpdateWidget(MyPicture oldWidget) {
    super.didUpdateWidget(oldWidget);
    if (widget.PictureProvider != oldWidget.PictureProvider)
      _getPicture();
  }

  void _getPicture() {
    final PictureStream oldPictureStream = _PictureStream;
    _PictureStream = widget.PictureProvider.resolve(createLocalPictureConfiguration(context));
    if (_PictureStream.key != oldPictureStream?.key) {
      // If the keys are the same, then we got the same picture back, and so we don't
      // need to update the listeners. If the key changed, though, we must make sure
      // to switch our listeners to the new picture stream.
      oldPictureStream?.removeListener(_updatePicture);
      _PictureStream.addListener(_updatePicture);
    }
  }

  void _updatePicture(PictureInfo pictureInfo, bool synchronousCall) {
    setState(() {
      // Trigger a build whenever the picture changes.
      _pictureInfo = pictureInfo;
    });
  }

  @override
  void dispose() {
    _PictureStream.removeListener(_updatePicture);
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return RawPicture(
      picture: _pictureInfo?.picture, // this is a dart:ui Picture object
      scale: _pictureInfo?.scale ?? 1.0,
    );
  }
}

Implementers

Annotations

@optionalTypeArgs

Constructors

PictureProvider(ColorFilter? colorFilter, {required PictureInfoDecoderBuilder<U> decoderBuilder}): Abstract const constructor. This constructor enables subclasses to provide const constructors so that they can be used in const expressions.

Properties

colorFilter → ColorFilter?: The color filter to apply to the picture, if any.
final
decoder ↔ PictureInfoDecoder<U>: The PictureInfoDecoder to use for loading this picture.
getter/setter pair
decoderBuilder → PictureInfoDecoderBuilder<U>: The decoder builder to build a decoder when theme changes.
final
hashCode → int: The hash code for this object.
no setterinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
theme ↔ SvgTheme: The default theme used when parsing SVG elements.
getter/setter pair

Methods

load(T key, {PictureErrorListener? onError}) → PictureStreamCompleter: Converts a key into an PictureStreamCompleter, and begins fetching the picture.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
obtainKey(PictureConfiguration picture) → Future<T>: Converts a pictureProvider's settings plus a pictureConfiguration to a key that describes the precise picture to load.
resolve(PictureConfiguration picture, {PictureErrorListener? onError}) → PictureStream: Resolves this Picture provider using the given configuration, returning an PictureStream.
toString() → String: A string representation of this object.
override

Operators

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

Static Properties

cache → PictureCache: The PictureCache for Picture objects created by PictureProvider implementations.
final
cacheCount → int: The number of items in the cache.
no setter

Static Methods

clearCache() → void: Clears the cache.