Deprecate ThemeData.dialogBackgroundColor in favor of DialogThemeData.backgroundColor (#155072)

Related to [☂️ Material Theme System Updates](https://github.com/flutter/flutter/issues/91772)

packages/flutter/lib/fix_data/fix_material/fix_theme_data.yaml

@@ -26,6 +26,79 @@
 #     * WidgetState: fix_widget_state.yaml
 version: 1
 transforms:
+  # Changes made in https://github.com/flutter/flutter/pull/155072
+  - title: "Migrate 'ThemeData.dialogBackgroundColor' to 'DialogThemeData.backgroundColor'"
+    date: 2024-09-12
+    element:
+      uris: [ 'material.dart' ]
+      method: 'copyWith'
+      inClass: 'ThemeData'
+    oneOf:
+      - if: "dialogBackgroundColor != '' && dialogTheme != ''"
+        changes:
+          - kind: 'removeParameter'
+            name: 'dialogBackgroundColor'
+      - if: "dialogBackgroundColor != '' && dialogTheme == ''"
+        changes:
+          - kind: 'removeParameter'
+            name: 'dialogBackgroundColor'
+          - kind: 'addParameter'
+            index: 135
+            name: 'dialogTheme'
+            style: optional_named
+            argumentValue:
+              expression: 'DialogThemeData(backgroundColor: {% dialogBackgroundColor %})'
+              requiredIf: "dialogBackgroundColor != ''"
+    variables:
+      dialogBackgroundColor:
+        kind: 'fragment'
+        value: 'arguments[dialogBackgroundColor]'
+      dialogTheme:
+        kind: 'fragment'
+        value: 'arguments[dialogTheme]'
+
+  # Changes made in https://github.com/flutter/flutter/pull/155072
+  - title: "Migrate 'ThemeData.dialogBackgroundColor' to 'DialogThemeData.backgroundColor'"
+    date: 2024-09-12
+    element:
+      uris: [ 'material.dart' ]
+      constructor: ''
+      inClass: 'ThemeData'
+    oneOf:
+      - if: "dialogBackgroundColor != '' && dialogTheme != ''"
+        changes:
+          - kind: 'removeParameter'
+            name: 'dialogBackgroundColor'
+      - if: "dialogBackgroundColor != '' && dialogTheme == ''"
+        changes:
+          - kind: 'removeParameter'
+            name: 'dialogBackgroundColor'
+          - kind: 'addParameter'
+            index: 135
+            name: 'dialogTheme'
+            style: optional_named
+            argumentValue:
+              expression: 'DialogThemeData(backgroundColor: {% dialogBackgroundColor %})'
+              requiredIf: "dialogBackgroundColor != ''"
+    variables:
+      dialogBackgroundColor:
+        kind: 'fragment'
+        value: 'arguments[dialogBackgroundColor]'
+      dialogTheme:
+        kind: 'fragment'
+        value: 'arguments[dialogTheme]'
+
+  # Changes made in https://github.com/flutter/flutter/pull/145523
+  - title: "Remove 'buttonBarTheme'"
+    date: 2024-04-28
+    element:
+      uris: [ 'material.dart' ]
+      constructor: ''
+      inClass: 'ThemeData'
+    changes:
+      - kind: 'removeParameter'
+        name: 'buttonBarTheme'
+
   # Changes made in https://github.com/flutter/flutter/pull/87281
   - title: "Remove 'fixTextFieldOutlineLabel'"
     date: 2021-04-30
@@ -1698,15 +1771,4 @@ transforms:
       - kind: 'removeParameter'
         name: 'useMaterial3'
 
-  # Changes made in https://github.com/flutter/flutter/pull/145523
-  - title: "Remove 'buttonBarTheme'"
-    date: 2024-04-28
-    element:
-      uris: [ 'material.dart' ]
-      constructor: ''
-      inClass: 'ThemeData'
-    changes:
-      - kind: 'removeParameter'
-        name: 'buttonBarTheme'
-
 # Before adding a new fix: read instructions at the top of this file.

packages/flutter/lib/fix_data/fix_widgets/fix_widgets.yaml

@@ -23,7 +23,7 @@
 #     * ListWheelScrollView: fix_list_wheel_scroll_view.yaml
 version: 1
 transforms:
-  # Changes made in TBD
+  # Changes made in https://github.com/flutter/flutter/pull/139260
   - title: "Migrate to focusNode.enclosingScope!"
     date: 2023-11-29
     element:

packages/flutter/lib/src/material/dialog.dart

@@ -93,8 +93,10 @@ class Dialog extends StatelessWidget {
   ///
   /// This sets the [Material.color] on this [Dialog]'s [Material].
   ///
-  /// If `null`, [ColorScheme.surfaceContainerHigh] is used in Material 3.
-  /// Otherwise, defaults to [ThemeData.dialogBackgroundColor].
+  /// If null, then the [DialogThemeData.backgroundColor] is used. If that is
+  /// also null, defaults to [ColorScheme.surfaceContainerHigh]. If
+  /// [ThemeData.useMaterial3] is false, defaults to [Colors.grey] with a shade
+  ///  of 800 in dark theme and [Colors.white] in light theme.
   ///
   /// If [Dialog.fullscreen] is used, defaults to [ColorScheme.surface].
   /// {@endtemplate}
@@ -1638,9 +1640,7 @@ double _scalePadding(double textScaleFactor) {
 // Hand coded defaults based on Material Design 2.
 class _DialogDefaultsM2 extends DialogThemeData {
   _DialogDefaultsM2(this.context)
-    : _textTheme = Theme.of(context).textTheme,
-      _iconTheme = Theme.of(context).iconTheme,
-      super(
+    : super(
         alignment: Alignment.center,
         elevation: 24.0,
         shape: const RoundedRectangleBorder(borderRadius: BorderRadius.all(Radius.circular(4.0))),
@@ -1648,23 +1648,26 @@ class _DialogDefaultsM2 extends DialogThemeData {
       );
 
   final BuildContext context;
-  final TextTheme _textTheme;
-  final IconThemeData _iconTheme;
+  late final ThemeData theme = Theme.of(context);
+  late final TextTheme textTheme = theme.textTheme;
+  late final IconThemeData iconTheme = theme.iconTheme;
 
   @override
-  Color? get iconColor => _iconTheme.color;
+  Color? get iconColor => iconTheme.color;
 
   @override
-  Color? get backgroundColor => Theme.of(context).dialogBackgroundColor;
+  Color? get backgroundColor => theme.brightness == Brightness.dark
+    ? Colors.grey[800]!
+    : Colors.white;
 
   @override
-  Color? get shadowColor => Theme.of(context).shadowColor;
+  Color? get shadowColor => theme.shadowColor;
 
   @override
-  TextStyle? get titleTextStyle => _textTheme.titleLarge;
+  TextStyle? get titleTextStyle => textTheme.titleLarge;
 
   @override
-  TextStyle? get contentTextStyle => _textTheme.titleMedium;
+  TextStyle? get contentTextStyle => textTheme.titleMedium;
 
   @override
   EdgeInsetsGeometry? get actionsPadding => EdgeInsets.zero;

packages/flutter/lib/src/material/theme_data.dart

@@ -280,7 +280,6 @@ class ThemeData with Diagnosticable {
     // https://github.com/flutter/flutter/issues/91772.
     Color? canvasColor,
     Color? cardColor,
-    Color? dialogBackgroundColor,
     Color? disabledColor,
     Color? dividerColor,
     Color? focusColor,
@@ -361,6 +360,11 @@ class ThemeData with Diagnosticable {
       'This feature was deprecated after v3.21.0-10.0.pre.',
     )
     ButtonBarThemeData? buttonBarTheme,
+    @Deprecated(
+      'Use DialogThemeData.backgroundColor instead. '
+      'This feature was deprecated after v3.27.0-0.1.pre.',
+    )
+    Color? dialogBackgroundColor,
   }) {
     // GENERAL CONFIGURATION
     cupertinoOverrideTheme = cupertinoOverrideTheme?.noDefault();
@@ -446,7 +450,6 @@ class ThemeData with Diagnosticable {
     unselectedWidgetColor ??= isDark ? Colors.white70 : Colors.black54;
     // Spec doesn't specify a dark theme secondaryHeaderColor, this is a guess.
     secondaryHeaderColor ??= isDark ? Colors.grey[700]! : primarySwatch[50]!;
-    dialogBackgroundColor ??= isDark ? Colors.grey[800]! : Colors.white;
     indicatorColor ??= colorScheme.secondary == primaryColor ? Colors.white : colorScheme.secondary;
     hintColor ??= isDark ? Colors.white60 : Colors.black.withOpacity(0.6);
     // The default [buttonTheme] is here because it doesn't use the defaults for
@@ -558,6 +561,7 @@ class ThemeData with Diagnosticable {
     tooltipTheme ??= const TooltipThemeData();
     // DEPRECATED (newest deprecations at the bottom)
     buttonBarTheme ??= const ButtonBarThemeData();
+    dialogBackgroundColor ??= isDark ? Colors.grey[800]! : Colors.white;
     return ThemeData.raw(
       // For the sanity of the reader, make sure these properties are in the same
       // order in every place that they are separated by section comments (e.g.
@@ -581,7 +585,6 @@ class ThemeData with Diagnosticable {
       canvasColor: canvasColor,
       cardColor: cardColor,
       colorScheme: colorScheme,
-      dialogBackgroundColor: dialogBackgroundColor,
       disabledColor: disabledColor,
       dividerColor: dividerColor,
       focusColor: focusColor,
@@ -651,6 +654,7 @@ class ThemeData with Diagnosticable {
       tooltipTheme: tooltipTheme,
       // DEPRECATED (newest deprecations at the bottom)
       buttonBarTheme: buttonBarTheme,
+      dialogBackgroundColor: dialogBackgroundColor,
     );
   }
 
@@ -687,7 +691,6 @@ class ThemeData with Diagnosticable {
     // https://github.com/flutter/flutter/issues/91772.
     required this.canvasColor,
     required this.cardColor,
-    required this.dialogBackgroundColor,
     required this.disabledColor,
     required this.dividerColor,
     required this.focusColor,
@@ -761,6 +764,11 @@ class ThemeData with Diagnosticable {
       'This feature was deprecated after v3.21.0-10.0.pre.',
     )
     ButtonBarThemeData? buttonBarTheme,
+    @Deprecated(
+      'Use DialogThemeData.backgroundColor instead. '
+      'This feature was deprecated after v3.27.0-0.1.pre.',
+    )
+    required this.dialogBackgroundColor,
   }) : // DEPRECATED (newest deprecations at the bottom)
        // should not be `required`, use getter pattern to avoid breakages.
        _buttonBarTheme = buttonBarTheme,
@@ -1154,9 +1162,6 @@ class ThemeData with Diagnosticable {
   /// backwards compatibility breaks.
   final ColorScheme colorScheme;
 
-  /// The background color of [Dialog] elements.
-  final Color dialogBackgroundColor;
-
   /// The color used for widgets that are inoperative, regardless of
   /// their state. For example, a disabled checkbox (which may be
   /// checked or unchecked).
@@ -1424,6 +1429,13 @@ class ThemeData with Diagnosticable {
   ButtonBarThemeData get buttonBarTheme => _buttonBarTheme!;
   final ButtonBarThemeData? _buttonBarTheme;
 
+  /// The background color of [Dialog] elements.
+  @Deprecated(
+    'Use DialogThemeData.backgroundColor instead. '
+    'This feature was deprecated after v3.27.0-0.1.pre.',
+  )
+  final Color dialogBackgroundColor;
+
   /// Creates a copy of this theme but with the given fields replaced with the new values.
   ///
   /// The [brightness] value is applied to the [colorScheme].
@@ -1453,7 +1465,6 @@ class ThemeData with Diagnosticable {
     // https://github.com/flutter/flutter/issues/91772.
     Color? canvasColor,
     Color? cardColor,
-    Color? dialogBackgroundColor,
     Color? disabledColor,
     Color? dividerColor,
     Color? focusColor,
@@ -1537,6 +1548,11 @@ class ThemeData with Diagnosticable {
       'This feature was deprecated after v3.21.0-10.0.pre.',
     )
     ButtonBarThemeData? buttonBarTheme,
+    @Deprecated(
+      'Use DialogThemeData.backgroundColor instead. '
+      'This feature was deprecated after v3.27.0-0.1.pre.',
+    )
+    Color? dialogBackgroundColor,
   }) {
     cupertinoOverrideTheme = cupertinoOverrideTheme?.noDefault();
 
@@ -1591,7 +1607,6 @@ class ThemeData with Diagnosticable {
       canvasColor: canvasColor ?? this.canvasColor,
       cardColor: cardColor ?? this.cardColor,
       colorScheme: (colorScheme ?? this.colorScheme).copyWith(brightness: brightness),
-      dialogBackgroundColor: dialogBackgroundColor ?? this.dialogBackgroundColor,
       disabledColor: disabledColor ?? this.disabledColor,
       dividerColor: dividerColor ?? this.dividerColor,
       focusColor: focusColor ?? this.focusColor,
@@ -1659,7 +1674,9 @@ class ThemeData with Diagnosticable {
       timePickerTheme: timePickerTheme ?? this.timePickerTheme,
       toggleButtonsTheme: toggleButtonsTheme ?? this.toggleButtonsTheme,
       tooltipTheme: tooltipTheme ?? this.tooltipTheme,
+      // DEPRECATED (newest deprecations at the bottom)
       buttonBarTheme: buttonBarTheme ?? _buttonBarTheme,
+      dialogBackgroundColor: dialogBackgroundColor ?? this.dialogBackgroundColor,
     );
   }
 
@@ -1784,7 +1801,6 @@ class ThemeData with Diagnosticable {
       canvasColor: Color.lerp(a.canvasColor, b.canvasColor, t)!,
       cardColor: Color.lerp(a.cardColor, b.cardColor, t)!,
       colorScheme: ColorScheme.lerp(a.colorScheme, b.colorScheme, t),
-      dialogBackgroundColor: Color.lerp(a.dialogBackgroundColor, b.dialogBackgroundColor, t)!,
       disabledColor: Color.lerp(a.disabledColor, b.disabledColor, t)!,
       dividerColor: Color.lerp(a.dividerColor, b.dividerColor, t)!,
       focusColor: Color.lerp(a.focusColor, b.focusColor, t)!,
@@ -1852,7 +1868,9 @@ class ThemeData with Diagnosticable {
       timePickerTheme: TimePickerThemeData.lerp(a.timePickerTheme, b.timePickerTheme, t),
       toggleButtonsTheme: ToggleButtonsThemeData.lerp(a.toggleButtonsTheme, b.toggleButtonsTheme, t)!,
       tooltipTheme: TooltipThemeData.lerp(a.tooltipTheme, b.tooltipTheme, t)!,
+      // DEPRECATED (newest deprecations at the bottom)
       buttonBarTheme: ButtonBarThemeData.lerp(a.buttonBarTheme, b.buttonBarTheme, t),
+      dialogBackgroundColor: Color.lerp(a.dialogBackgroundColor, b.dialogBackgroundColor, t)!,
     );
   }
 
@@ -1884,7 +1902,6 @@ class ThemeData with Diagnosticable {
         other.canvasColor == canvasColor &&
         other.cardColor == cardColor &&
         other.colorScheme == colorScheme &&
-        other.dialogBackgroundColor == dialogBackgroundColor &&
         other.disabledColor == disabledColor &&
         other.dividerColor == dividerColor &&
         other.focusColor == focusColor &&
@@ -1952,7 +1969,9 @@ class ThemeData with Diagnosticable {
         other.timePickerTheme == timePickerTheme &&
         other.toggleButtonsTheme == toggleButtonsTheme &&
         other.tooltipTheme == tooltipTheme &&
-        other.buttonBarTheme == buttonBarTheme;
+        // DEPRECATED (newest deprecations at the bottom)
+        other.buttonBarTheme == buttonBarTheme &&
+        other.dialogBackgroundColor == dialogBackgroundColor;
   }
 
   @override
@@ -1982,7 +2001,6 @@ class ThemeData with Diagnosticable {
       canvasColor,
       cardColor,
       colorScheme,
-      dialogBackgroundColor,
       disabledColor,
       dividerColor,
       focusColor,
@@ -2052,6 +2070,7 @@ class ThemeData with Diagnosticable {
       tooltipTheme,
       // DEPRECATED (newest deprecations at the bottom)
       buttonBarTheme,
+      dialogBackgroundColor,
     ];
     return Object.hashAll(values);
   }
@@ -2082,7 +2101,6 @@ class ThemeData with Diagnosticable {
     properties.add(ColorProperty('canvasColor', canvasColor, defaultValue: defaultData.canvasColor, level: DiagnosticLevel.debug));
     properties.add(ColorProperty('cardColor', cardColor, defaultValue: defaultData.cardColor, level: DiagnosticLevel.debug));
     properties.add(DiagnosticsProperty<ColorScheme>('colorScheme', colorScheme, defaultValue: defaultData.colorScheme, level: DiagnosticLevel.debug));
-    properties.add(ColorProperty('dialogBackgroundColor', dialogBackgroundColor, defaultValue: defaultData.dialogBackgroundColor, level: DiagnosticLevel.debug));
     properties.add(ColorProperty('disabledColor', disabledColor, defaultValue: defaultData.disabledColor, level: DiagnosticLevel.debug));
     properties.add(ColorProperty('dividerColor', dividerColor, defaultValue: defaultData.dividerColor, level: DiagnosticLevel.debug));
     properties.add(ColorProperty('focusColor', focusColor, defaultValue: defaultData.focusColor, level: DiagnosticLevel.debug));
@@ -2152,6 +2170,7 @@ class ThemeData with Diagnosticable {
     properties.add(DiagnosticsProperty<TooltipThemeData>('tooltipTheme', tooltipTheme, level: DiagnosticLevel.debug));
     // DEPRECATED (newest deprecations at the bottom)
     properties.add(DiagnosticsProperty<ButtonBarThemeData>('buttonBarTheme', buttonBarTheme, defaultValue: defaultData.buttonBarTheme, level: DiagnosticLevel.debug));
+    properties.add(ColorProperty('dialogBackgroundColor', dialogBackgroundColor, defaultValue: defaultData.dialogBackgroundColor, level: DiagnosticLevel.debug));
   }
 }
 

packages/flutter/test_fixes/material/theme_data.dart

@@ -237,4 +237,12 @@ void main() {
 
   // Changes made in https://github.com/flutter/flutter/pull/131455
   ThemeData themeData = ThemeData.copyWith(useMaterial3: false);
+
+  // Changes made in https://github.com/flutter/flutter/pull/155072
+  ThemeData themeData = ThemeData();
+  themeData = ThemeData(dialogBackgroundColor: Colors.orange);
+  themeData = ThemeData(dialogBackgroundColor: Colors.orange, dialogTheme: DialogThemeData(backgroundColor: Colors.red));
+  themeData = themeData.copyWith(dialogBackgroundColor: Colors.orange);
+  themeData = themeData.copyWith(dialogBackgroundColor: Colors.orange, dialogTheme: DialogThemeData(backgroundColor: Colors.red));
+  themeData.dialogBackgroundColor; // Removing field reference not supported.
 }

packages/flutter/test_fixes/material/theme_data.dart.expect

@@ -443,4 +443,12 @@ void main() {
 
   // Changes made in https://github.com/flutter/flutter/pull/131455
   ThemeData themeData = ThemeData.copyWith();
+
+  // Changes made in https://github.com/flutter/flutter/pull/155072
+  ThemeData themeData = ThemeData();
+  themeData = ThemeData(dialogTheme: DialogThemeData(backgroundColor: Colors.orange));
+  themeData = ThemeData(dialogTheme: DialogThemeData(backgroundColor: Colors.red));
+  themeData = themeData.copyWith(dialogTheme: DialogThemeData(backgroundColor: Colors.orange));
+  themeData = themeData.copyWith(dialogTheme: DialogThemeData(backgroundColor: Colors.red));
+  themeData.dialogBackgroundColor; // Removing field reference not supported.
 }

packages/flutter/test_fixes/widgets/widgets.dart

@@ -174,7 +174,7 @@ void main() {
   final PlatformMenuBar platformMenuBar = PlatformMenuBar(menus: <PlatformMenuItem>[], body: const SizedBox());
   final Widget bodyValue = platformMenuBar.body;
 
-  // Changes made in TBD
+  // Changes made in https://github.com/flutter/flutter/pull/139260
   final NavigatorState state = Navigator.of(context);
   state.focusScopeNode;
 }

packages/flutter/test_fixes/widgets/widgets.dart.expect

@@ -174,7 +174,7 @@ void main() {
   final PlatformMenuBar platformMenuBar = PlatformMenuBar(menus: <PlatformMenuItem>[], child: const SizedBox());
   final Widget bodyValue = platformMenuBar.child;
 
-  // Changes made in TBD
+  // Changes made in https://github.com/flutter/flutter/pull/139260
   final NavigatorState state = Navigator.of(context);
   state.focusNode.enclosingScope!;
 }