ImageCache class

Class for caching images.

Implements a least-recently-used cache of up to 1000 images, and up to 100 MB. The maximum size can be adjusted using maximumSize and maximumSizeBytes.

The cache also holds a list of 'live' references. An image is considered live if its ImageStreamCompleter's listener count has never dropped to zero after adding at least one listener. The cache uses ImageStreamCompleter.addOnLastListenerRemovedCallback to determine when this has happened.

The putIfAbsent method is the main entry-point to the cache API. It returns the previously cached ImageStreamCompleter for the given key, if available; if not, it calls the given callback to obtain it first. In either case, the key is moved to the 'most recently used' position.

A caller can determine whether an image is already in the cache by using containsKey, which will return true if the image is tracked by the cache in a pending or completed state. More fine grained information is available by using the statusForKey method.

Generally this class is not used directly. The ImageProvider class and its subclasses automatically handle the caching of images.

A shared instance of this cache is retained by PaintingBinding and can be obtained via the imageCache top-level property in the painting library.

This sample shows how to supply your own caching logic and replace the global imageCache variable.
link
/// This is the custom implementation of [ImageCache] where we can override
/// the logic.
class MyImageCache extends ImageCache {
  @override
  void clear() {
    print('Clearing cache!');
    super.clear();
  }
}

class MyWidgetsBinding extends WidgetsFlutterBinding {
  @override
  ImageCache createImageCache() => MyImageCache();
}

void main() {
  // The constructor sets global variables.
  MyWidgetsBinding();
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return Container();
  }
}

Constructors

ImageCache()

Properties

currentSize int
The current number of cached entries.
no setter
currentSizeBytes int
The current size of cached entries in bytes.
no setter
hashCode int
The hash code for this object.
no setterinherited
liveImageCount int
The number of live images being held by the ImageCache.
no setter
maximumSize int
Maximum number of entries to store in the cache.
getter/setter pair
maximumSizeBytes int
Maximum size of entries to store in the cache in bytes.
getter/setter pair
pendingImageCount int
The number of images being tracked as pending in the ImageCache.
no setter
runtimeType Type
A representation of the runtime type of the object.
no setterinherited

Methods

clear() → void
Evicts all pending and keepAlive entries from the cache.
clearLiveImages() → void
Clears any live references to images in this cache.
containsKey(Object key) bool
Returns whether this key has been previously added by putIfAbsent.
evict(Object key, {bool includeLive = true}) bool
Evicts a single entry from the cache, returning true if successful.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
putIfAbsent(Object key, ImageStreamCompleter loader(), {ImageErrorListener? onError}) ImageStreamCompleter?
Returns the previously cached ImageStream for the given key, if available; if not, calls the given callback to obtain it first. In either case, the key is moved to the 'most recently used' position.
statusForKey(Object key) ImageCacheStatus
The ImageCacheStatus information for the given key.
toString() String
A string representation of this object.
inherited

Operators

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