Closed
Description
Fuchsia would like to be able to display the loading progress of an image that's loaded over the network. Below is a rough proposal of how we could accomplish that.
We'd need to change NetworkImage to load using Socket directly so that it could report the chunks as they came in, and we'd have to plumb those events through ImageStreamCompleter.
Rough API proposal:
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;
}