settings [nfc]: Centralize logic for checking device animation settings

Author: chrisbobbe

lib/model/settings.dart

@@ -1,3 +1,4 @@
+import 'package:flutter/widgets.dart';
 import 'package:flutter/foundation.dart';
 
 import '../generated/l10n/zulip_localizations.dart';
@@ -473,3 +474,53 @@ class GlobalSettingsStore extends ChangeNotifier {
     notifyListeners();
   }
 }
+
+/// Whether to show an animated image in its still or animated version.
+///
+/// Use [resolve] to evaluate this for the given [BuildContext],
+/// which reads device-setting data for [animateConditionally].
+///
+/// Callers should try to check whether an image is animated,
+/// i.e. whether it has separate still and animated versions.
+/// This can't be done perfectly (in 2025-10)
+/// because of animated emoji that were uploaded before Zulip Server 5
+/// and don't have `still_url` filled in:
+///   https://github.com/zulip/zulip/issues/36339 .
+// TODO(server-future) Remove comment once all supported servers have a fix for
+//   zulip/zulip#36339, i.e. that have run a migration to fill in still_url.
+enum ImageAnimationMode {
+  /// Always show the animated version, ignoring device settings.
+  animateAlways,
+
+  /// Always show the still version, ignoring device settings.
+  animateNever,
+
+  /// Show the animated version
+  /// just if animations aren't disabled in device settings.
+  animateConditionally,
+  ;
+
+  /// True if the image should be animated, false if it should be still.
+  bool resolve(BuildContext context) {
+    switch (this) {
+      case animateAlways: return true;
+      case animateNever: return false;
+      case animateConditionally:
+        // From reading code, this doesn't actually get set on iOS:
+        //   https://github.com/zulip/zulip-flutter/pull/410#discussion_r1408522293
+        if (MediaQuery.disableAnimationsOf(context)) return false;
+
+        if (
+          defaultTargetPlatform == TargetPlatform.iOS
+          // TODO(#1924) On iOS 17+ (new in 2023), there's a more closely
+          //   relevant setting than "reduce motion". It's called "auto-play
+          //   animated images"; we should use that once Flutter exposes it.
+          && WidgetsBinding.instance.platformDispatcher.accessibilityFeatures.reduceMotion
+        ) {
+          return false;
+        }
+
+        return true;
+    }
+  }
+}

lib/widgets/emoji.dart

@@ -3,6 +3,7 @@ import 'package:flutter/widgets.dart';
 
 import '../api/model/model.dart';
 import '../model/emoji.dart';
+import '../model/settings.dart';
 import 'content.dart';
 
 /// A widget showing an emoji.
@@ -13,7 +14,7 @@ class EmojiWidget extends StatelessWidget {
     required this.squareDimension,
     this.squareDimensionScaler = TextScaler.noScaling,
     this.imagePlaceholderStyle = EmojiImagePlaceholderStyle.square,
-    this.neverAnimateImage = false,
+    this.imageAnimationMode = ImageAnimationMode.animateConditionally,
     this.buildCustomTextEmoji,
   });
 
@@ -35,11 +36,12 @@ class EmojiWidget extends StatelessWidget {
 
   final EmojiImagePlaceholderStyle imagePlaceholderStyle;
 
-  /// Whether to show an animated emoji in its still (non-animated) variant
-  /// only, even if device settings permit animation.
+  /// Whether to show an animated emoji in its still or animated version.
   ///
-  /// Defaults to false.
-  final bool neverAnimateImage;
+  /// Ignored except for animated image emoji.
+  ///
+  /// Defaults to [ImageAnimationMode.animateConditionally].
+  final ImageAnimationMode imageAnimationMode;
 
   /// An optional callback to specify a custom plain-text emoji style.
   ///
@@ -71,7 +73,7 @@ class EmojiWidget extends StatelessWidget {
         size: squareDimension,
         textScaler: squareDimensionScaler,
         errorBuilder: _getImageErrorBuilder(effectiveSquareDimension),
-        neverAnimate: neverAnimateImage),
+        animationMode: imageAnimationMode),
       UnicodeEmojiDisplay() => UnicodeEmojiWidget(
         size: squareDimension,
         emojiDisplay: emojiDisplay),
@@ -189,7 +191,7 @@ class ImageEmojiWidget extends StatelessWidget {
     required this.size,
     this.textScaler = TextScaler.noScaling,
     this.errorBuilder,
-    this.neverAnimate = false,
+    this.animationMode = ImageAnimationMode.animateConditionally,
   });
 
   final ImageEmojiDisplay emojiDisplay;
@@ -206,30 +208,20 @@ class ImageEmojiWidget extends StatelessWidget {
 
   final ImageErrorWidgetBuilder? errorBuilder;
 
-  /// Whether to show an animated emoji in its still (non-animated) variant
-  /// only, even if device settings permit animation.
+  /// Whether to show an animated emoji in its still or animated version.
+  ///
+  /// Ignored for non-animated emoji.
   ///
-  /// Defaults to false.
-  final bool neverAnimate;
+  /// Defaults to [ImageAnimationMode.animateConditionally].
+  final ImageAnimationMode animationMode;
 
   @override
   Widget build(BuildContext context) {
-    final doNotAnimate =
-      neverAnimate
-      // From reading code, this doesn't actually get set on iOS:
-      //   https://github.com/zulip/zulip-flutter/pull/410#discussion_r1408522293
-      || MediaQuery.disableAnimationsOf(context)
-      || (defaultTargetPlatform == TargetPlatform.iOS
-        // TODO(#1924) On iOS 17+ (new in 2023), there's a more closely
-        //   relevant setting than "reduce motion". It's called "auto-play
-        //   animated images"; we should use that once Flutter exposes it.
-        && WidgetsBinding.instance.platformDispatcher.accessibilityFeatures.reduceMotion);
-
     final size = textScaler.scale(this.size);
 
-    final resolvedUrl = doNotAnimate
-      ? (emojiDisplay.resolvedStillUrl ?? emojiDisplay.resolvedUrl)
-      : emojiDisplay.resolvedUrl;
+    final resolvedUrl = animationMode.resolve(context)
+      ? emojiDisplay.resolvedUrl
+      : (emojiDisplay.resolvedStillUrl ?? emojiDisplay.resolvedUrl);
 
     return RealmContentNetworkImage(
       width: size, height: size,

lib/widgets/user.dart

@@ -4,6 +4,7 @@ import '../api/model/model.dart';
 import '../model/avatar_url.dart';
 import '../model/binding.dart';
 import '../model/presence.dart';
+import '../model/settings.dart';
 import 'content.dart';
 import 'emoji.dart';
 import 'icons.dart';
@@ -363,7 +364,7 @@ class UserStatusEmoji extends StatelessWidget {
       child: EmojiWidget(
         emojiDisplay: emojiDisplay,
         squareDimension: size,
-        neverAnimateImage: neverAnimate,
+        imageAnimationMode: ImageAnimationMode.animateNever,
         buildCustomTextEmoji: () =>
           // Invoked when an image emoji's URL didn't parse; see
           // EmojiStore.emojiDisplayFor. Don't show text, just an empty square.