Skip to content

Commit 89d59da

Browse files
authored
Image GIF pausing (#176492)
Flutter needs a strong story around pausing animated GIFs because it affects accessibility via [MediaQueryData.disableAnimations](https://main-api.flutter.dev/flutter/widgets/MediaQueryData/disableAnimations.html). See #175516. ### Today Currently, it's possible to pause a gif using TickerProvider. However, if paused on initial load, the first frame will never display, and I believe that's a bug. ```dart TickerMode( // Pauses the gif, but if set to false on first load, the first frame never loads. enabled: false, child: Image(image: myAnimatedGif), ), ``` Currently `disableAnimations` has no effect: ```dart MediaQuery( // Currently has no effect on the Image, until this PR. data: MediaQueryData(disableAnimations: true), child: Image(image: myAnimatedGif), ), ``` ### With this PR * MediaQueryData.disableAnimations can be used to pause a gif in the same way that TickerMode can be used today. * If either MediaQuery.disableAnimations or TickerMode cause a gif to be paused on first load, it will show its first frame before pausing. This is potentially a breaking change. * The docs clearly explain this behavior and how to pause a gif. Fixes #175516 Partial fix for #130976 Fixes Google b/419605327
1 parent 90f26f5 commit 89d59da

2 files changed

Lines changed: 947 additions & 20 deletions

File tree

‎packages/flutter/lib/src/widgets/image.dart‎

Lines changed: 40 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,8 @@ export 'package:flutter/painting.dart'
4747
// Examples can assume:
4848
// late Widget image;
4949
// late ImageProvider _image;
50+
// late bool isPaused;
51+
// late AssetImage myAnimatedGif;
5052

5153
/// Creates an [ImageConfiguration] based on the given [BuildContext] (and
5254
/// optionally size).
@@ -282,6 +284,23 @@ typedef ImageErrorWidgetBuilder =
282284
/// ```
283285
/// {@end-tool}
284286
///
287+
/// Multiframe images, such as animated GIFs, are paused when [TickerMode] is
288+
/// disabled just like any other animation. They also paused when animations are
289+
/// disabled via [MediaQueryData.disableAnimations], such as for accessibility
290+
/// purposes. If the animation is paused when the image first loads, the first
291+
/// frame will be displayed and then animation will stop.
292+
///
293+
/// {@tool snippet}
294+
//// An example of pausing a multiframe image using [TickerMode].
295+
///
296+
/// ```dart
297+
/// TickerMode(
298+
/// enabled: !isPaused,
299+
/// child: Image(image: myAnimatedGif),
300+
/// ),
301+
/// ```
302+
/// {@end-tool}
303+
///
285304
/// ## Memory usage
286305
///
287306
/// The image is stored in memory in uncompressed form (so that it can be
@@ -1101,6 +1120,11 @@ class _ImageState extends State<Image> with WidgetsBindingObserver {
11011120
StackTrace? _lastStack;
11021121
ImageStreamCompleterHandle? _completerHandle;
11031122

1123+
/// True when animations are disabled and the image should not update, such as
1124+
/// when [TickerMode] is disabled or [MediaQueryData.disableAnimations] is
1125+
/// true.
1126+
bool _isPaused = false;
1127+
11041128
@override
11051129
void initState() {
11061130
super.initState();
@@ -1124,10 +1148,12 @@ class _ImageState extends State<Image> with WidgetsBindingObserver {
11241148
_updateInvertColors();
11251149
_resolveImage();
11261150

1127-
if (TickerMode.of(context)) {
1128-
_listenToStream();
1129-
} else {
1151+
_isPaused = !TickerMode.of(context) || (MediaQuery.maybeDisableAnimationsOf(context) ?? false);
1152+
1153+
if (_isPaused && _frameNumber != null) {
11301154
_stopListeningToStream(keepStreamAlive: true);
1155+
} else {
1156+
_listenToStream();
11311157
}
11321158

11331159
super.didChangeDependencies();
@@ -1144,6 +1170,7 @@ class _ImageState extends State<Image> with WidgetsBindingObserver {
11441170
}
11451171
if (widget.image != oldWidget.image) {
11461172
_resolveImage();
1173+
_listenToStream();
11471174
}
11481175
}
11491176

@@ -1220,6 +1247,9 @@ class _ImageState extends State<Image> with WidgetsBindingObserver {
12201247
_frameNumber = _frameNumber == null ? 0 : _frameNumber! + 1;
12211248
_wasSynchronouslyLoaded = _wasSynchronouslyLoaded | synchronousCall;
12221249
});
1250+
if (_isPaused) {
1251+
_stopListeningToStream(keepStreamAlive: true);
1252+
}
12231253
}
12241254

12251255
void _handleImageChunk(ImageChunkEvent event) {
@@ -1233,10 +1263,12 @@ class _ImageState extends State<Image> with WidgetsBindingObserver {
12331263

12341264
void _replaceImage({required ImageInfo? info}) {
12351265
final ImageInfo? oldImageInfo = _imageInfo;
1236-
SchedulerBinding.instance.addPostFrameCallback(
1237-
(_) => oldImageInfo?.dispose(),
1238-
debugLabel: 'Image.disposeOldInfo',
1239-
);
1266+
if (oldImageInfo != null) {
1267+
SchedulerBinding.instance.addPostFrameCallback(
1268+
(Duration duration) => oldImageInfo.dispose(),
1269+
debugLabel: 'Image.disposeOldInfo',
1270+
);
1271+
}
12401272
_imageInfo = info;
12411273
}
12421274

@@ -1275,11 +1307,10 @@ class _ImageState extends State<Image> with WidgetsBindingObserver {
12751307
return;
12761308
}
12771309

1310+
_isListeningToStream = true;
12781311
_imageStream!.addListener(_getListener());
12791312
_completerHandle?.dispose();
12801313
_completerHandle = null;
1281-
1282-
_isListeningToStream = true;
12831314
}
12841315

12851316
/// Stops listening to the image stream, if this state object has attached a

0 commit comments

Comments
 (0)