ImageCache and ImageProvider changes

ImageCache now has a method called containsKey. ImageProvider subclasses should not override resolve, but instead should implement new methods on ImageProvider. These changes were submitted as a single commit to the framework.

The sections below describe the changes to containsKey and ImageProvider.

Clients of the ImageCache, such as a custom ImageProvider, may want to know if the cache is already tracking an image. Adding the containsKey method allows callers to discover this without calling a method like putIfAbsent, which can trigger an undesired call to ImageProvider.load.

The default implementation checks both pending and cached image buckets.

  bool containsKey(Object key) {
    return _pendingImages[key] != null || _cache[key] != null;
  }

The ImageProvider.resolve method does some complicated error handling work that should not normally be overridden. It also previously did work to load the image into the image cache, by way of ImageProvider.obtainKey and ImageProvider.load. Subclasses had no opportunity to override this behavior without overriding resolve, and the ability to compose ImageProviders is limited if multiple ImageProviders expect to override resolve.

To solve this issue, resolve is now marked as non-virtual, and two new protected methods have been added: createStream() and resolveStreamForKey(). These methods allow subclasses to control most of the behavior of resolve, without having to duplicate all the error handling work. It also allows subclasses that compose ImageProviders to be more confident that there is only one public entrypoint to the various chained providers.

Before migration, the code would not have an override of containsKey.

Code after migration:

class MyImageCache implements ImageCache {
  @override
  bool containsKey(Object key) {
    // Check if your custom cache is tracking this key.
  }

  ...
}

Code before the migration:

class MyImageProvider extends ImageProvider<Object> {
  @override
  ImageStream resolve(ImageConfiguration configuration) {
    // create stream
    // set up error handling
    // interact with ImageCache
    // call obtainKey/load, etc.
  }
  ...
}

Code after the migration:

class MyImageProvider extends ImageProvider<Object> {
  @override
  ImageStream createStream(ImageConfiguration configuration) {
    // Return stream, or use super.createStream(),
    // which returns a new ImageStream.
  }

  @override
  void resolveStreamForKey(
    ImageConfiguration configuration,
    ImageStream stream,
    Object key,
    ImageErrorListener handleError,
  ) {
    // Interact with the cache, use the key, potentially call `load`,
    // and report any errors back through `handleError`.
  }
  ...
}

Landed in version: 1.16.3
In stable release: 1.17

API documentation:

• ImageCache
• ImageProvider
• ScrollAwareImageProvider

Relevant issues:

• Issue #32143
• Issue #44510
• Issue #48305
• Issue #48775

Relevant PRs:

• Defer image decoding when scrolling fast #49389