flexible_space_bar.dart 16.3 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.

5 6
// @dart = 2.8

7
import 'dart:math' as math;
8
import 'dart:ui' as ui;
9

10
import 'package:flutter/foundation.dart';
11 12
import 'package:flutter/widgets.dart';

13
import 'colors.dart';
14 15 16
import 'constants.dart';
import 'theme.dart';

17
/// The collapsing effect while the space bar collapses from its full size.
18 19 20 21 22 23 24 25 26 27 28
enum CollapseMode {
  /// The background widget will scroll in a parallax fashion.
  parallax,

  /// The background widget pin in place until it reaches the min extent.
  pin,

  /// The background widget will act as normal with no collapsing effect.
  none,
}

29 30 31 32 33 34 35 36 37 38 39 40 41 42
/// The stretching effect while the space bar stretches beyond its full size.
enum StretchMode {
  /// The background widget will expand to fill the extra space.
  zoomBackground,

  /// The background will blur using a [ImageFilter.blur] effect.
  blurBackground,

  /// The title will fade away as the user over-scrolls.
  fadeTitle,
}

/// The part of a material design [AppBar] that expands, collapses, and
/// stretches.
43
///
44
/// Most commonly used in the [SliverAppBar.flexibleSpace] field, a flexible
45 46
/// space bar expands and contracts as the app scrolls so that the [AppBar]
/// reaches from the top of the app to the top of the scrolling contents of the
47 48 49 50
/// app. When using [SliverAppBar.flexibleSpace], the [SliverAppBar.expandedHeight]
/// must be large enough to accommodate the [SliverAppBar.flexibleSpace] widget.
///
/// Furthermore is included functionality for stretch behavior. When
51 52
/// [SliverAppBar.stretch] is true, and your [ScrollPhysics] allow for
/// overscroll, this space will stretch with the overscroll.
53
///
54 55 56
/// The widget that sizes the [AppBar] must wrap it in the widget returned by
/// [FlexibleSpaceBar.createSettings], to convey sizing information down to the
/// [FlexibleSpaceBar].
57
///
58
/// {@tool dartpad --template=freeform}
59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140
/// This sample application demonstrates the different features of the
/// [FlexibleSpaceBar] when used in a [SliverAppBar]. This app bar is configured
/// to stretch into the overscroll space, and uses the
/// [FlexibleSpaceBar.stretchModes] to apply `fadeTitle`, `blurBackground` and
/// `zoomBackground`. The app bar also makes use of [CollapseMode.parallax] by
/// default.
///
/// ```dart imports
/// import 'package:flutter/material.dart';
/// ```
/// ```dart
/// void main() => runApp(MaterialApp(home: MyApp()));
///
/// class MyApp extends StatelessWidget {
///   @override
///   Widget build(BuildContext context) {
///     return Scaffold(
///       body: CustomScrollView(
///         physics: const BouncingScrollPhysics(),
///         slivers: <Widget>[
///           SliverAppBar(
///             stretch: true,
///             onStretchTrigger: () {
///               // Function callback for stretch
///               return;
///             },
///             expandedHeight: 300.0,
///             flexibleSpace: FlexibleSpaceBar(
///               stretchModes: <StretchMode>[
///                 StretchMode.zoomBackground,
///                 StretchMode.blurBackground,
///                 StretchMode.fadeTitle,
///               ],
///               centerTitle: true,
///               title: const Text('Flight Report'),
///               background: Stack(
///                 fit: StackFit.expand,
///                 children: [
///                   Image.network(
///                     'https://flutter.github.io/assets-for-api-docs/assets/widgets/owl-2.jpg',
///                     fit: BoxFit.cover,
///                   ),
///                   const DecoratedBox(
///                     decoration: BoxDecoration(
///                       gradient: LinearGradient(
///                         begin: Alignment(0.0, 0.5),
///                         end: Alignment(0.0, 0.0),
///                         colors: <Color>[
///                           Color(0x60000000),
///                           Color(0x00000000),
///                         ],
///                       ),
///                     ),
///                   ),
///                 ],
///               ),
///             ),
///           ),
///           SliverList(
///             delegate: SliverChildListDelegate([
///               ListTile(
///                 leading: Icon(Icons.wb_sunny),
///                 title: Text('Sunday'),
///                 subtitle: Text('sunny, h: 80, l: 65'),
///               ),
///               ListTile(
///                 leading: Icon(Icons.wb_sunny),
///                 title: Text('Monday'),
///                 subtitle: Text('sunny, h: 80, l: 65'),
///               ),
///               // ListTiles++
///             ]),
///           ),
///         ],
///       ),
///     );
///   }
/// }
///
/// ```
/// {@end-tool}
///
141
/// See also:
Ian Hickson's avatar
Ian Hickson committed
142
///
143 144
///  * [SliverAppBar], which implements the expanding and contracting.
///  * [AppBar], which is used by [SliverAppBar].
145
///  * <https://material.io/design/components/app-bars-top.html#behavior>
146
class FlexibleSpaceBar extends StatefulWidget {
147 148
  /// Creates a flexible space bar.
  ///
149
  /// Most commonly used in the [AppBar.flexibleSpace] field.
150
  const FlexibleSpaceBar({
151 152 153
    Key key,
    this.title,
    this.background,
154
    this.centerTitle,
155
    this.titlePadding,
156
    this.collapseMode = CollapseMode.parallax,
157
    this.stretchModes = const <StretchMode>[StretchMode.zoomBackground],
158 159
  }) : assert(collapseMode != null),
       super(key: key);
160

161 162 163
  /// The primary contents of the flexible space bar when expanded.
  ///
  /// Typically a [Text] widget.
164
  final Widget title;
165 166 167

