theme.dart 8.44 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3 4
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

xster's avatar
xster committed
5
import 'package:flutter/cupertino.dart';
6
import 'package:flutter/foundation.dart';
7

8
import 'material_localizations.dart';
9
import 'theme_data.dart';
10
import 'typography.dart';
11

12
export 'theme_data.dart' show Brightness, ThemeData;
13

14
/// The duration over which theme changes animate by default.
15
const Duration kThemeAnimationDuration = Duration(milliseconds: 200);
16

17
/// Applies a theme to descendant widgets.
18
///
19 20
/// A theme describes the colors and typographic choices of an application.
///
21 22
/// {@youtube 560 315 https://www.youtube.com/watch?v=oTvQDJOBXmM}
///
23 24 25 26
/// Descendant widgets obtain the current theme's [ThemeData] object using
/// [Theme.of]. When a widget uses [Theme.of], it is automatically rebuilt if
/// the theme later changes, so that the changes can be applied.
///
27 28 29
/// The [Theme] widget implies an [IconTheme] widget, set to the value of the
/// [ThemeData.iconTheme] of the [data] for the [Theme].
///
30 31
/// See also:
///
32 33 34 35 36
///  * [ThemeData], which describes the actual configuration of a theme.
///  * [AnimatedTheme], which animates the [ThemeData] when it changes rather
///    than changing the theme all at once.
///  * [MaterialApp], which includes an [AnimatedTheme] widget configured via
///    the [MaterialApp.theme] argument.
37
class Theme extends StatelessWidget {
38 39
  /// Applies the given theme [data] to [child].
  ///
40
  /// The [data] and [child] arguments must not be null.
41
  const Theme({
42
    super.key,
43 44
    required this.data,
    required this.child,
45
  }) : assert(child != null),
46
       assert(data != null);
47

48
  /// Specifies the color and typography values for descendant widgets.
49 50
  final ThemeData data;

51
  /// The widget below this widget in the tree.
52
  ///
53
  /// {@macro flutter.widgets.ProxyWidget.child}
54 55
  final Widget child;

56
  static final ThemeData _kFallbackTheme = ThemeData.fallback();
57

58 59
  /// The data from the closest [Theme] instance that encloses the given
  /// context.
60
  ///
61 62 63 64
  /// If the given context is enclosed in a [Localizations] widget providing
  /// [MaterialLocalizations], the returned data is localized according to the
  /// nearest available [MaterialLocalizations].
  ///
65
  /// Defaults to [ThemeData.fallback] if there is no [Theme] in the given
66
  /// build context.
67
  ///
68 69 70 71 72
  /// Typical usage is as follows:
  ///
  /// ```dart
  /// @override
  /// Widget build(BuildContext context) {
73
  ///   return Text(
74
  ///     'Example',
75
  ///     style: Theme.of(context).textTheme.headline6,
76 77 78 79 80 81 82 83 84 85 86 87 88 89
  ///   );
  /// }
  /// ```
  ///
  /// When the [Theme] is actually created in the same `build` function
  /// (possibly indirectly, e.g. as part of a [MaterialApp]), the `context`
  /// argument to the `build` function can't be used to find the [Theme] (since
  /// it's "above" the widget being returned). In such cases, the following
  /// technique with a [Builder] can be used to provide a new scope with a
  /// [BuildContext] that is "under" the [Theme]:
  ///
  /// ```dart
  /// @override
  /// Widget build(BuildContext context) {
90 91 92
  ///   return MaterialApp(
  ///     theme: ThemeData.light(),
  ///     body: Builder(
93 94 95
  ///       // Create an inner BuildContext so that we can refer to
  ///       // the Theme with Theme.of().
  ///       builder: (BuildContext context) {
96 97
  ///         return Center(
  ///           child: Text(
98
  ///             'Example',
99
  ///             style: Theme.of(context).textTheme.headline6,
100 101 102 103 104 105 106
  ///           ),
  ///         );
  ///       },
  ///     ),
  ///   );
  /// }
  /// ```
107
  static ThemeData of(BuildContext context) {
108
    final _InheritedTheme? inheritedTheme = context.dependOnInheritedWidgetOfExactType<_InheritedTheme>();
109
    final MaterialLocalizations? localizations = Localizations.of<MaterialLocalizations>(context, MaterialLocalizations);
110
    final ScriptCategory category = localizations?.scriptCategory ?? ScriptCategory.englishLike;
111
    final ThemeData theme = inheritedTheme?.theme.data ?? _kFallbackTheme;
112
    return ThemeData.localize(theme, theme.typography.geometryThemeFor(category));
113 114
  }

115 116 117 118 119 120 121 122 123 124 125 126 127 128 129
  // The inherited themes in widgets library can not infer their values from
  // Theme in material library. Wraps the child with these inherited themes to
  // overrides their values directly.
  Widget _wrapsWidgetThemes(BuildContext context, Widget child) {
    final DefaultSelectionStyle selectionStyle = DefaultSelectionStyle.of(context);
    return IconTheme(
      data: data.iconTheme,
      child: DefaultSelectionStyle(
        selectionColor: data.textSelectionTheme.selectionColor ?? selectionStyle.selectionColor,
        cursorColor: data.textSelectionTheme.cursorColor ?? selectionStyle.cursorColor,
        child: child,
      ),
    );
  }

130
  @override
131
  Widget build(BuildContext context) {
132
    return _InheritedTheme(
133
      theme: this,
134 135 136 137 138 139 140
      child: CupertinoTheme(
        // We're using a MaterialBasedCupertinoThemeData here instead of a
        // CupertinoThemeData because it defers some properties to the Material
        // ThemeData.
        data: MaterialBasedCupertinoThemeData(
          materialTheme: data,
        ),
141
        child: _wrapsWidgetThemes(context, child),
142
      ),
143 144
    );
  }
Hixie's avatar
Hixie committed
145

146
  @override
147 148
  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
    super.debugFillProperties(properties);
149
    properties.add(DiagnosticsProperty<ThemeData>('data', data, showName: false));
Hixie's avatar
Hixie committed
150
  }
