Ability to display loading progress of an image #32374

class ImageChunkEvent {
  /// The number of bytes that have been loaded thus far.
  final int bytesLoaded;

  /// The number of bytes that are expected to have been
  /// loaded when the image is fully loaded.
  ///
  /// This value will be `null` if the total number of bytes
  /// is unknown.
  final int totalBytes;
}

/// Signature for callbacks reporting that an image has reached an
/// incremental step towards being fully loaded.
///
/// Used by [ImageStream].
///
/// The `event` specifies the progress towards fully loading the image.
typedef ImageChunkListener = void Function(ImageChunkEvent event);

class ImageStream extends Diagnosticable {
  /// ...
  ///
  /// An [ImageChunkListener] can also optionally be added
  /// along with the `listener`. If the stream produces images
  /// that are loaded in chunks, then the specified listener will
  /// be notified for every chunk of data that is loaded (e.g. over
  /// the file system or the network).
  void addListener(
    ImageListener listener, {
    ImageChunkListener chunkListener,
    ImageErrorListener onError,
  });
}

/// Signature for callbacks used to build a widget to display
/// while an image is loading (e.g. from the local file system
/// or the network).
///
/// This will be called to build a new widget for every
/// [ImageChunkEvent] that fires during image loading (see
/// [ImageChunkListener]).
///
/// For single-frame images, once the image loads, the
/// image chunk events will stop firing, the image provider's
/// stream will yield a completed [ImageInfo] object, and this
/// builder will not be consulted anymore.  For these cases,
/// the `currentRawImage` parameter will be `null`.
///
/// For multi-frame images, it's possible that image chunk
/// events will continue to fire after the first image frame has
/// loaded.  In that case, the `currentRawImage` parameter
/// will be set to the widget representing the current
/// fully-loaded image frame that is about to be replaced.
/// This allows callers the ability to overlay a loading progress
/// indicator over the current frame, for instance.
typedef ImageLoadingBuilder = Widget Function(
  BuildContext context,
  ImageChunkEvent imageChunkEvent,
  Widget currentRawImage,
);

class Image {
  const Image({
    ...
    this.imageLoadingBuilder,
  });

  /// A builder that specifies the widget to display to the user
  /// before the image provider's stream has yielded its first
  /// image.
  ///
  /// If provided, this widget will be sized to match the size of
  /// the image.
  final ImageLoadingBuilder imageLoadingBuilder;
}