  /// Shown behind the [title] when expanded.
  ///
168
  /// Typically an [Image] widget with [Image.fit] set to [BoxFit.cover].
169
  final Widget background;
170

171 172
  /// Whether the title should be centered.
  ///
173
  /// By default this property is true if the current target platform
174
  /// is [TargetPlatform.iOS] or [TargetPlatform.macOS], false otherwise.
175 176
  final bool centerTitle;

177 178 179 180 181
  /// Collapse effect while scrolling.
  ///
  /// Defaults to [CollapseMode.parallax].
  final CollapseMode collapseMode;

182 183 184 185 186
  /// Stretch effect while over-scrolling,
  ///
  /// Defaults to include [StretchMode.zoomBackground].
  final List<StretchMode> stretchModes;

187 188 189 190 191 192 193 194 195
  /// Defines how far the [title] is inset from either the widget's
  /// bottom-left or its center.
  ///
  /// Typically this property is used to adjust how far the title is
  /// is inset from the bottom-left and it is specified along with
  /// [centerTitle] false.
  ///
  /// By default the value of this property is
  /// `EdgeInsetsDirectional.only(start: 72, bottom: 16)` if the title is
196
  /// not centered, `EdgeInsetsDirectional.only(start: 0, bottom: 16)` otherwise.
197 198
  final EdgeInsetsGeometry titlePadding;

199 200 201 202
  /// Wraps a widget that contains an [AppBar] to convey sizing information down
  /// to the [FlexibleSpaceBar].
  ///
  /// Used by [Scaffold] and [SliverAppBar].
203 204 205 206 207 208 209 210 211 212 213
  ///
  /// `toolbarOpacity` affects how transparent the text within the toolbar
  /// appears. `minExtent` sets the minimum height of the resulting
  /// [FlexibleSpaceBar] when fully collapsed. `maxExtent` sets the maximum
  /// height of the resulting [FlexibleSpaceBar] when fully expanded.
  /// `currentExtent` sets the scale of the [FlexibleSpaceBar.background] and
  /// [FlexibleSpaceBar.title] widgets of [FlexibleSpaceBar] upon
  /// initialization.
  ///
  /// See also:
  ///
214 215
  ///  * [FlexibleSpaceBarSettings] which creates a settings object that can be
  ///    used to specify these settings to a [FlexibleSpaceBar].
216 217 218 219 220 221 222 223
  static Widget createSettings({
    double toolbarOpacity,
    double minExtent,
    double maxExtent,
    @required double currentExtent,
    @required Widget child,
  }) {
    assert(currentExtent != null);
224
    return FlexibleSpaceBarSettings(
225 226 227 228 229 230 231 232
      toolbarOpacity: toolbarOpacity ?? 1.0,
      minExtent: minExtent ?? currentExtent,
      maxExtent: maxExtent ?? currentExtent,
      currentExtent: currentExtent,
      child: child,
    );
  }

233
  @override
234
  _FlexibleSpaceBarState createState() => _FlexibleSpaceBarState();
235 236 237
}