151
}
152

153
class _InheritedTheme extends InheritedTheme {
154
  const _InheritedTheme({
155
    required this.theme,
156 157
    required super.child,
  }) : assert(theme != null);
158 159 160

  final Theme theme;

161 162
  @override
  Widget wrap(BuildContext context, Widget child) {
163
    return Theme(data: theme.data, child: child);
164 165
  }

166
  @override
167
  bool updateShouldNotify(_InheritedTheme old) => theme.data != old.theme.data;
168 169
}

170 171 172 173 174 175
/// An interpolation between two [ThemeData]s.
///
/// This class specializes the interpolation of [Tween<ThemeData>] to call the
/// [ThemeData.lerp] method.
///
/// See [Tween] for a discussion on how to use interpolation objects.
176
class ThemeDataTween extends Tween<ThemeData> {
177 178 179 180 181
  /// Creates a [ThemeData] tween.
  ///
  /// The [begin] and [end] properties must be non-null before the tween is
  /// first used, but the arguments can be null if the values are going to be
  /// filled in later.
182
  ThemeDataTween({ super.begin, super.end });
183

184
  @override
185
  ThemeData lerp(double t) => ThemeData.lerp(begin!, end!, t);
186 187
}

188
/// Animated version of [Theme] which automatically transitions the colors,
189
/// etc, over a given duration whenever the given theme changes.
190
///
191 192 193 194
/// Here's an illustration of what using this widget looks like, using a [curve]
/// of [Curves.elasticInOut].
/// {@animation 250 266 https://flutter.github.io/assets-for-api-docs/assets/widgets/animated_theme.mp4}
///
195 196
/// See also:
///
197 198 199 200 201
///  * [Theme], which [AnimatedTheme] uses to actually apply the interpolated
///    theme.
///  * [ThemeData], which describes the actual configuration of a theme.
///  * [MaterialApp], which includes an [AnimatedTheme] widget configured via
///    the [MaterialApp.theme] argument.
202
class AnimatedTheme extends ImplicitlyAnimatedWidget {
203 204
  /// Creates an animated theme.
  ///
205 206
  /// By default, the theme transition uses a linear curve. The [data] and
  /// [child] arguments must not be null.
207
  const AnimatedTheme({
208
    super.key,
209
    required this.data,
210 211 212
    super.curve,
    super.duration = kThemeAnimationDuration,
    super.onEnd,
213
    required this.child,
214
  }) : assert(child != null),
215
       assert(data != null);
216

217
  /// Specifies the color and typography values for descendant widgets.
218 219
  final ThemeData data;

220
  /// The widget below this widget in the tree.
221
  ///
222
  /// {@macro flutter.widgets.ProxyWidget.child}
223 224
  final Widget child;

225
  @override
226
  AnimatedWidgetBaseState<AnimatedTheme> createState() => _AnimatedThemeState();
227 228 229
}

class _AnimatedThemeState extends AnimatedWidgetBaseState<AnimatedTheme> {
230
  ThemeDataTween? _data;
231

232
  @override
233
  void forEachTween(TweenVisitor<dynamic> visitor) {
234
    _data = visitor(_data, widget.data, (dynamic value) => ThemeDataTween(begin: value as ThemeData))! as ThemeDataTween;
235 236
  }

237
  @override
238
  Widget build(BuildContext context) {
239
    return Theme(
240
      data: _data!.evaluate(animation),
241
      child: widget.child,
242 243 244
    );
  }

245
  @override
246
  void debugFillProperties(DiagnosticPropertiesBuilder description) {
247
    super.debugFillProperties(description);
248
    description.add(DiagnosticsProperty<ThemeDataTween>('data', _data, showName: false, defaultValue: null));
249 250
  }
}