theme.dart 9.04 KB
Newer Older
1 2 3 4
// Copyright 2015 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

5
import 'package:flutter/foundation.dart';
6
import 'package:flutter/widgets.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 21 22 23 24
/// A theme describes the colors and typographic choices of an application.
///
/// 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.
///
25 26 27
/// The [Theme] widget implies an [IconTheme] widget, set to the value of the
/// [ThemeData.iconTheme] of the [data] for the [Theme].
///
28 29
/// See also:
///
30 31 32 33 34
///  * [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.
35
class Theme extends StatelessWidget {
36 37
  /// Applies the given theme [data] to [child].
  ///
38
  /// The [data] and [child] arguments must not be null.
39
  const Theme({
40
    Key key,
41
    @required this.data,
42
    this.isMaterialAppTheme = false,
43
    @required this.child,
44 45
  }) : assert(child != null),
       assert(data != null),
46
       super(key: key);
47

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

51 52 53 54 55 56 57 58 59 60 61
  /// True if this theme was installed by the [MaterialApp].
  ///
  /// When an app uses the [Navigator] to push a route, the route's widgets
  /// will only inherit from the app's theme, even though the widget that
  /// triggered the push may inherit from a theme that "shadows" the app's
  /// theme because it's deeper in the widget tree. Apps can find the shadowing
  /// theme with `Theme.of(context, shadowThemeOnly: true)` and pass it along
  /// to the class that creates a route's widgets. Material widgets that push
  /// routes, like [PopupMenuButton] and [DropdownButton], do this.
  final bool isMaterialAppTheme;

62
  /// The widget below this widget in the tree.
63 64
  ///
  /// {@macro flutter.widgets.child}
65 66
  final Widget child;

67
  static final ThemeData _kFallbackTheme = ThemeData.fallback();
68

69 70
  /// The data from the closest [Theme] instance that encloses the given
  /// context.
71
  ///
72 73 74 75
  /// If the given context is enclosed in a [Localizations] widget providing
  /// [MaterialLocalizations], the returned data is localized according to the
  /// nearest available [MaterialLocalizations].
  ///
76 77
  /// Defaults to [new ThemeData.fallback] if there is no [Theme] in the given
  /// build context.
78
  ///
79 80 81 82 83 84 85
  /// If [shadowThemeOnly] is true and the closest [Theme] ancestor was
  /// installed by the [MaterialApp] — in other words if the closest [Theme]
  /// ancestor does not shadow the application's theme — then this returns null.
  /// This argument should be used in situations where its useful to wrap a
  /// route's widgets with a [Theme], but only when the application's overall
  /// theme is being shadowed by a [Theme] widget that is deeper in the tree.
  /// See [isMaterialAppTheme].
86 87 88 89 90 91
  ///
  /// Typical usage is as follows:
  ///
  /// ```dart
  /// @override
  /// Widget build(BuildContext context) {
92
  ///   return Text(
93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108
  ///     'Example',
  ///     style: Theme.of(context).textTheme.title,
  ///   );
  /// }
  /// ```
  ///
  /// 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) {
109 110 111
  ///   return MaterialApp(
  ///     theme: ThemeData.light(),
  ///     body: Builder(
112 113 114
  ///       // Create an inner BuildContext so that we can refer to
  ///       // the Theme with Theme.of().
  ///       builder: (BuildContext context) {
115 116
  ///         return Center(
  ///           child: Text(
117 118 119 120 121 122 123 124 125
  ///             'Example',
  ///             style: Theme.of(context).textTheme.title,
  ///           ),
  ///         );
  ///       },
  ///     ),
  ///   );
  /// }
  /// ```
126
  static ThemeData of(BuildContext context, { bool shadowThemeOnly = false }) {
127
    final _InheritedTheme inheritedTheme = context.inheritFromWidgetOfExactType(_InheritedTheme);
128
    if (shadowThemeOnly) {
129
      if (inheritedTheme == null || inheritedTheme.theme.isMaterialAppTheme)
130
        return null;
131
      return inheritedTheme.theme.data;
132
    }
133 134

    final MaterialLocalizations localizations = MaterialLocalizations.of(context);
135 136 137
    final ScriptCategory category = localizations?.scriptCategory ?? ScriptCategory.englishLike;
    final ThemeData theme = inheritedTheme?.theme?.data ?? _kFallbackTheme;
    return ThemeData.localize(theme, theme.typography.geometryThemeFor(category));
138 139
  }

140
  @override
141
  Widget build(BuildContext context) {
142
    return _InheritedTheme(
143
      theme: this,
144
      child: IconTheme(
145 146 147 148 149
        data: data.iconTheme,
        child: child,
      ),
    );
  }
Hixie's avatar
Hixie committed
150

151
  @override
152 153
  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
    super.debugFillProperties(properties);
154
    properties.add(DiagnosticsProperty<ThemeData>('data', data, showName: false));
Hixie's avatar
Hixie committed
155
  }