class _FlexibleSpaceBarState extends State<FlexibleSpaceBar> {
238
  bool _getEffectiveCenterTitle(ThemeData theme) {
239 240
    if (widget.centerTitle != null)
      return widget.centerTitle;
241 242 243
    assert(theme.platform != null);
    switch (theme.platform) {
      case TargetPlatform.android:
244
      case TargetPlatform.fuchsia:
245 246
      case TargetPlatform.linux:
      case TargetPlatform.windows:
247 248
        return false;
      case TargetPlatform.iOS:
249
      case TargetPlatform.macOS:
250 251
        return true;
    }
252
    return null;
253 254
  }

255
  Alignment _getTitleAlignment(bool effectiveCenterTitle) {
256
    if (effectiveCenterTitle)
257
      return Alignment.bottomCenter;
258 259 260 261
    final TextDirection textDirection = Directionality.of(context);
    assert(textDirection != null);
    switch (textDirection) {
      case TextDirection.rtl:
262
        return Alignment.bottomRight;
263
      case TextDirection.ltr:
264
        return Alignment.bottomLeft;
265 266 267 268
    }
    return null;
  }

269
  double _getCollapsePadding(double t, FlexibleSpaceBarSettings settings) {
270 271 272 273 274 275 276
    switch (widget.collapseMode) {
      case CollapseMode.pin:
        return -(settings.maxExtent - settings.currentExtent);
      case CollapseMode.none:
        return 0.0;
      case CollapseMode.parallax:
        final double deltaExtent = settings.maxExtent - settings.minExtent;
277
        return -Tween<double>(begin: 0.0, end: deltaExtent / 4.0).transform(t);
278 279 280 281
    }
    return null;
  }

282 283
  @override
  Widget build(BuildContext context) {
284 285
    return LayoutBuilder(
      builder: (BuildContext context, BoxConstraints constraints) {
286
        final FlexibleSpaceBarSettings settings = context.dependOnInheritedWidgetOfExactType<FlexibleSpaceBarSettings>();
287 288 289 290
        assert(
          settings != null,
          'A FlexibleSpaceBar must be wrapped in the widget returned by FlexibleSpaceBar.createSettings().',
        );
291

292
        final List<Widget> children = <Widget>[];
293

294 295 296 297
        final double deltaExtent = settings.maxExtent - settings.minExtent;

        // 0.0 -> Expanded
        // 1.0 -> Collapsed to toolbar
298
        final double t = (1.0 - (settings.currentExtent - settings.minExtent) / deltaExtent).clamp(0.0, 1.0) as double;
299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322

        // background
        if (widget.background != null) {
          final double fadeStart = math.max(0.0, 1.0 - kToolbarHeight / deltaExtent);
          const double fadeEnd = 1.0;
          assert(fadeStart <= fadeEnd);
          final double opacity = 1.0 - Interval(fadeStart, fadeEnd).transform(t);
          if (opacity > 0.0) {
            double height = settings.maxExtent;

            // StretchMode.zoomBackground
            if (widget.stretchModes.contains(StretchMode.zoomBackground) &&
              constraints.maxHeight > height) {
              height = constraints.maxHeight;
            }

            children.add(Positioned(
              top: _getCollapsePadding(t, settings),
              left: 0.0,
              right: 0.0,
              height: height,
              child: Opacity(
                opacity: opacity,
                child: widget.background,
323
              ),
324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343
            ));

            // StretchMode.blurBackground
            if (widget.stretchModes.contains(StretchMode.blurBackground) &&
              constraints.maxHeight > settings.maxExtent) {
              final double blurAmount = (constraints.maxHeight - settings.maxExtent) / 10;
              children.add(Positioned.fill(
                child: BackdropFilter(
                  child: Container(
                    color: Colors.transparent,
                  ),
                  filter: ui.ImageFilter.blur(
                    sigmaX: blurAmount,
                    sigmaY: blurAmount,
                  )
                )
              ));
            }
          }
        }
344

345 346 347 348 349 350 351
        // title
        if (widget.title != null) {
          final ThemeData theme = Theme.of(context);

          Widget title;
          switch (theme.platform) {
            case TargetPlatform.iOS:
352
            case TargetPlatform.macOS:
353 354 355
              title = widget.title;
              break;
            case TargetPlatform.android:
356 357 358
            case TargetPlatform.fuchsia:
            case TargetPlatform.linux:
            case TargetPlatform.windows:
359 360 361 362
              title = Semantics(
                namesRoute: true,
                child: widget.title,
              );
363
              break;
364 365 366 367 368 369
          }

          // StretchMode.fadeTitle
          if (widget.stretchModes.contains(StretchMode.fadeTitle) &&
            constraints.maxHeight > settings.maxExtent) {
            final double stretchOpacity = 1 -
370
              (((constraints.maxHeight - settings.maxExtent) / 100).clamp(0.0, 1.0) as double);
371 372 373 374 375 376 377 378
            title = Opacity(
              opacity: stretchOpacity,
              child: title,
            );
          }

          final double opacity = settings.toolbarOpacity;
          if (opacity > 0.0) {
379
            TextStyle titleStyle = theme.primaryTextTheme.headline6;
380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401
            titleStyle = titleStyle.copyWith(
              color: titleStyle.color.withOpacity(opacity)
            );
            final bool effectiveCenterTitle = _getEffectiveCenterTitle(theme);
            final EdgeInsetsGeometry padding = widget.titlePadding ??
              EdgeInsetsDirectional.only(
                start: effectiveCenterTitle ? 0.0 : 72.0,
                bottom: 16.0,
              );
            final double scaleValue = Tween<double>(begin: 1.5, end: 1.0).transform(t);
            final Matrix4 scaleTransform = Matrix4.identity()
              ..scale(scaleValue, scaleValue, 1.0);
            final Alignment titleAlignment = _getTitleAlignment(effectiveCenterTitle);
            children.add(Container(
              padding: padding,
              child: Transform(
                alignment: titleAlignment,
                transform: scaleTransform,
                child: Align(
                  alignment: titleAlignment,
                  child: DefaultTextStyle(
                    style: titleStyle,
402 403 404 405 406 407 408 409 410
                    child: LayoutBuilder(
                      builder: (BuildContext context, BoxConstraints constraints) {
                        return Container(
                          width: constraints.maxWidth / scaleValue,
                          alignment: titleAlignment,
                          child: title,
                        );
                      }
                    ),
411 412 413 414 415 416 417 418 419 420
                  ),
                ),
              ),
            ));
          }
        }

        return ClipRect(child: Stack(children: children));
      }
    );
421
  }
422 423
}

424 425 426 427
/// Provides sizing and opacity information to a [FlexibleSpaceBar].
///
/// See also:
///
428
///  * [FlexibleSpaceBar] which creates a flexible space bar.
429 430 431 432 433
class FlexibleSpaceBarSettings extends InheritedWidget {
  /// Creates a Flexible Space Bar Settings widget.
  ///
  /// Used by [Scaffold] and [SliverAppBar]. [child] must have a
  /// [FlexibleSpaceBar] widget in its tree for the settings to take affect.
434 435 436
  ///
  /// The required [toolbarOpacity], [minExtent], [maxExtent], [currentExtent],
  /// and [child] parameters must not be null.
437
  const FlexibleSpaceBarSettings({
438
    Key key,
439 440 441
    @required this.toolbarOpacity,
    @required this.minExtent,
    @required this.maxExtent,
442 443
    @required this.currentExtent,
    @required Widget child,
444 445 446 447 448 449 450 451
  }) : assert(toolbarOpacity != null),
       assert(minExtent != null && minExtent >= 0),
       assert(maxExtent != null && maxExtent >= 0),
       assert(currentExtent != null && currentExtent >= 0),
       assert(toolbarOpacity >= 0.0),
       assert(minExtent <= maxExtent),
       assert(minExtent <= currentExtent),
       assert(currentExtent <= maxExtent),
452
       super(key: key, child: child);
453

454
  /// Affects how transparent the text within the toolbar appears.
455
  final double toolbarOpacity;
456 457

  /// Minimum height of the resulting [FlexibleSpaceBar] when fully collapsed.
458
  final double minExtent;
459 460

  /// Maximum height of the resulting [FlexibleSpaceBar] when fully expanded.
461
  final double maxExtent;
462 463 464 465

  /// If the [FlexibleSpaceBar.title] or the [FlexibleSpaceBar.background] is
  /// not null, then this value is used to calculate the relative scale of
  /// these elements upon initialization.
466
  final double currentExtent;
467 468

  @override
469
  bool updateShouldNotify(FlexibleSpaceBarSettings oldWidget) {
470 471 472 473
    return toolbarOpacity != oldWidget.toolbarOpacity
        || minExtent != oldWidget.minExtent
        || maxExtent != oldWidget.maxExtent
        || currentExtent != oldWidget.currentExtent;
474
  }
475
}