156
}
157

158 159 160 161 162 163 164 165 166 167 168
class _InheritedTheme extends InheritedWidget {
  const _InheritedTheme({
    Key key,
    @required this.theme,
    @required Widget child
  }) : assert(theme != null),
       super(key: key, child: child);

  final Theme theme;

  @override
169
  bool updateShouldNotify(_InheritedTheme old) => theme.data != old.theme.data;
170 171
}

172 173 174 175 176 177
/// 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.
178
class ThemeDataTween extends Tween<ThemeData> {
179 180 181 182 183
  /// 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.
184
  ThemeDataTween({ ThemeData begin, ThemeData end }) : super(begin: begin, end: end);
185

186
  @override
187 188 189
  ThemeData lerp(double t) => ThemeData.lerp(begin, end, t);
}

190
/// Animated version of [Theme] which automatically transitions the colors,
191
/// etc, over a given duration whenever the given theme changes.
192
///
193 194 195 196
/// 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}
///
197 198
/// See also:
///
199 200 201 202 203
///  * [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.
204
class AnimatedTheme extends ImplicitlyAnimatedWidget {
205 206
  /// Creates an animated theme.
  ///
207 208
  /// By default, the theme transition uses a linear curve. The [data] and
  /// [child] arguments must not be null.
209
  const AnimatedTheme({
210
    Key key,
211
    @required this.data,
212 213 214
    this.isMaterialAppTheme = false,
    Curve curve = Curves.linear,
    Duration duration = kThemeAnimationDuration,
215
    @required this.child,
216 217 218
  }) : assert(child != null),
       assert(data != null),
       super(key: key, curve: curve, duration: duration);
219

220
  /// Specifies the color and typography values for descendant widgets.
221 222
  final ThemeData data;

223 224 225
  /// True if this theme was created by the [MaterialApp]. See [Theme.isMaterialAppTheme].
  final bool isMaterialAppTheme;

226
  /// The widget below this widget in the tree.
227 228
  ///
  /// {@macro flutter.widgets.child}
229 230
  final Widget child;

231
  @override
232
  _AnimatedThemeState createState() => _AnimatedThemeState();
233 234 235
}

class _AnimatedThemeState extends AnimatedWidgetBaseState<AnimatedTheme> {
236
  ThemeDataTween _data;
237

238
  @override
239
  void forEachTween(TweenVisitor<dynamic> visitor) {
240
    // TODO(ianh): Use constructor tear-offs when it becomes possible
241
    _data = visitor(_data, widget.data, (dynamic value) => ThemeDataTween(begin: value));
242 243 244
    assert(_data != null);
  }

245
  @override
246
  Widget build(BuildContext context) {
247
    return Theme(
248 249
      isMaterialAppTheme: widget.isMaterialAppTheme,
      child: widget.child,
250
      data: _data.evaluate(animation)
251 252 253
    );
  }

254
  @override
255
  void debugFillProperties(DiagnosticPropertiesBuilder description) {
256
    super.debugFillProperties(description);
257
    description.add(DiagnosticsProperty<ThemeDataTween>('data', _data, showName: false, defaultValue: null));
258 259
  }
}